40

In Git it's possible to set and enforce a good commit template.

Can you recommend (preferably with argumentation) a good commit template / guidelines to enforce in the company?

Improve this question

8 Answers 8

Reset to default
44

I use

[Abc]: Message.

With Add, Mod(ify), Ref(actoring), Fix, Rem(ove) and Rea(dability) then it's easy to extract logfile.

Example :

Add: New function to rule the world.  
Mod: Add women factor in Domination.ruleTheWorld().  
Ref: Extract empathy stuff to an abstract class.  
Fix: RUL-42 or #42 Starvation need to be initialised before Energy to avoid the nullpointer in People.  
Rem: freeSpeech is not used anymore.  
Rea: Removed old TODO and extra space in header.

If I have more than a line, I sort them with most important first.

Improve this answer
2
  • 1
    Could you please explain some difference between Mod and Ref? Sometimes I'm just doing small fixes which is some kind of refactoring.
    – yegle
    Dec 31, 2012 at 19:25
  • 2
    @yegle Mod is about adding something or change a behaviour, Ref is about changing internal stuff that don't add any fonctionality, add API, etc. Example : if I have an add(Object) function and I implement an add(List<Object>) function, I will comment with Mod. Later I remove duplication and use directly add(Object) in add(List<Object>) then I will use Ref.
    – rangzen
    Feb 28, 2013 at 6:41
13

We use the following:

