Git commits: An Effective Style Guide

Paul Isaris on June 30, 2018

Post cover image provided via xkcd Git commits are one of the most underrated features of Git. Pause for a moment and think; When was the last ... [Read Full]
markdown guide
 

I saw something a co-worker does and I really liked it.

It is as simple as addind the Jira issue number and the short name of the person that did the commit.

Like "841-RickM-bug fixed bug blah blah"

Reading commits from the develop and master branch is pure joy this way. Like, everything makes sense.

 

Why would you add the user's name? That only takes up room in the short version of the commit message, and you can see their name in the log anyway.

 

Isn't the author already recorded as part of the commit anyway?

 

We use BitBucket and Jira and when you add the issue number to the commit it links it in Jira too so you can go directly to the commit in BitBucket. Pretty cool stuff!

 

Cool, that also works like a charm, especially for short commits. On larger ones, you might need to add multiple lines ;)

 

or split up the long commit into several short ones :)

Of course! Just keep making sure that you can easily navigate through the commit history.

 

Adding the username and / or trello/jira id/hash to your git branch is also pretty helpful in a team environment.

Eg, instead of 'new-bug-fix' ... you can write 'jlyons-idea1234-new-bug-fix'

 

Great article Paul!

I see you value a more fully featured, descriptive commit message. I've worked with a few developers who really push for short, punchy commit messages of <40 characters. I guess the logic is that it will be quick and easy to scan in future but in my opinion, often times you just can't convey what you need to convey in that short of a message.

Another thing I would say is it's important to know when to put something in a commit message and when to put it in project documentation. Sometimes I'll find myself writing something in the commit message and I'll read it back and realise it's much better suited to go in the README.md or similar.

 

Ideally you'd do both: a concise commit subject that summarises the whole change, and a commit body that explains the why of your change. The body is something people will rarely read, but they'll really appreciate it when it answers their questions (they've likely come to your commit message to clarify something).

eg. this commit.

 

Nice post, Paul! I've been trying to work out for a while how to introduce developers to using Git in its full capacity, but it's a bit of a chicken and egg problem:

  • Without writing good commit messages, there's no reason to look at blame/history, since it doesn't have anything to offer

  • If you're not looking at the history, there's no reason to write good commit messages, and there's no reason to use rebasing to keep a clean history (eg. squashing extraneous "fix" commits)

  • Without a clean history, tools like git bisect become more pain than it's worth to use, so you don't work with the history

It's surprising that developers, who generally thrive on learning how things work, don't progress quickly past the "Git is Ctrl-S for code" stage:

Example of a bad history

 

Thanks for your response Stephen, I know exactly what you mean. I indulge to the same "fast git commit" thing many times. Unfortunately, developers don't like to adhere to a new way of doing a certain thing "just because" someone told them.
If they see value in it, then they will do it.
So, if they stumble upon a situation where they want to rollback to a certain commit and spend hours finding it, then they will cahnge their minds.
So, the only way of getting them to use a new git style is actually to ask them for baby, incremental steps.
For example, they could try adding the issue tracker id in their commit messages, for a month.
Then, they could also tag the major commits so that there is a way to rollback to a previous version, easily.
These incremental small changes will result in them not complaining about drastically changing their way of work.

 

Really nice article, thanks a lot Paul!

I would have put the issue tracker id on the first line (ideally at the beginning) to easily find commits related to a specific feature/issue, it's usually the starting point of investigations.

I really like the commit type, I'll try to use it in my own commits, but I disagree with the "test" type. Tests should be added in the commit containing the feature/fix code because if you put tests code in a commit before feature code, a git bisect can stop between both commits and lead to broken unit tests. And if you put tests code after the feature code, you can forgot to revert the tests when you need to revert the feature, which will break tests too.

The more complex step when doing small and smart commits is to encourage the rest of the team to do the same. This methodology takes time and developers don't often see the real advantage to do it (we don't need to git bisect every day). I think the best argument is about Pull Requests: with small and specific commits, rather than reading the whole change which is sometimes really hard, reading commit by commit and skipping the less interesting ones leads to more valuable code reviews. My Pull Requests are often paired with a long description linking to the important commit to read.

 

Very nice article Paul.

I agree that commit message is essential. On first glance, it tells us a lot about commit itself, and it should be made neatly. Fortunately, nowadays most of IDE has excellent support for git. I prefer to look directly into the code and later search for the particular commit. So I omit the stage of looking through commit messages at all. I don't think that my way is the best one, but it helps in case of the mess in commit messages.
I think that more important than meaningful commit message is proper commit body. I mean, devs should avoid committing all changes in one commit and split at every available place. Creation of a commit cost as a little time but can save a lot of time in future, especially when we would like to revert some evil commit from our branch. It'd be much more difficult if we have multiple functionalities changed in one commit. This is a real nightmare!

So,
Keep calm and commit

Cheers

 

Thanks for your response, Rafal! Totally agree with you on this.
Code readability is much more important than commit messages, and should be first priority ;)

 

Personally I (definitely not alone in this) found this guide compelling and informative, and I try to follow the Imperative Title, Explanatory Details pattern.

 

I'm all for good, structured commit messages, but do not see the point of the commit type. It leaves even fewer characters for a meaningful title, and creates friction by being one more thing to think about.

 

Well, of course it can be omitted if you think that it does not improve commit readability, but it sure is a helpful way of filtering out the commits of a certain type.

 

Excellent article, Paul!

Writing a meaningful git commit message is a good practice because it not only helps in debugging issues later (especially if it's been caused by one's own git commit) but also is one form of effective documentation that can be referred by anyone (e.g: new team-members) to get up-to speed on a project.

While I'm sure there are numerous articles on the internet towards this, here's one I found to add more detail

 

Thanks for the comment and the reference, Vinay!

 

I think all of this could be omitted when you've just started a new project and at the early stages. The reasoning is simple: you need small, atomic and well-commented commits to find regressions (mostly), admire the history and to make merges/rebases easier. This is not needed when there's not much code and you only write the most basic subsystems. Actually, I'd argue that making verbose and small commits that early is counterproductive as it distracts from the flow. It might be wrong for big teams and huge tasks but I'm sure it applies to pet and medium-sized projects. My own projects usually start with a big "Initial commit" and a set of huge commits after that, mostly described as "WIP" or so.

Of course, when the groundwork is set the commits should become smaller and more feature/bugfix oriented. It can also be used as a good rule of thumb telling you the project has probably become an MVP or an alpha and is ready to be shown to somebody.

 

exactly this is something I overlooked ... and this style is truly great to follow ..thanx

 

The best way to enforce self/team discipline is to automate commit process. I can’t recommend enough github.com/brigade/overcommit

code of conduct - report abuse