Changes between Initial Version and Version 1 of Development


Ignore:
Timestamp:
09/23/11 13:05:07 (6 years ago)
Author:
stuge
Comment:

How to write good commit messages

Legend:

Unmodified
Added
Removed
Modified
  • Development

    v1 v1  
     1= Commit messages = 
     2 
     3It's important to write good commit messages that will stand the test of time, so that those who review your patches can know what the patch is supposed to do, and so that anyone looking at the repository history (e.g. when tracking down a regression) can see what was done in the past. 
     4 
     5== General format == 
     6Commit messages in git repositories typically adhere to the following format: 
     7{{{ 
     8Short one line description of commit, preferably <= 60 chars 
     9 
     10This is line 3 where a long description of the commit can start. Line 2 
     11above should always be left blank. The long description should normally 
     12include some background on why this commit was required and why it is 
     13best that the commit changes things the way it does. Lines should 
     14preferably be <= 70 characters. 
     15}}} 
     16 
     17== Commands == 
     18You can send commands to Trac within commit messages, in the form of: 
     19{{{ 
     20command #1 
     21command #1, #2 
     22command #1 & #2 
     23command #1 and #2 
     24}}} 
     25  
     26Instead of the short-hand syntax "#1", "ticket:1" can be used as well, e.g.: 
     27{{{ 
     28command ticket:1 
     29command ticket:1, ticket:2 
     30command ticket:1 & ticket:2  
     31command ticket:1 and ticket:2 
     32}}} 
     33      
     34In addition, the ':' character can be omitted, and ''issue'' or ''bug'' can be used instead of ''ticket''. 
     35 
     36You can have more than one command in a message. The following commands are supported. There is more than one spelling for each command, to make this as user-friendly as possible. 
     37   
     38    close, closed, closes, fix, fixed, fixes:: 
     39      The specified tickets are closed, and the commit message is added to them as a comment. 
     40   
     41    references, refs, addresses, re, see:: 
     42      The specified tickets are left in their current status, and the commit message is added to them as a comment.  
     43 
     44A fairly complicated example of what you can do is with a commit message of: 
     45{{{ 
     46Changed blah and foo to do this and that. 
     47 
     48Fixes #10 and #12, and refs #12. 
     49}}} 
     50This will automatically close ticket 10 and 12, and add a note to ticket 12. 
     51 
     52When using a command to close a ticket, the ticket owner will be set to the Author of the commit. There is a mapping from the author's email address to the email address registered for the Trac account. If a match is found the Trac username is used. If no match is found then the full Author email in the commit is used.