Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

closed as primarily opinion-based by Jim G., MichaelT, GlenH7, Kilian Foth, Dan Pichelman Jul 3 '13 at 17:40

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

8 Answers 8

up vote 27 down vote accepted

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.

share|improve this answer
1  
+1 That is a nice way of dealing with it and you can easily grep for changes. –  Sardathrion Oct 6 '11 at 9:46
8  
EEk! You took away free speech! –  CaffGeek Oct 6 '11 at 14:10
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 '12 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 '13 at 6:41

[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

share|improve this answer
    
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. –  GlenH7 Jul 2 '13 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 '13 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 '13 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 '13 at 12:48

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
    
+1 for bug fixes but what about new features? Unless new features are all created in JIRA as well... –  Sardathrion Oct 6 '11 at 9:45
3  
@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 '11 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 Oct 6 '11 at 12:59
3  
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 '11 at 14:19
    
Isn't it better to do a ticket on a separate branch? –  Tamás Szelei Oct 6 '11 at 14:52

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.

share|improve this answer

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.

share|improve this answer
3  
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 '11 at 13:20

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