69

I have a repo on GitHub. Recently I have discovered GitHub's pages and I want to use them.
I would like to create this new branch and then, when I need to, either commit on master branch or on gh-pages branch.

How can I do this? Do I have to create another folder inside my repo?

rubik
  • 8,814
  • 9
  • 58
  • 88
  • `origin` isn't a branch, it's a remote. You mean `master`. – Dustin Jan 20 '11 at 18:43
  • Ah yes, you're right. I'll edit. – rubik Jan 21 '11 at 06:15
  • See [my related answer](http://stackoverflow.com/a/29616287/946850) and a [writeup](http://krlmlr.github.io/git-subbranch) for a solution that consists of creating a clone in a subdirectoy of the working copy. – krlmlr Apr 13 '15 at 22:57
  • 2
    You [no longer need a gh-pages branch](http://stackoverflow.com/questions/4750520/git-branch-gh-pages/39024454#39024454). – Dan Dascalescu Aug 19 '16 at 00:05
  • @DanDascalescu why not post an own answer in addition to all your comments here. What is your link for, it links to the question here? – Timo Jan 08 '22 at 20:45
  • 1
    @Timo: I see why you're confused. I had actually posted an answer here, and the link is to *that answer* (note the anchor id after the `#`), but @Martijn Pieters [deleted it](https://imgur.com/a/cPlAB72), and [SE has been repeatedly refusing](https://meta.stackexchange.com/questions/340714/deletion-notification) to implement any notifications about deleted answers, so I had no idea it was deleted. Anyway, [another answer here](https://stackoverflow.com/a/45220305/1269037) still points to the simpler method of just telling GitHub which folder to serve the pages from; no special branch needed. – Dan Dascalescu Jan 11 '22 at 10:53

9 Answers9

41

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 .
Arrowmaster
  • 9,143
  • 2
  • 28
  • 25
  • I don't get this. How is this anything related to `symbolic-ref`? – cregox Mar 24 '11 at 15:52
  • @Cawas Previously the only way to do this was to use `git symbolic-ref` like in Chandru's answer. Now `git checkout --orphan` is the proper way. – Arrowmaster Mar 24 '11 at 19:01
  • but, @arrow, when I see the docs about both they don't seem to do the same thing at all! about `symbolic-ref` it says "*symbolic links are now deprecated and symbolic refs are used by default*" while about `orphan` it says "*This can be useful when you want to publish the tree from a commit without exposing its full history*". To me that's the opposite. You're creating a completely separated branch instead of making one the mirror of the other! – cregox Mar 24 '11 at 19:36
  • @Cawas `git symbolic-ref` is a plumbing command used every time a ref is updated to point to a different commit. This includes every time `git checkout` is used. It is not ment to be called manually which is why `git checkout --orphan` was added. – Arrowmaster Mar 25 '11 at 08:58
  • So, `orphan` actually adopts the orphan rather than creates one, is that it? and it does same thing than `symbolic-ref`, except we have to call it? This would probably be much easier explained through a good example. – cregox Mar 25 '11 at 14:35
  • 4
    @Cawas `--orphan` takes the start-point (HEAD if not specified) and creates a new branch with no history from that point. The additional `git rm -rf .` in my answer is to remove the previous content for when you want the branch to start with no content at all. When you run `git symbolic-ref HEAD refs/heads/gh-pages` when gh-pages does not exist yet, it puts the repo in a state similar to right after `git init` before the first commit is made, so the following commit will not have a parent. `--orphan` was added for that very specific use case of `symbolic-ref`, but not to replace other uses. – Arrowmaster Mar 25 '11 at 20:35
  • Oh ok! I see now what you meant. Thanks for the explicit explanation! So, if I got this right, the *symbolic link* created by `symbolic-ref` is actually removed by one of the 2 subsequent commands. – cregox Mar 25 '11 at 21:52
  • @Cawas No there is no *symbolic link* involved, that is the old way. Go into a repository and try `cat .git/HEAD` and `cat .git/refs/heads/master`. Those files are created by `git symbolic-ref`. The first normally just references another (except when you have a detached HEAD) while the other will point to a specific commit SHA1. – Arrowmaster Mar 25 '11 at 22:03
  • It's not the file system's *symbolic link* per say, but it behaves like it, inside git. And it is a **link** nevertheless. Same concept, isn't it not? I see how my comment was confusing, and cool thing analyzing the .git/ files. Never did it before! :) – cregox Mar 25 '11 at 22:34
  • You also might want to `git clean -df`, because there may be files in the working-directory that weren't currently tracked (i.e. `.gitignore`'d files), that were not removed by `git rm` for that reason, but will *now* be attended to due to the removal of a possible `.gitignore`. – ELLIOTTCABLE Jan 31 '13 at 08:13
34

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

Twenty
  • 5,234
  • 4
  • 32
  • 67
Chris Jacob
  • 11,878
  • 7
  • 47
  • 42
  • 1
    @rubik it's actually better to use the second suggestion from the same author: https://gist.github.com/833223 – cregox Mar 24 '11 at 15:53
  • 1
    GitHub has just enabled using [any branch and directory as the source for the docs](https://github.com/blog/2228-simpler-github-pages-publishing). You no longer have to use `gh-pages`. – Dan Dascalescu Aug 18 '16 at 17:42
  • @DanDascalescu It's not true. You can only use the master branch, or the master branch's docs folder, or gh-pages. Not "any" branch. Those are the only 3 possibilities as of April 2020. – Vadorequest Apr 04 '20 at 09:45
12

On your local clone do,

git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index 
git clean -fdx

Then, git checkout gh-pages and write your pages. git push origin gh-pages when you're ready to publish the pages.

Chandra Sekar
  • 10,683
  • 3
  • 39
  • 54
  • Yes, but where do I put my pages? How does git know what pages to put in gh-pages? – rubik Jan 20 '11 at 19:18
  • 3
    `git checkout gh-pages` means you've switched to the branch named 'gh-pages'. Any change you commit to this branch is picked up by github to build your github pages. To switch back to the 'master' branch (presumably your source code), do `git checkout master`. – Chandra Sekar Jan 21 '11 at 04:19
  • related: http://stackoverflow.com/questions/847609/create-a-git-symbolic-ref-in-remote-repository – cregox Mar 28 '11 at 20:31
  • 1
    GitHub has just enabled using [any branch and directory as the source for the docs](https://github.com/blog/2228-simpler-github-pages-publishing). You no longer have to use `gh-pages`. – Dan Dascalescu Aug 18 '16 at 17:42
4

There's yet another solution to your problem: Forget about gh-pages and branching; Put your static files that are supposed to be served inside /docs directory and then go to your project settings and tell github to serve /docs content.

For more information take a look at this

Rsh
  • 7,214
  • 5
  • 36
  • 45
  • 1
    I generate javascript from Elm code and I don't want to have javascript polute my repository code. Right now this is my script for deploying https://github.com/rofrol/closeyoureyesnow/blob/master/build_and_deploy.sh – rofrol Nov 22 '19 at 11:45
2

Publish a static site like this:

git subtree push --prefix www origin gh-pages

Where www is the doc root directory in which your static files are. Your static site is now live at: https://[user_name].github.io/[repo_name]/

Jonas Ellehauge
  • 21
  • 6
  • does not work for me. I get ```reset gh-pages branch to master ...\nfatal: Refusing to fetch into current branch refs/heads/gh-pages of non-bare repository\nfatal: the remote end hung up unexpectedly```. I use this ```git push origin `git subtree split --prefix build`:$DEPLOY --force``` https://github.com/rofrol/closeyoureyesnow/blob/master/build_and_deploy.sh – rofrol Nov 22 '19 at 11:52
1

Creating Project Pages manually

Adding a new set of Pages for a project manually is a straightforward process if you're used to using command-line git.

https://help.github.com/articles/creating-project-pages-manually

Community
  • 1
  • 1
mockee
  • 1,315
  • 2
  • 14
  • 21
1

Are your gh-pages and master branch having EXACTLY the same folder structure? If this is the case why do you even want to have two branches? just maintain one gh-pages branch! but if for whatever reason you want to have both branches that are constantly synced then your best bet is to use git rebase. See here:
http://lea.verou.me/2011/10/easily-keep-gh-pages-in-sync-with-master/

You can also cherry pick only the files you need from master and push them onto gh-pages using a special use case of git checkout. See here:
http://oli.jp/2011/github-pages-workflow/#gh-pages-workflow
http://nicolasgallagher.com/git-checkout-specific-files-from-another-branch/

Having had to tackle with the same problem I've come to find that gh-pages will usually end up having a different code base than master. In other words, gh-pages should only include the content of the dist/build/publish folder of your project whereas master will include your config files, unminified scripts and styles etc.

My suggestion would be to create gh-pages as an --orphan branch and only include the publication-ready material in it. You would have to clone from your master in a different local directory, use git checkout --orphan gh-pages to create gh-pages and then delete all the unnecessary files using git rm -rf .. From there you can go on and push to gh-pages after having added your publish-only files. Refer to Github docs for more info:
https://help.github.com/articles/creating-project-pages-manually/

Good luck

Saba Ahang
  • 578
  • 9
  • 24
  • 3
    GitHub has just enabled using [any branch and directory as the source for the docs](https://github.com/blog/2228-simpler-github-pages-publishing). You no longer have to use `gh-pages`. – Dan Dascalescu Aug 18 '16 at 17:42
1

The typical way is to switch branches: git checkout master if you want to work on master and git checkout gh-pages if you want to work on gh-pages.

Starting with git 2.5, you can have both branches checked out at the same time (in different directories). See https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows. Setup via git worktree add -b gh-pages ../gh-pages origin/gh-pages.

Bonus: If the content of a subdirectory of your master checkout is the content of gh-pages, use the script provided at https://github.com/X1011/git-directory-deploy.

koppor
  • 19,079
  • 15
  • 119
  • 161
1

I use this

git push origin `git subtree split --prefix build`:$DEPLOY --force

You can see working version https://github.com/rofrol/closeyoureyesnow/blob/master/build_and_deploy.sh

rofrol
  • 14,438
  • 7
  • 79
  • 77