Skip to content

Github workflow tips

Jump to bottom
Michael Hulse edited this page Jul 17, 2019 · 4 revisions

Last modified Jan 25, 2015
Edited on July 17, 2019 to fix formatting

Some of these notes are tailored for using GitHub for Mac

TOC

Quick links

Q: What is a gh-pages branch and what does it do?

A: A gh-pages branch is the repo name that GitHub uses to publish the contents of your branch to the web.
For example: http://registerguard.github.io/repo-name/demo/index.html

In other words, if you want to have GitHub host a demo page of your repo, FROM your repo (useing their servers), then you need to create a gh-pages branch on your repo (you'll also need create a website for your user/organization account in order for gh-pages to work ... see below).

Q: How do I setup a website for my user or organization account?

A: That's pretty easy:

  1. Create a new repo named username.github.com or organization.github.com:
  2. Add an index.html file with <p>Hello world</p> and add it to the repo.
  3. Publish the repo.
  4. Create new/publish a gh-pages branch, set it as the default (see below) and delete your master branch (optional, but only the gh-pages branch will be visible as a web page).
  5. After a few minutes you should be able to access your files via http://username.github.com or http://organization.github.com (depending on which one you setup).

Q: I want my repository to have a gh-pages branch only!

A: You'll need to create a gh-pages branch and delete your master branch.

  1. Push a master branch.
  2. Create/publish a new gh-pages branch (based off of the master).
  3. Go to the repo's admin interface via the GitHub website and choose gh-pages as your default branch.
  4. Now you can safely delete the master branch using GitHub for Mac.

Q: How do I keep my master branch and add a gh-pages branch that mirrors the master branch?

A: Here's how I do it:

  1. Create and publish a new gh-pages branch based on my master branch.
  2. After a few minutes, you'll be able to access your repo's files via the web:
    http://registerguard.com/repo-name/some-folder/some-file.ext (for example).
  3. Later, update/commit changes to your master branch, open the Merge View panel and drag your master branch into the left slot and gh-pages into the right slot. Click Merge Branches.

It's a manual process, but GitHub's mac UI makes it rather painless.

Q: How do I tag my branch with a version number and "freeze" a commit for future downloads?

A: You'll have to do this via terminal:

  1. Navigate to your local repository.
  2. List current tags: $ git tag.
  3. Add a new tag: $ git tag -a v0.1.0 -m "v0.1.0 stable".
  4. Push the latest tag: $ git push --tags.

Bonus!

  1. Delete the local tag: git tag -d v0.1.0.
  2. Delete the remote tag (which removes its download link): git push origin :v0.1.0.

Bonus!!

Tag an older commit:

  1. List commits using: $ git log --pretty=oneline, which outputs something like:
ce82fdf67a8205e4ddf5ca352dea5c1c4e8a9dd9 Hello universe!
12838cbd62e400a86e59a98323edfb4cb518496e Hello world!
  1. Next: $ git tag -a v0.0.1 -m "v0.0.1 stable" 12838cb.
  2. Finally: git push --tags.

More information on tagging here:

Q: I'm constantly checking things in and out of my master branch... Is this out of the ordinary?

A: Short answer? No. Long answer?

Some interesting workflow information can be found here:

A successful Git branching model

Inspired by that article, I've opted to create a develop branch for repositories that I frequently work on; so, my repos end up having a master, gh-pages and develop branch.

The nice thing about this workflow is that you can let your master branch be stable, and use your develop branch for the frequent check-in/outs. When you're ready to update master with the latest stable release, just merge develop into master and master into gh-pages.

Q: How do I compare my xxx branch to my yyy branch???

A: There's some good info here:

Github’s Compare View

It's pretty simple if you do it via a repo's Branches tab on the web; once there, just click on the Compare button.

Q: I'm using a Mac and .DS_Store files suck, what should I do?

A: Here's what I do:

If you don’t want OS X mucking up your Git repo with .DS_Store files, you can set up a global ignore file. As per freshsauce, you simply execute the following two commands:

git config --global core.excludesfile ~/.gitignore
echo .DS_Store >> ~/.gitignore

How to globally ignore .DS_Store when using Git

Q: How do I globally tell Git to ignore specific types of files?

A: See .DS_Store comments above, then read this.

On OS X Mountain Lion, the .gitignore_global file is located here:

~/user/.gitignore_global

... you can edit it directly.

Note: It's probably best to (also) add a .gitignore file to your repo; reasoning: You can't say for sure what type of setup someone has on the other end (i.e. someone forks your code and does a pull request). It's best just to include a .gitignore (and .gitattributes) and then you don't have to worry about rouge files. :)

Q: How do I add a sidebar and/or footer to my WIKI pages?

A: Create pages named _sidebar and _footer (I think _header will work as well).

These new pages will show up as sidebars/footers on every page of your WIKI.

To edit these "special" pages, you can modify the URI directly, like so:

https://github.com/user-name/project-name/wiki/_sidebar/_edit and/or https://github.com/user-name/project-name/wiki/_footer/_edit

Alternatively, when you go to edit any page in your WIKI, the _sidebar and _footer pages are available to edit at the bottom of the page.

Q: What's your general workflow for branches?

A: I work on develop and when it's stable I'll merge it to master and then I'll merge master to gh-pages. Pretty simple. :)

Q: How to create a "fresh" branch?

A: Currently, you'll have to use terminal to do this.

Here's the basics:

