My Ideal Git Workflow

I went to go look at another team’s code repository recently to try to find something and I couldn’t help but notice that their git history was a mess of merge commits and confusing commit messages.

Now, there aren’t hard and fast rules for how to git (no, really.), but I am of the opinion it is generally helpful to keep a clean history to tie changes in individual files to tickets. If you can do this with a single merge bubble per feature or something else, more power to you.

What follows is how my team and I prefer to maintain our git history.

Avoid Merge Bubbles with Rebase

Instead of just merging your branch into master after a Pull Request closes (never trust Github’s automatic merge!), try this instead:

# make sure your local copy of master is up to date
git fetch
git checkout master
git merge --ff-only origin/master

# rebase your feature branch against master
git checkout my-feature-branch
git rebase origin/master

# this rebase may have caused conflicts
# just resolve them like you would a merge, then...
git add .
git rebase --continue

# update your branch after rebasing, for posterity. 
# you need to force the push, because of the rebase
git push -f origin my-feature-branch

# finally merge the branch cleanly
git checkout master
git merge --ff-only my-feature-branch
git push origin master
This process completely avoids merge commits and the associated bubbles. Your git log will always show a single unbroken thread for whatever branch you are on.

Advanced Tip – The Release Branch

If you use a secondary branch like “release” or “develop” for building to a Test environment (vs master branch for QA/Prod), the easiest thing is to just merge the branches twice. Once on your test build branch (without rebasing). Then after the ticket is approved to go up the stack, rebase against master and merge, as shown here. Then rebase your test build branch on master (like it was a feature branch), which will remove any merge commits you have added.

Commits and Commit Messages

There are many ideas of what makes a good commit message, but focusing just on the initial subject line, I recommend:

[404] Create default error page

or, if you are on JIRA instead of Github for issue/ticket numbers:

[PROJECT-404] Create default error page

The message should be present tense, clear, and short. The textual tag of the issue/ticket number is optional, but very helpful when scanning a git log.

As far as commits themselves, I would recommend committing as often as possible during development, and don’t worry over much about messages at this point (especially longer descriptions). At least commit once per day, if only to be able to push your changes up.

When you are ready to do a Pull Request, use git rebase -i HEAD~10 (or how ever many commits you have) to merge several of them together into logical pieces. Feel free to rearrange or edit commits at this point, reducing the number to minimum logical groupings. For smaller features/bug fixes, a single commit at the Pull Request stage is recommended.

After the Pull Request, squash all of your commits together, unless your Pull Request comprises multiple unrelated shippable features, then squash the commits down to one per shippable feature.

To make an apt answer is a joy to a man, and a word in season, how good it is! / Even a fool who keeps silent is considered wise; when he closes his lips, he is deemed intelligent.

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s