Github - syncing the gh-pages branch

gh-pages branch is used with github repos as a front page for the repository. It is used to display demos, documentations, a stylized readme, and more. Some difficulties arise when the gh-pages branch needs to reference or contain files that originate from the master branch.

Work flows

Different work flow suggestions exist (see here, and there). These suggestions work, but I find that syncing the gh-pages so it would contain the latest code from master to be a bad practice. The DRY principle should be imposed here- each file should either be on master or gh-pages branch. Not both, and not resorting to use gh-pages as the master branch.

A different approach

Create the gh-pages as an orphan branch (also Github's recommendation):

1
2
git checkout --orphan gh-pages
git rm -rf .

dealing with special files

  1. files from master that need to be referenced from gh-pages. For example- A demo page for a js client side widget. The demo should reference the distribution .js files. The easiest way the achieve this is to keep the distribution files in master, while inside gh-pages, use a 3rd party CDN to reference them such as RawGit.

  2. files that get generated in master branch, but belong to gh-pages. For example- documentation files that are auto generated by a tool that scans the source files. This is a bit more tricky:

The first time the files get generated on master, there's no problem switching to the gh-pages branch, and then stage and commit them. Trying to do so in the second time gets: 
1
error: The following untracked working tree files would be overwritten by checkout:

assuming the files are in a folder named documentation, the way around this is:

1
2
3
4
git add documentation
git stash
git checkout gh-pages
git checkout stash@{0} -- documentation/

using git checkout stash@{0} is preferred here over git stash pop, since the stash command will result in conflicts which you will need to resolve manually (note the stash command doesn't take --theirs).