GithubPagesPublisher refactor

[dairiki]

What started out as work to support explicitly specifying a branch to push to (#978) has turned into this.

Issue(s) Resolved

Fixes #978

Related Issues / Links

Associated doc PR: lektor/lektor-website#340

Description of Changes

• Wrote at least one-line docstrings (for any new functions)
• Added unit test(s) covering the changes (if testable)
• Link to corresponding documentation pull request for getlektor.com

• Add support for specifying which branch to push to by specifying a branch query param on the target URL.
• Issues a warning when defaulting to pushing to the master branch for a user or organization pages site. (Recently created user or organization pages repositories default to using the main branch.)
• [Optimization] Do a shallow fetch when fetching the current target branch from upstream.
• [Optimization] Avoid copying the HTML output files to a new scratch directory.
• Refactor/cleanup of some code in lektor.publisher.

Question

Is it worth adding an option that would prevent keeping any git history of the deployed site?

If one doesn't care about preserving the history of the deployed gh-pages site, one can just force-push the new
content to the target branch. This avoids having to fetch the existing branch from upstream, saving network bandwidth.

In general, I'm not sure how useful it is to keep a history of the deployed site anyway.

Of pertinence, I just noticed that our docs currently say: "The way this is implemented in Lektor currently is that Lektor will force-push a website into a repository of choice."
This appears not to be what our current code does. Current code appears to alway creates a new commit (with the previous branch head as its parent) preserving all previously published version of the site's HTML in the git history. (No force push involved.)
Later on the same page, our docs say: "The way this deployment support works is that it commits a new commit into a temporary location and pushes it into the gh-pages or master branch depending on the name of the repository." (which is not quite the same thing.)

[yagebu]

For ghpages, I think it's preferable to force-push an orphaned commit instead of having some history of deployed pages. Since that would be consistent with the current documentation (but not the implementation), I think changing it to work like that would be fine.

[dairiki]

For ghpages, I think it's preferable to force-push an orphaned commit instead of having some history of deployed pages. Since that would be consistent with the current documentation (but not the implementation), I think changing it to work like that would be fine.

I tend to agree that force-push should be the preferred behavior, however, I worry about changing the default behavior without warning (other than in the changelog). In the rare cases where someone does want to preserve the history of the deployed HTML, changing to force-push will delete any such accumulated history.

The safer way to make the change would be to add a preserve_history=false option that would enable the force-push behavior. The default behavior would be left unchanged, but a warning would be issued that the default behavior will be changed in future and that users should add an explicit preserver_history=true if they want to keep the non-force-push behavior.

Is it worth the effort to do that?