[Ticket's Id in JIRA]: [Message: What was done] For example - ABC-123: Added ability to configure presentation per region.

In this case with proper integration you will be able to get changed/deleted/added files in your issue tracker. However, be aware that you should prevent something like ABC-123: Done or ABC-123: Fixed with filters if possible.

Improve this answer
9
  • +1 for bug fixes but what about new features? Unless new features are all created in JIRA as well...
    – Sardathrion - against SE abuse
    Oct 6, 2011 at 9:45
  • 4
    @Sardathrion - Personally I'd create trackers for the new functionality in JIRA. We do this with Bugzilla and it gives the test team (and everyone else) good visibility of everything being put into a release and minimises things going out when they've not been tested / code reviewed / whatever.
    – Jon Hopkins
    Oct 6, 2011 at 12:46
  • @JonHopkins: While a bug tracker can be used for new features, it may not be the ideal tool. Of course, your mileage shall vary ^_~
    – Sardathrion - against SE abuse
    Oct 6, 2011 at 12:59
  • 4
    I came to love having a ticket assigned to every commit (some tickets can easly have multiple commits, of course): it's a very simple way to get more background information when inspecting code later on. "Why did they do that?" is much easier to answer when you have the commit comment and an issue tracking entry.
    – Joachim Sauer
    Oct 6, 2011 at 14:19
  • 1
    Sure - and once you've gotten it reviewed, you can merge to master.. whereby the ticket reference in the branch name is lost but not if it was also in the commit message.
    – JBRWilkinson
    Dec 27, 2013 at 12:35
12

There is one simple rule, which is a convention followed by many (if not all) SCMs and by most tools that work with SCMs :

The first line of a commit message is a short summary, while the rest of the message contains the details.

So, most tools display the first line only, and display the whole message on demand.

A typical misuse of a commit message is a bullet list of changes (only the first bullet will be shown). Another misuse is writing a loooong detailed message on a single line.

So, if there is one thing to enforce, I would say it's the maximum length of the first line.

Improve this answer
1
  • I’ve never seen a reason to write a long detailed commit message in Git at all. Detailed info goes in the issue tracker, and so my commit messages are just one-sentence descriptions of the (small) change I made in that commit.
    – Marnen Laibow-Koser
    Jun 15, 2018 at 14:44
9

Personally I've never seen a general commit template worth using. The comment should concisely say what the commits are related to e.g. what feature/bug fix or a brief statement of why changes were made.

Information on what was committed should not be included, this can be determined by the scm system. More bug/feature information belongs in where ever bugs and features are tracked.

When updating a bug report after a commit I find it's good to also state the commit revision along with the comments in the bug report. This way you can find your way from the commit comment to bug report, and for each comment on the bug report you can find what was committed, but you do not duplicate information by having it on both the bug report and commit message.

Then when viewing history of revisions for a file, you have nice brief messages describing the history but also know where to look for more details bug reports or task descriptions for more details.

Improve this answer
1
  • 4
    Many bug tools will let you link directly to the revision in your SCM tool if you enter the details in the correct format. Similarly, many SCM tools will link directly to the bug database if you enter the bug details in the correct format. IMO, as long as you do this, then you're golden.
    – Dean Harding
    Feb 1, 2011 at 13:20
3

In Git it is possible to enforce nearly anything with Git hooks. Check the examples in .git/hooks for ideas.

As for the message, in a very general case, you want to include enough information about the problem you were solving AND the solution itself to be able to find and identify this commit later. In most cases the problem will be referenced a bug number (with proper integration with your bug tracking system). If you have other systems your process integrates with (like the code review tracking system), include the appropriate bits as well:

Extracted checking foobar range from bar() into foo(min, max) to re-use
in yadda() and blah(). foo() returns true if foobar is in the
specified range and false otherwise.

BugID: 123456
ReviewedBy: mabuddy
AutomergeTo: none

BUT you wanna keep it simple. Otherwise, people will find a way to cheat the system and produce useless commit messages.

Improve this answer
0

We use a template containing

  • The id number of the bug / feature / fix
  • A yes/no describing whether the code is tested or not
  • And a details section for a short description of the intention of the commit

The first two are omitted most of the time however (occasionally all three) so its not really a big deal.

Improve this answer
1
  • Why would untested code ever be pushed in the first place?
    – Marnen Laibow-Koser
    Feb 25, 2020 at 14:35
0

I generally have the identifier that is in the ticket tracking system I use or a high level overview as the first line. Then I have line item "bullet" points of the specific change in the commit. So I could of something like:

MyVideoGameProject-123 OR Inventory System Improvements
Made inventory GUI drap and drap
Added ability to have multiple bag slots to expand inventory capacity

This is the cleanest commit format I like. It is direct and to the point. Another reason I do it this way is that if I want to create a change log, I could just take all the commit messages and parse it into a change log very easily.

Improve this answer
0

[ticketId][ABC][topicId][WIP] Message, where:

  • ticketId - id of an item in task repository
  • ABC - add (feature), fix (bugfix), str (structure), dep (dependency) rem (backward incompatibility/remove), rea (readability), ref (refactoring)
  • topicId - can be a job selector for jenkins and/or branch name and/or topic name for gerrit
  • WIP - work in progress/or not (i.e. Continuous Integration may requires this)
  • message - detail of the modification

Examples:
[#452567][add][menu_item] new item - guestbook
[#452363][fix][banner_top][WIP] 1024x300 can be used now
[#452363][fix][banner_top] 500x200 can be used now
[#452713][rem][page] left middle ad

Improve this answer
5
  • 1
    Your answer would be stronger if you explained why you feel this is such a good format. While the value of this format may be self-evident to you, it's value is not as obvious to others.
    – user53019
    Jul 2, 2013 at 22:41
  • thanks for the comment - yes i will explain in more detail soon - I just wanted to start with a facts - would be a good stack feature that you could sign the answer with WIP:)
    – laplasz
    Jul 3, 2013 at 7:25
  • For 'Work In Progress' - is this a note to yourselves that you'll come back and amend, or do you commit to master with this? If so, why?
    – JBRWilkinson
    Dec 27, 2013 at 12:36
  • CI workflow may require it - so you push to master unfinished change just to integrate it as soon as possible
    – laplasz
    Dec 27, 2013 at 12:48
  • This is too much ceremony. Ticket ID and message are essential of course, but ABC should be a function of the ticket ID (and so you can look it up in the issue tracker), topic ID seems useless, and WIP should never be pushed to a remote at all.
    – Marnen Laibow-Koser
    Feb 25, 2020 at 14:32

Not the answer you're looking for? Browse other questions tagged or ask your own question.