Git workflow and usage standards

These standards are to assist teams working with Camel Punch on projects that use Git as their version control system. Git workflows may change from project to project, so these are basic guidelines and pointers for those new to Git.

Use your own fork

If a project is hosted on Github, It’s usually easiest to fork a project to your own Github account before working on anything. This way you can use your own copies of the main repository’s branches, and play to your heart’s content without fear of messing with the main fork.

Many of Camel Punch’s projects are deployed automatically from Git, so it’s good to steer clear of the central remote to avoid accidents.

Rebase when pulling to a topic branch

You should stay up to date with the latest changes from the main remote’s master branch. Do this at a time when your workspace is clean i.e. no staged or changed files (you might use ‘git stash’ to achieve this, or wait until your next commit). For example, if the main remote is called ‘camelpunch’, use:

git pull --rebase camelpunch master

This will cause any commits you have to be applied on top of the latest changes from the central master branch. Also, you’ll avoid creating merge commits that you get with straightforward ‘git pull’.

You will occasionally run into merge conflicts, even with rebase. Git gives instructions when a merge conflict occurs. Just edit the offending files, then ‘git add’ them and ‘git rebase –continue’. If you get flustered, use ‘git rebase –abort’.

Use subject lines in commit messages

Read Tim Pope’s guidance on commit messages. They’re pretty decent rules. Subject lines go on the first line of the commit and should succinctly state the purpose of the commit. They should be followed by an empty line, e.g.:

allow users to log out

Uses Rails' UJS with the DELETE HTTP verb on /sessions
Some more explanation.

Terse subject lines become really useful for the chump that has to pull in yours and others’ commits, and decide which order they should arrive in and so on.

If you’re using gitx, it provides a handy line to indicate where the 72 character stop point is. Tim Pope’s Vim runtime files have special highlighting for this purpose.

Include Pivotal Tracker story ID in commit messages

Since we use Tracker for almost every project, if you’re fixing something that’s in Tracker, use the following syntax to tie your commit to the story. This automatically comments on the story, placing a link to your commit in Github. Also, it’ll mark the story as finished. So, if you haven’t finished the story yet, and your commit has been pushed to the main remote, be sure to reset it to ‘started’ from Tracker’s interface.

here is the subject line

Here's an explanation of the commit.

[fixes #234234234234]

It’s good to put it on the last line, cos it’s pretty ugly to read and, if you’re obeying Tim Pope’s restriction to 72 chars in the subject line, your space is restricted there at least.