Skip to content

Instantly share code, notes, and snippets.

@matt-riley
Forked from chrisjacob/README.md
Created October 13, 2013 18:26
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save matt-riley/6965607 to your computer and use it in GitHub Desktop.
Save matt-riley/6965607 to your computer and use it in GitHub Desktop.

Intro

Setup GitHub Pages "gh-pages" branch as a subfolder within the "master" project on your local checkout.

IMPORTANT

If you plan on switching between different branches (e.g. git checkout master-experiment then revert back with git checkout master) you will loose your child folder from this tutorial (because it's in your .gitignore and is not part of your master branch).

For this reason I prefer to: Setup GitHub Pages "gh-pages" branch and "master" branch as subfolders of a parent project folder ("grandmaster")

The Result

See "master" branch: https://github.com/chrisjacob/parent

See "gh-pages" branch: https://github.com/chrisjacob/parent/tree/gh-pages

The final folder structure on my local system is:

/parent
/parent/.git # checkout of "master" branch
/parent/.gitignore # ignores child/ folder
/parent/README.markdown
/parent/child
/parent/child/.git # checkout of "gh-pages" branch (+ removed "master" branch)
/parent/child/index.html
/parent/child/README.textile

The Process

A note for GitHub novices - replace "chrisjacob" with your own GitHub username.

A note for Terminal novices - you don't need to enter the "ichris:Sites $ " parts of the code listed below. ^_^

Visit GitHub and create a new repository with the project name "parent" https://github.com/repositories/new

Open Terminal.app, initialise a new git repository for the project and push the "master" branch to GitHub.

ichris:~ $ cd Sites/
ichris:Sites $ mkdir parent
ichris:Sites $ cd parent/
ichris:parent $ git init
ichris:parent $ echo "# Parent README file" > README.markdown
ichris:parent $ git add .
ichris:parent $ git commit -m "Parent README added"
ichris:parent $ git remote add origin git@github.com:chrisjacob/parent.git
ichris:parent $ git push origin master

Refresh your projects "master" branch page on GitHub to see the committed files https://github.com/chrisjacob/parent

Auto generate a GitHub Pages branch, with some default content https://github.com/chrisjacob/parent/pages/create

Or follow these steps to get to the generator page:

  1. Go to the projects Admin page on GitHub https://github.com/chrisjacob/parent/admin

  2. Check the "GitHub Pages" checkbox

  3. A popup will ask you to "Activate GitHub Pages" - click the big "Automatic GitHub Page Generator" button

Check that your GitHub Pages page has been built and is available http://chrisjacob.github.com/parent/

Back in Terminal.app, setup a "child" folder for your "gh-pages" branch and make sure the "master" branch ignore's this folder. Commit this to "master".

ichris:parent $ mkdir child
ichris:parent $ echo "child/" > .gitignore
ichris:parent $ git add .
ichris:parent $ git commit -m ".gitignore child/ folder (contains gh-pages branch)"
ichris:parent $ git push origin master

Change into the "child" folder, clone your repo, checkout the "gh-pages" branch, list the files (should have "index.html" and ".git") and then remove the "master" branch to avoid any confusion. Last step is to check that "master" branch was removed and only "gh-pages" is listed.

ichris:child $ cd child/
ichris:child $ git clone git@github.com:chrisjacob/parent.git .
ichris:child $ git checkout origin/gh-pages -b gh-pages
ichris:child $ ls -la
ichris:child $ git branch -d master
ichris:child $ git branch

You will probably get a warning when deleting the "master" branch... don't worry about it ^_^

Lets add a "README.textile" file to the gh-pages branch - notice parents/ README has the extension .markdown; I've chosen .textile here to demonstrate that these two repositories don't "see" each others files.

ichris:child $ echo "h1. Child README file" > README.textile
ichris:child $ git add .
ichris:child $ git commit -m "Child README added"

Now push to the "gh-pages" branch

ichris:child $ git push origin gh-pages

Visit your projects "gh-pages" branch page on GitHub to see the committed files https://github.com/chrisjacob/parent/tree/gh-pages

Change directory back to the parent/ folder, make sure it doesn't have the "gh-pages" branch, make sure it has ignored the child/ folder and all it's content.

ichris:child $ cd ../
ichris:parent $ git branch
ichris:parent $ git status

If everything has gone well you can now work in parent/ and commit to "master". You can also cd into child/, make changes and commit to "gh-pages".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment