More recent versions of git have an alternative to the git symbolic-ref method that Chandru explained. This avoids having to use the lower level commands.
git checkout --orphan gh-pages
git rm -rf .
More recent versions of git have an alternative to the git symbolic-ref method that Chandru explained. This avoids having to use the lower level commands.
git checkout --orphan gh-pages
git rm -rf .
You might find this tutorial useful:
Setup GitHub Pages "gh-pages" branch and "master" branch as subfolders of a parent project folder ("grandmaster").
To me this approach seems simpler then doing a git checkout gh-pages each time you want to edit your gh-pages content. Let me know what you think ^_^
Edit: I updated the tutorial link - thanks @Cawas. The old tutorial (not recommended) was https://gist.github.com/825950
Videos
Github pages like to publish from a separate branch called gh-pages.
Am I meant to keep the documentation for my project in a separate branch permanently? I've never used git that way.
Why not keep it in a sub-directory of the master branch?
» npm install gh-pages
This is something we've been it with on the Smithay repository, and I'm thinking this might be of interest to others, so sharing what we found in case that helps. :)
For some time the Smithay git repo was becoming very slow to clone, and digging into this we realized it was almost 450 MB in size. It ended up that almost all of that space was taken by our gh-pages branch, on which our CI script uploads the api docs for Smithay and its public dependencies.
As it appears, Smithay is kinda hitting a few bad cases so that rustdoc output ends up pretty large: the target/doc/ folder we serve on github pages is ~220 MB in size. Keeping git history on such large content, generating huge diffs at each commit, really made the git repo blow up both in disk size and in processing time required to clone it.
As a first-step measure, we changed the CI script to overwrite the gh-pages branch at every run, rather than just appending a new commit. We use this gh-pages action, so it was just a matter of adding a force_orphan: true parameter.
Turns out that this improved the situation a lot: when it no longer needs to keep history, git manages to compress that 220MB of documentation very well, and now the whole Smithay git repo is only ~15 MB!
So if you're using gh-pages to host your documentation, you might want to check if you can have some similar gains on this side. :)