Create a blank/orphan Git branch

Many basic Git use cases involve a main branch master with feature branches periodically merged into master. For certain purposes, totally distinct branch without a common history can exist in the same Git repo. One of the most common uses of this is for documentation. For example, GitHub will build a website from the gh-pages branch.

1. setup blank Git branch

Do NOT force push during this procedure, you may accidentally erase years of work!

This example assumes you want to create a gh-pages empty branch for documentation on GitHub, but will of course work for other purposes too.

  1. change to the repo directory, e.g. cd ~/myprog
  2. create a blank Git branch

    git checkout --orphan gh-pages
  3. remove the unneeded files from this branch (by default, all existing files are staged from the previous branch)

    git rm --cached -r .
    
    git clean -id

    This leaves you with nothing but the .git/ directory, which should not be disturbed.

2. copy documentation files

What happens next depends on if your documentation files were already added to another branch (tracked) or were not added to Git (untracked).

Wanted files for the blank gh-pages branch are in docs/ on master branch.

copy over the files to gh-pages

git checkout master -- docs/

git commit -am "moved docs from master"

3. Upload files to GitHub

  1. push the documentation

    git push -u origin gh-pages
  2. Enable the documentation builds from https://github.com/username/myrepo/settings → GitHub Pages under Source select gh-pages.

  3. In a few minutes, the webpages at https://username.github.io/myrepo/ should be active.

Once you’re sure everything is working, you can remove the docs/ folder from its old location.