$ cd repo
$ git checkout --orphan gh-pages
Switched to a new branch 'gh-pages'
$ git rm -rf .
# Add your files, for example:
$ git add *
$ git add .gitattributes
$ git add .gitignore
# ... or whatever else needs to be added.
# Check status:
$ git status
# Once you're ready to commit:
$ git commit -a -m 'Hello world!'
$ git push origin gh-pages

I've found that there can be some issues between using terminal (to create a fresh branch) and GitHub for Mac, so I'd almost recommend to start with a "fresh" clone:

$ git clone https://github.com/user/repo.git

Or, use GitHub for Mac to download the repo, follow the above instructions, remove the repo from GH4M, remove the local repo folder and then re-clone the repo using GH4M.

Official documentation here.

Q: How do I generate git.io short url for repos?

A: Use:

$ curl -i http://git.io -F "url=https://github.com/..."
HTTP/1.1 201 Created
Location: http://git.io/abc123
$ curl -i http://git.io/abc123
HTTP/1.1 302 Found
Location: https://github.com/...

You can specify your own code to setup your own vanity URL:

$ curl -i http://git.io -F "url=https://github.com/technoweenie" \
    -F "code=t"
HTTP/1.1 201 Created
Location: http://git.io/t

More info here.

Q: Alternatives to the master/develop branch workflow mentioned above?

A: Yes! I've seen some repos that use the master branch as their "unstable" repo, and they've got a "version" branch that's "stable".

Example:

gruntjs / grunt

In essence, this is the opposite of the workflow I'm using (where master branch is "stable" and develop branch is "unstable").

The one drawback to my workflow is that my gh-pages branch is based on master (for demo purposes). I really wish there was a gh-demo-pages branch. :D

Q: Can commit messages contain references to issues?

A: Yes! Just use #XX where "XX" is the issue number. This shortcut also works in issues themselves and their comments.

Note: If you reference an issue number in a commit then that issue will get closed automatically.

Q: How do I resolve merge conflicts?

A: Crack open terminal and run:

$ git status

Look for a section that says:

Unmerged paths

From there, run:

$ git add <file>

And you can go from there (I jump back into GitHub for mac and the conflicted file(s) should be good to go now).

More info here:

How to resolve Git merge conflict

Q: How do I start a read-only repo on a server?

A: Log onto your server and make sure git is installed:

$ which git

if not, install it.

Once git is there, on server, clone:

$ git clone https://github.com/registerguard/bulldog.git

use the git:// version for both pushing and pulling (not read-only) why?

... and that's it!

TIPS:

Do:

$ git log

... before/after to see diffs (see what version you got and/or what's changed).

Use:

$ git pull

... to update the local repo to the latest version.

Note:

$ git status

... does not apply to "read-only" repos.

Q: I want to reference another repo from my repo ... How can I version control code inside of another repo?

A: Use git submodules!

There's a really good walkthrough here:

How to use Git submodules

Here's some quick tips:

  • Download your repo, cd to the root of the project tree and run $ submodule add [email protected]:username/repository.git path/to/desired/module/location (make sure the target folder doesn't already exist).
  • On your production server, to get a repo initialized, run $ git clone --recursive [email protected]:username/repository.
  • To update a submodule, cd to the submodule directory and run $ git pull; if you get an error like "you aren’t on any branch" then run $ git checkout master.
  • Other?

Note: You might consider using https, instead of git@, as the latter won't require authentication. Choose wisely. :)

Q: How do I setup Brew (Mac) to be the default Git command/resource?

A: Easy!

First, get your current Git version:

$ git --version

... and the path:

$ which git

... next:

$ brew update

... then:

$ brew install git

... and:

$ brew doctor

Now, start a new terminal session and run the above $ git --version and $ which git commands.

See here for more tips on using Brew.

Q: OMG! I've commited sensitive information to my repo/wiki, how can I undo????

A: Yah, that sucks ...

Here's one way:

Remove sensitive data

What has worked for me:

  1. Clone the repo (using a WIKI as an example): 
    $ git clone https://github.com/user/repo.wiki.git
  2. Move to that directory: 
    cd repo.wiki/
  3. Delete the hidden .git folder.
  4. Initialize a new repository in the same folder and link it to github: 
    $ git init
$ git remote add origin [email protected]:user/repo.wiki.git
  5. Now commit your current version of code: 
    $ git add *
$ git commit -am 'Hello world!'
  6. Finally, force (-f) update on GitHub: 
    $ git push -f origin master

The same/more info can be found here:

how to delete all commit history in github

Q: How to clone a specific branch?

A: If you have git >= 1.7.10:

$ git clone -b mybranch --single-branch git://sub.domain.com/repo.git

stackoverflow: Clone only one branch

Q: How to check for changes on remote (origin) git repository?

A: Some of these have been stated already, but these work well when used together:

$ git log # shows what happened (like a git history) (use 'q' to quit)
$ git status # Shows you current status of commits
$ git diff # Shows difference between local and github repo. (use 'q' to quit)

Other options:

# Bring your remote refs up to date:
$ git remote update

# Test whether the branch you are tracking is ahead, behind or has diverged;
# If it says nothing, the local and remote are the same:
$ git status -uno

# This command will show you the commits in all of the branches
# whose names end in master (eg master and origin/master):
$ git show-branch *master

Short version to see if you're ahead or behind:

$ git remote update && git status

Q: How do I change a folder name in a repository that's a Git sub-module of another repository?

A:

  • Clone sub-module repo locally.
    • Make sure you're working on the right branch (in this case, I want to be in master).
  • Make changes to folder name.
    • If necessary, update gh-pages demo branch.
  • Push back to GitHub.

Done.

Clone this wiki locally