How I Git
Perhaps the one piece of ubiquitous technology that you will find at any new
tech company is git. There are a couple of other technologies that you will
probably find, like AWS, but git is the only one I expect to find everywhere. It is
also, surprisingly, many developers number one frienemy. I want to share some
of my favorite tips and tweaks that I have used over the years to make it all
friend and never my enemy.
First, let’s get this out of the way. I like git, a lot. I am one of the odd
people that think it makes sense. I can’t defend how complex it can sometimes
get, but I think that by and large the design and philosophy works for me and
I can do a lot with it.
Best Practices
Branching
Use 2 permanent branches master and develop with ephemeral branches for
features and hotfixes. Many people will advocate for other branching
strategies but I think that this model is easy to convey and easy to mentally
track. All new code is merged into develop and when you are ready to release
something you merge develop into master and then tag the HEAD of master.
Need to fix a bug in production? Create a hotfix branch off of master,
merge that into master, tag it, deploy, and then merge master back into
develop.
Want to build the next cool feature? Create a feature branch off of
develop and then merge that back into develop when you are done and move on
to the next hot thing.
I like this pattern because it is simple and gives you quite a bit of control
over what happens when. I have seen many people advocate for a single master
branch that everything goes into. But, unless you have really good test
coverage and are doing true continuous integration where every commit is
deployable; the single branch policy will eventually breakdown on a team of any
reasonable size. It simply requires a discipline that I haven’t seen larger
teams maintain.
At Teem, we use one more semi-permanent branch we lovingly refer to as the
release branch. For each release (we release weekly) we branch off of
develop into a branch named release-<version_num>. We then deploy
this to a staging server for QA to validate. Having this additional branch
allows development of new features to keep going without causing a lot of
headache or confusion about what is in the release and if QA finds an issue,
how to merge the fix for that release. Everything for that release is branched
from and merged back into the release branch. Finally, when it is time to
release, we merge the release branch into master and tag the HEAD. Backport
master into develop, rinse and repeat.
Branch names
Please, for the love of all that is good, use descriptive branch names. I suggest the following naming patterns
feature-<ISSUE_ID>-short-summary-of-branch
hotfix-<ISSUE_ID>-short-summary-of-branch
releasefix-<ISSUE_ID>-short-summary-of-branch
Doing this allows anyone that is reviewing that branch to have some idea of
where that merge should be going, e.g. feature branches merge into develop
not master. Having the issue id (we use JIRA, but this could be the id from
any ticket tracker) allows people to reference what the branch should be
addressing, be that a bug report or a user story. And finally, a short summary
makes the branch descriptive and easier to use. I also recommend this pattern
because it then becomes easy to create a changelog from the git log of merges.
Commit Messages
Let’s get the less contentious piece of advice out of the way, commit messages
should be informative and well structured. I have generally followed the
advice of
tpope
and the
git handbook
but with a slight tweak. Here is a example commit message
Capitalized, short (50 chars or less) summary
**What**
- Bullet pointed list of changes you made.
- Each line should be no longer than 72 characters.
- For example:
- Switch from o365 beta API to the v1 API
**Why**
- Again a bulleted list of reasons you made that change.
- Again, no longer than 72 characters.
- For example:
- The v1 API is now stable and the beta API contains breaking changes with the
v1 api.
**Notes**
- Any additional notes for peer reviewers or to add additional context.
The most important thing to remember, this message is supposed to inform people about what is happening in the project without them needing to read every file. For peer review, it is important that they can recognize what is intended to be in the change set and what should not be there. One-line messages help no one.
To help ensure that you write a half-decent commit message, git has a feature
where called .gitmessage. Create a file called .gitmessage in your home
folder and put this in it
Captialized, short (50 chars or less) summary
**What**
-
**Why**
-
**Notes**
git will now use that as the template/initial text in all of your commit
messages.
Note, it will not have any impact on specifying the commit message when using
git -m.
Commits
Something that is probably not so contentious: I believe in
committing frequently. And now something slightly more contentious: I believe
in using rebase to create a sensible history that makes something like
cherry-pick simple to use. I generally believe that you should work on small
chunks of code that can be reasonably described in a single commit with one or
two comments in the “What” section of my commit message. I also believe that
you should break coding style fixes, e.g PEP8 fixes, into separate commits so
that they can be reviewed separately. To actually make all of these ideas play
nicely together I use rebase frequently. I squash my frequent small commit into
larger (but still fairly small) semantic pieces of history, so my git log will
go from something like this
sha1 - "Add new contact method"
sha2 - "Fix typo in contact method"
sha3 - "Add new unit test"
sha4 - "Fix bug found by unit test"
sha5 - "Fix PEP8 issues with imports"
sha6 - "Fix PEP8 issues with line lengths"
to something like this
sha1' - "Add new contact method and unit test"
sha2' - "Fix PEP8 issues"
This history makes it easy to cherry-pick or revert the new feature and it
makes it easier for peer reviewers to review the logic change in sah1'
independently of the potentially noisy and distracting PEP8 changes in sha2'.
To do this I make heavy use git rebase -i to selectively squash commits. I
have also created an aliases called git fixup that will simply squash my
staged changes into my previous commit. More on aliases later.
On rebasing
I do not intend to give a full defense of rebasing here. I will say this; if
you are not comfortable with git, then rebasing may not be for you. Almost
everything else you do in git is fairly safe, there is a way to recover from
what you are doing, this is why I like and trust git. However, rebase is
one of those commands that is not always recoverable and you often have to
simply live with the end results. With that said, if you are using rebase
especially if you are using pull -r, which is a standard pull that uses
rebase instead of merge, then you must enable and configure the rerere
feature. Quick, update your ~/.gitconfig to have
[rerere]
enabled = 1
autoupdate = 1
you will thank me. From the git book:
The name stands for “reuse recorded resolution” and as the name implies, it allows you to ask Git to remember how you’ve resolved a hunk conflict so that the next time it sees the same conflict, Git can automatically resolve it for you.
Basically, while you are rebasing, if you have a conflict that you resolve, git
will now remember that resolution and automatically apply it again in the
future. This is huge for git pull -r, which will often replay the same
section of your history and therefore run into the same conflict over and over.
Honestly, I don’t think rebase is usable without enabling rerere.
Aliases
Any post on git can not be complete without a list of handy-dandy aliases and
commands. So, here are mine. I have roughly 3 categories of aliases: audit
and cleanup, historical logging, and commit helpers.
Audit and cleanup
The following commands help me clean up old branches
audit = !git branch --merged | grep -v '\*\|master\|develop\|release-'
clean-audit = !git branch --merged | grep -v '\*\|master\|develop\|release-' | xargs -n 1 git branch -d
b = !git for-each-ref --sort='-authordate' --format='%(authordate)%09%(objectname:short)%09%(refname)' refs/heads | sed -e 's-refs/heads/--'
trim = !git reflog expire --expire=now --all && git gc --prune=now
I use audit and clean-audit the most frequently. audit simply lists my
local branches that have already been merged (except for master, develop,
and the release branches) and hence are not needed anymore. clean-audit
simply extends that command to delete the listed branches.
The b alias prints a summary of all local branches, it looks likes this
Fri Mar 17 16:19:24 2017 -0600 4d2a351 master
Fri Mar 17 15:08:31 2017 -0600 d9ce23e release-17.12.01
Fri Mar 17 13:21:34 2017 -0600 a5d5f73 develop
I use trim pretty sparingly. It simply cleans up old branch pointers that are
not being used as of “now”. This can be useful to reclaim some space after you
do clean-audit. I only recommend this command if you have OCD.
Historical Logging
The following commands will print your git log in fun, potentially
informative, ways:
graph = log --graph --oneline --decorate --all
l = log --pretty=format:%C(yellow)%h\ %ad%Cred%d\ %Creset%s%Cblue\ [%cn] --decorate --date=short
ll = log --pretty=format:%C(yellow)%h%Cred%d\ %Creset%s%Cblue\ [%cn] --decorate --numstat
Assuming that you and your team are writing good summary lines in your commit
messages, these commands can be used to quickly find when a certain commit
happened. I don’t use these frequently, but they have been useful when trying
to find when something happened in the repo. git l is great a really short
summary of the history, e.g.
af1f3ec 2017-03-05 (HEAD -> source-hugo, origin/source-hugo) Site rebuild Sun Mar 5 13:53:22 MST 2017 [Lucas Roesler]
ddfdd9d 2017-03-05 Post new spring hefe beer post [Lucas Roesler]
e5bd906 2017-02-25 Site rebuild Sat Feb 25 13:33:12 MST 2017 [Lucas Roesler]
bd21f27 2017-02-25 Add a reading list page [Lucas Roesler]
dad0fbb 2017-02-18 Site rebuild Sat Feb 18 20:20:50 MST 2017 [Lucas Roesler]
If you need a little more detail, git ll will show you the change stats as
well as the summary that you get in git l, e.g.
af1f3ec (HEAD -> source-hugo, origin/source-hugo) Site rebuild Sun Mar 5 13:53:22 MST 2017 [Lucas Roesler]
21 1 public/2017/01/hello/index.html
21 1 public/2017/01/my-management-philosophy/index.html
21 1 public/2017/01/spicy-winter-porter/index.html
Commit helpers
I only have one alias related to commits fixup
fixup=!git commit --amend
This command will take your staged changes and immediately squash them into the
previous commit. This is great for fixing small typos and simply reduces the
amount of time I need to spend in rebase. This is by far my most frequently
used alias.
Adding aliases
Adding these aliases to your system is pretty simple. In your ~/.gitconfig
file, add or update the [alias] section with the snippets I shared above. My
config file looks like
[alias]
fixup=!git commit --amend
# cleanup old branches
audit = "!git branch --merged | grep -v '\\*\\|master\\|develop\\|release-'"
clean-audit = "!git branch --merged | grep -v '\\*\\|master\\|develop\\|release-' | xargs -n 1 git branch -d"
Summary
Git is a powerful tool, one of my favorites. I like a semantic git logs, so I use rebase. You don’t have to do this. But, you better write good commit messages :)
