A Guide to Git(Hub) Flow and Commits

4 min readDec 4, 2017

Yep, we all have been there, eh? Well, I have.

This is the kind of stuff I used to do. And no, I'm not proud of it.

And, to help my future self, I'm putting together a team of all the best resources that I have found so far on how to improve our experience with Git.

The Git Flow

In the incredible extensive, and well written, article A Successful Git Branching Model, Driessen presents all the main arguments of what has become know as The Git Flow. Mandatory.

Pros: Clear purpose, simplifies releases and hot-fixes, avoids cherry picking.
Cons: Using the--no-ff flag for every merge let the git log a bit messy.

The GitHub Flow

Ideal for flows that deploys continuously to production

The awesome (and beautiful) hot-site Understanding the GitHub Flow is an interactive tutorial of how to apply the GitHub Flow. Awesome!

Pros: Popularises Code review in Pull Requests.
Cons: Not very suitable for projects that demands periodical releases.

But wait, which one to chose?

Although these are not the only approaches, in my experience, what have brought more confidence and success among my teams was a merge (ha!) of both. That is..

The Git Mixed Flow

Here is how it works:

The Git Flow is followed as the main guideline, with a few tweaks.
Developers rebases their branches on the daily basis to avoid conflict — git pull --rebase origin develop
When the developer feels like, a Pull Request is opened to start a conversation or a code review on the proposed changes.
Once the change is ready, tested, reviewed and approved, the Pull Request is non-fast-forward merged into develop, creating a new merge commit.
Finally, when a new version is ready to be released, the develop branch is fast-forward merged into master, not creating another merge commit —
git merge --ff-only develop

As a result, the git log is kept with just one depth level for each Pull Request:

And now, we’ve got:

The Git Flow process, the power of Pull Request for conversation and code reviews and fewer merge commits

Branch Naming

“***How to name things*** — *the hardest problem in programming” via* @PeterHilton

Still following the awesome A Successful Git Branching Model article, these are some simple, though effective, naming conventions for branches:

branch: master
what: Always deployable to production. Shall never be pushed to.

branch: develop
origin: master
merge into: master
what: Next release in development. Only mergeable via Pull Requests.

branch: release-*
origin: develop
merge into: master
what: A release waiting to be lunched soon.

branch: hotfix-*
origin: master
merge into: master
what: a bug fix in production (master).

branch: feat-*
origin: develop
merge into: develop
what: Adds a new feature.

branch: fix-*
origin: develop
merge into: develop
what: Fixes a bug in development.

branch: ref-*
origin: develop
merge to: develop
what: Refactoring/Improvements of existing features.

branch: chore-*
origin: develop
merge into: develop
what: Config changes, tools/libraries updates, build adjusts and so forth.

Where * is a imperative description of the change separated — by — dashes.

These conventions have not been written in stone, of course. You are free to use and adapt them as you will.

Commit Messages

https://chris.beams.io/posts/git-commit/

The piece How to Write a Git Commit Message is probably the best article that I've read on this topic. It is a totally must-read material. Seriously. Click here and read it. Now!

If you clicked it and the article’s length scared you, fear not! The excellent 5 Useful Tips For A Better Commit Message could pass for its TL;DR version. You’re welcome. 😅

Code Reviews

"Modern code reviews are about socialisation, learning, and teaching."

In this excellent talk, Derek Prior from Thoughtbot, says all above and also explains the learning and sharing knowledge aspects of having a strong Code-Review culture. Eye-opening!