Static site with separate source branch

This post is dedicated to the use-case where there are 2 different branches in a project. Typically one branch is for the source files, and one is for the generated output files for publishing. This use-case matches the way in which this website is currently hosted, via GitHub pages. Then the master branch is eventually published, whereas other branches remain in the repositories only.

Typically generated websites have a dedicated distribution directory like dist in which the generated files end up. This use-case covers a different use-case where the generated .html files end up next to the .adoc source files.

Setup

Just some prepwork is needed to get this working.

Branches

We have two seperate branches, one for the source files src, and one for the generated output for publishing master. As there is little to no correlation between both branches, the --orphan option can be used during the git checkout to prevent branches from forcefully bing associated with each other.

Git branches

$ git branch -a
  master
* src
  remotes/origin/master
  remotes/origin/src

Gitignore

Part of the trick is not to ignore the output .html files in the src branch, to make it available for the git commands. The source .adoc files can be ignored from out of the master branch, but that is mainly to reduce the effect of those oops moments.

Doing the transfer dance

To successfully generate the output files and have them end up in the master branch we need to do a little dance. The actual transfer is being done via git stash.

From source to stash

If you are unexperienced with Git, just know you can always run git status to get an overview of the current state of the repository.

Checkout src branch

$ git checkout src

Generate output files

$ make html
asciidoctor index.adoc
asciidoctor posts/index.adoc
asciidoctor posts/2016-08-02-static-site-with-separate-source-branch.adoc

Put output files in stash

$ git add *.html **/*.html

From cached to stash

$ git stash

From stash to master

Checkout master branch

$ git checkout master

Remove previous generated files

$ git rm *.html **/*.html

Apply stash

$ git stash pop

The new and modified files are automatically added as staged in git, so making a commit will do.

Commit the new files

$ git commit -m "chore: site update"

If your use-case covers more or different files than the HTML files in this example, then replace the *.html **/*.html globbing patterns with different patterns that match your output files.