Create a blank/orphan Git branch

Many basic Git use cases involve a main branch with feature branches periodically merged into the main branch. 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.

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.

From the repo directory create a blank Git branch:

git switch --orphan gh-pages

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 the .git/ directory, which should not be disturbed.

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). Assume wanted files for the blank gh-pages branch are in docs/ on main branch.

copy over the files to gh-pages

git checkout main -- docs/

git commit -am "moved docs"

Upload files

1. push the documentation

   git push -u origin gh-pages

2. Enable the documentation builds from github.invalid/username/myrepo/settings → GitHub Pages under Source select gh-pages.

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

Once everything is working, the old docs/ folder isn’t needed.