Contents
workflow gh – pages #
Setting up GitHub Pages may seem a little scary. Here's how the GitHub documentation suggests to configure the gh-pages branch:
$ cd / path / to / fancypants
$ symbolic git-ref HEAD refs / heads / gh-pages
$ rm .git / index
$ git clean -fdx
$ echo "My GitHub page"> index.html
$ git add.
$ git commit -a -m "First validation page"
$ git push origin gh-pages
This creates a new gh-pages branch with nothing, then adds a file and pushes it to GitHub. Now you have two branches with different content:
master – the code of your project
gh-pages – the website of your project, hosted by GitHub using GitHub Pages
In Tip: git checkout specific files from another branch Nicolas Gallagher explains how to add or update files on gh-pages from the master branch ( this assumes you are working as a master):
$ git add.
$ git status // to see what changes will be made
$ git commit -m "A descriptive validation message"
$ git push // send master branch changes to GitHub
$ git checkout gh-pages // go to gh-pages
$ git checkout master – file1.txt file2.ext file3.ext // add / update file1-3 with changes to the master branch
$ git commit -m "Update master file 1-3"
$ git push // push the gh-pages branch changes to the GitHub pages
$ git checkout master // return to the master branch
Lea Verou generally reproduces the branch changes of the gh pages, and covers the workflow in Lets you easily keep the gh pages synchronized with the master . To do this, replace the git checkout master and the commands git commit seconds with git rebase master:
$ git add.
$ git status // to see what changes will be made
$ git commit -m A descriptive validation message & # 39;
$ git push // send master branch changes to GitHub
$ git checkout gh-pages // go to gh-pages
$ git rebase master // update the gh-pages with the master
$ git push // push the gh-pages branch changes to the GitHub pages
$ git checkout master // return to the master branch
By rebasing, all validations on the main branch (and their validation messages) are applied to the gh-pages branch.
Using a post-commit hook #
Paul Irish contributed to this post-commit hook snippet to automate Lea's workflow (save as .git / hooks / post-commit in your Git repo):
#! / bin / sh
git checkout gh-pages
git rebase master
git checkout master
This allows you to replace the last five steps of Lea's workflow with git push –all. Nice!
Fusion via git push #
Nicolas Gallagher came across another way to merge the master into gh-pages in GitHub Help on Remote Controls – you can push your local branch branch to the gh branch -pages on GitHub:
git push -f master of origin: gh-pages
This would replace the last four stages of Lea's workflow. Your main branch should be a mirror or a subset of the remote gh-pages branch, and that means that if you have the gh-pages branch locally, it will now be behind the GitHub version. However, using this method, you can essentially ignore (or not even have) the gh-pages branch locally.
Thanks to Nicolas Gallagher and Paul Irish for saying this (several times)
The -f (force) fact that thrust occurs even though the gh-pages branch is no longer recent (avoiding a " rapid non-advanced updates were rejected " error). When using this method you should not be working on gh pages at all, so the only time this will happen is if someone else pushes the changes in front of you. In this case, you can merge these changes into your local master and push the gh-pages branch again. This is the shell script to force the pressure that uses the Web Forward .
Setting up GitHub pages using your current content #
However, I wanted to have everything in gh-pages and no master branch, because the project page is essentially the project. Ideally, I would simply rename the master branch to gh-pages ( possibly $ git remote rename master gh-pages ), but I was concerned that this would cause problems with GitHub. Being lazy I simply branched out instead.
$ cd / path / to / diveintohtml5
$ git checkout -b gh-pages
$ git push origin gh-pages
It worked well even with the CNAME-based service, but a typical git pull failed with this error:
$ git sweater
You asked me to shoot without telling me which branch you
want to merge with, and & # 39; branch.gh-pages.merge & # 39; in
your configuration file does not tell me either. Please
specify the branch you want to use on the command line and
try again (eg, 'git pull
See git-pull (1) for more details.
If you often merge with the same branch, you may want to
use something like the following in your configuration file:
[branch “gh-pages”]
remote =
merge =
[Remote"
url =
fetch =
See git-config (1) for more details.
I corrected this by editing the .git / config file of the repo and adding:
[branch “gh-pages”]
remote = origin
merge = refs / heads / gh-pages
As Ryan Fitzer confirms in Easy Syncing of GitHub Pages (detailing what he did for a "default" configuration), I could have avoid this by following the instructions of GitHub, and replace echo "My GitHub"> index.html with git merge master.
Deletion of the master branch on GitHub #
This step could be messy, so I first checked with GitHub support first (thanks Petros!). There are three things you must do:
Make the gh branch your default branch on GitHub: Repository Administration> Options> Set the "Default Direction" setting to something other than the master
Delete the master branch on GitHub using $ git push origin: master (which, I think, just sends a null branch to replace the remote master branch)
Delete the master branch in your local repo (once you've checked everything works!) Using $ git branch -d master
After that, I ended up with a gh-pages branch on GitHub and everything (except html5doctor.github.com/diveintohtml5 ) works as expected. I do not know why the default GitHub Pages address fails, but since we use CNAME to serve on a different domain, this is not a problem for us.
The support of GitHub also had this good advice:
First of all, whenever you are not sure of something, you can try to do it after you have cloned and recovered while locally as a backup . If something goes wrong, you can iron your deposit.
Conclusion #
I hope that GitHub adds management options to choose the branch to use for GitHub pages (so you can choose the master), and to add CNAME information (the addition a repo file is inelegant). I also hope that they update the GitHub Pages documentation to cover the above configurations.
In the meantime, if you have a repo, you want to use gh pages using CNAME ( and not using the URL github.com), and you have no Separating the master and gh-pages branches, moving your master repo to gh-pages could be a good way to simplify things.
If you have comments or comments, contact me via Twitter (@boblet) or Google+ (Oli Studholme) .
