Enhancement: Optionally do not delete all contents of gh-pages branch

[jnehlmeier]

Currently the Github pages plugin deletes everything in the gh-pages branch. It would be nice if an optional behavior could be defined in which the plugin only deletes the folders/files defined in the copy spec (or alternatively allow defining a target folder, instead of always using /)

This would solve the following use cases:

• In a multi module project each module can have the plugin applied and can define its own files to be pushed (e.g. each module can push its JavaDoc without deleting everything pushed by other modules)
• You might want to keep already pushed JavaDoc of older releases on the gh-pages branch, e.g.

githubPages {
        repoUri = '...'
        commitMessage "Upload JavaDoc: $project.name/$project.version"
        pages {
            from javadoc.outputs.files
            into "docs/$project.name/$project.version"
        }
    }

• The gh-pages branch might contain a full fledged Jekyll website which grows over time (maybe also contains binary data). In order to keep the master branch small for GIT clones you don't want to have that website stored in src/main/gh-pages (which by default is part of the pages { ... } copy spec)

[aadamovich]

+1

[ajoberstar]

Just deleting what's in the copy spec ends up meaning we're just copying rather than "syncing", so that won't work. Some type of target dir might make the most sense. Not sure what the best way to expose that is though.

• You can resolve the multi-project use case by applying the plugin once and referencing the other projects. This would result in only one push, which seems beneficial.
• The multi-versions of JavaDoc seems the most compelling to me.
• For the final use case, you would still pay the cloning penalty anytime you ran publishGhPages. Though, I guess it minimizes the scope of when that applies.

[ajoberstar]

Would the option added in #102 resolve this for you?

[jnehlmeier]

For releases it is probably ok. However if you want to publish SNAPSHOT javadoc you would always copy javadoc to the same location and in that case you actually want to replace the old one with the new one. If you don't do so you would end up with garbage in the branch (e.g. when classes are renamed/moved/deleted during development)

Avoiding that garbage in such a scenario is probably only possible by introducing the target folder concept and allowing only the target folder to be cleaned instead of the whole branch.

[ajoberstar]

Makes sense.