1Git commit messages format 2========================== 3 4The principle of the git commit log is to document at least the 5*what*; in English. That is redundant with the commit diff, yes. But 6that redundancy does help in understanding the commit diff better. If 7appropriate, the commit log can also document the *why*, but only if 8it does so by respecting the format of the commit log. The reason why 9we are so strict about the format is that the commit log is later 10parsed by a tool to build a ChangeLog, which we want to stay compliant 11with the GNU ChangeLog format. 12 13So here is the format we are talking about. 14 15The first line of a git commit message should start at column 1, with 16no space. That line should be a short summary of the purpose of the 17commit. If the commit relates to a bug filed into bugzilla, the line 18should begin with the bug (or Problem Report) number, followed by a 19white space; e.g: 20 21Bug <number-of-the-bug> This is a great commit 22 23The line in its entirety should not be longer than 50 characters. 24 25The next line should be an empty line, with no spaces. 26 27Subsequent lines can be a free form introductory text that should 28start column 0. The introductory text can have an arbitrary number of 29lines. No line in that text should start with the sequence 30<white-space>*. That is, no line in that text should start with a 31sequence of white spaces followed by the start character (*). 32 33If there was an introductory text, then the next line should be an 34empty line, with no spaces. 35 36The subsequent lines should have the form of the Body of a GNU ChangeLog 37entry, i.e: 38 39 * file1.c (func1): Changed foo in this function. 40 (func2): Changed blah in that function 41 * file2.c (func_foo): Changed something here. 42 43Note that before the '*', there is a tab that is 8 spaces long. Also 44note that right after the '*', there is a space. 45 46An example of commit message would be: 47 48~=~ 49Bug 123456 Add super feature 50 51The super feature requires modifying function_bleh to make it call 52function_foo instead of function_bar. As function_bar is no more 53used, this patch removes it. 54 55 * file1.c (function_foo): Define new static function. 56 * file2.c (function_bar): Removed static function. 57 * file3.c (function_bleh): Modified this function to call 58 function_foo, rather than function function_bar. 59~=~ 60 61Note how, in the ChangeLog part of the commit log, each function 62modification is mentioned, by referring to the name of the function in 63parenthesis. The length of a line should not exceed 72 characters. 64The description of what happens to the function should be succinct. 65Just describe the "what". 66 67The "how" should be described by comments in the code change itself, 68so there is no need to describe in the ChangeLog part of the commit 69log.. The "why" and "general spirit" of the change should be 70described in the introductory text that precedes the ChangeLog part. 71So, again, no need to add to the ChangeLog part. 72 73For files that contain no function definitions, the ChangeLog looks 74like: 75 76~=~ Bug 123456 Shorten compilation lines 77 78 * configure.ac: Shorten compilation lines by regrouping 79 PKG_CHECK_MODULES calls. 80 * tests/Makefile.am: Adjust this. 81~=~ 82 83Another one could be: 84 85~=~ 86Bug 123456 Shorten compilation lines 87 88Blah blah, this is an introductory text explaining the purpose of this 89commit. It can contain whatever character I want. It just cannot 90contain a line that starts with white spaces immediately followed by 91the star character. 92 93 * configure.ac: Shorten compilation lines by regrouping 94 PKG_CHECK_MODULES calls. 95 * tests/Makefile.am: Adjust this. 96~=~ 97 98When it's needed, the introductory text is very important. Please 99take time to explain the current status of the code (before your 100patch) and why it was in the need of your patch. In other words, take 101time to explain the problem you are trying to solve. If the problem 102is explained in a bug in the bugzilla, please try to explain it again, 103using your words. Just linking to the bugzilla is generally not 104enough. And then, yes, refer to the bugzilla. 105 106Then explain how your changes address the issue that you've just 107described. 108 109In other words, the introductory text should tell a story. So please 110be generous :-) 111 112And then the ChangeLog part of the commit log is another exercise. 113This one has to be succinct. Every single function or global variable 114or type changed (or added/removed) has to be mentioned explicitly by 115name as shown in one of the examples above. 116 117Writing the ChangeLog part of the commit log can seem tedious, but 118it's an excellent way to perform an auto-review of your work. You'd 119be surprised by the number of issues that you catch in the process. 120 121Also, please keep in mind that reviewers of the code are going to do a 122function-by-function and line-by-line review of your changes, so 123please, take the time to do so as well. This is a great way to give 124great quality to your code. 125 126We encourage you to look at the existing commit logs or at the 127ChangeLog file for inspiration. 128 129Happy Hacking! 130