Last updated July 3, 2013. Created by Gurpartap Singh on March 3, 2006.
Edited by scor, sun, pfrenssen, Drave Robber. Log in to edit this page.

As a module or theme maintainer or contributor, you may be making commits to a Drupal Git repository on a regular basis, both for your own code and changes contributed by others. Appropriate comments along with those commit messages are the key to providing context that others need to understand the development of your code.
It is also a good practice and a form of netiquette to credit contribution authors both in commit messages and in the commits themselves by properly applying git aware patches. Thus, the commit will appear in contributor's profile and will help spread good karma and encourage further contributions.

Important: Do NOT begin your commit message with the # symbol. While this was a best practice with CVS, it will cause Git to remove the commit message entirely in certain situations (e.g. git rebase -i).

Quick summary for the impatient

Use this syntax for commit messages:

Issue #[issue number] by [comma-separated usernames]: [Short summary of the change].

For example:

Issue #52287 by sun, Dries: Fixed outdated commit message standards.

Note the punctuation.

Longer version

Give details

Provide at least a short summary of what is contained in the commit. Most often, the issue title can be re-used. Otherwise, try to summarize the change.

Usually, commit messages start with the (past tense) verb

  • Added (new feature)
  • Fixed (bug fix)
  • Changed (task)
  • Updated (task, due to changes in third-party code)

It may not be trivial to phrase a summary starting with one of those verbs. But if used consistently, you will get used to it. When not using these verbs, make sure you prefix the commit message with the issue category.

Either way allows users of your module to determine whether a new release contains only bug fixes or maybe also new features and other stuff that may require testing on an existing production site.

The following hint might help you in writing comprehensive summaries:

Try to keep the commit message to something like the title of the issue or a single sentence describing what was fixed. Do not describe what was really wrong, just say what was fixed.

Reference the drupal.org issue, if available

A common practice is to create a project issue for every change in a module/project. If the change you are committing relates to an issue on drupal.org, give the issue number, preceded by a number/pound/hash sign (#). This convention is interpreted by the commit log on drupal.org to provide a link back to the issue.

Give credit

If others have contributed to the change you are committing, take the time to give them credit. Each commit message should contain at least one contributor name, even if it refers to yourself. Once a project has more than one maintainer, or is taken over by a new maintainer, it's very valuable to know who actually wrote or contributed a certain change.

To do this, append by [username]: to the issue number. Separate multiple contributors with commas.

Issue #123456 by dww, Dries: Added project release tracking.

If you are just committing a patch created by others, do not credit yourself.

If a very very large list of people (eg. more than 10-12) contributed to a change, pick the major contributors and add et al to represent the rest:

Issue #123456 by dww, pwolanin, et al: Added project release tracking.

If a change/commit does not relate to an issue for any reason, you should skip the issue number, but still give credit:

by sun: Updated README.txt.

Always refer to usernames from drupal.org and not the contributors' Git account names.

You can also add a commit author in git to attribute authorship of what you're committing to another user.

(Optional) Re-use commit messages in CHANGELOG.txt

Each project should include a CHANGELOG.txt, which lists the major changes to the code in the project. Some projects choose to list even minor changes.

One way to create the CHANGELOG.txt file is to copy and paste commit messages to your changelog prior to committing a change (see formatting above). This gives you a nice output for project release nodes. (Or you could bypass this completely by using the git-release-notes Drush extension -- example output.)

Note that if you do copy/paste commit messages into CHANGELOG.txt for every commit, it does make it more difficult to do git "cherry-picking" (i.e., to apply only selected patches to a new branch), and more difficult to port patches to other branches. But if you do want to follow this practice:

  1. Apply a patch.
  2. Add a change log entry to CHANGELOG.txt. Notes:
    • Change logs are reverse chronological, new entries at the top.
    • All lines in CHANGELOG.txt should wrap at 80 chars. If an entry exceeds 80 chars, subsequent lines belonging to the same entry should be indented by 2 spaces.
    • Leave out the "Issue" commit message prefix in the changelog.
  3. Copy the changelog entry and re-use for the Git commit message (but remove linefeeds and indents of long lines).
  4. Prepend the "Issue " prefix.
  5. Commit.

Normally, changelog entries/changes shouldn't be contained in patches you create and submit to a project. Let the project maintainer add CHANGELOG entries.

Prior to creating a new release, you should update the CHANGELOG.txt and insert a new release heading:

--- CHANGELOG.txt 3 Nov 2008 23:18:02 -0000 1.4.2.14
+++ CHANGELOG.txt 29 Nov 2008 15:42:53 -0000
@@ -6,6 +6,10 @@ Journal x.x-x.x, xxxx-xx-xx
Journal 6.x-1.x, xxxx-xx-xx
---------------------------
+
+
+Journal 6.x-1.3, 2008-11-29
+---------------------------
#322731 by sun: Fixed improper use of t() in module install file.

Examples

A sample commit message:

Issue #46746 by Matt: Fixed inconsistent encoding of path aliases.

Longer messages are possible, but commonly not used, since the drupal.org issue already contains detailed information and is automatically linked in the release notes if you are following this guide.

Extended commit message, including non-technical explanation:

Issue #46746 by Matt: Fixed inconsistent encoding of path aliases.
Fixes broken URLs on profile pages.

Longer, and more descriptive, for larger issues:

Issue #[issue number] by [username]: [Short summary of the change].
A bug in [filename(s)] caused [short description of the problem]. This commit
solves this by:
* [first solution or change]
* [second solution or change]
* [third solution or change]
* Adding $foo as parameter to the API call module_function() in bar.
[Optional short note on the effects for code calling your APIs or functions, or users using your modules.]

For other examples, have a look at commit messages as available on http://drupal.org/commitlog. Note, however, that you'll also see non-conforming commit messages there.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

Apparently, no one on drupal.org squeezes details or important information into commit messages like the last chapter of this page suggests.

The lower section of this page actually dates back to dark ages. The only time I've ever seen such commit messages was in the very first CVS commits in existence by Dries and other champions, and AFAIK, at that time there was no d.o project infrastructure or anything remotely comparable to issues. Thus, the only (poor) way to communicate about larger changes, pitfalls, and follow-up todos was to squeeze the info into your commit message.

Even though the migration to git might have changed what kind of stuff and code gets committed, I don't think that it's going to change the superior procedure (and to some extent, change management) of using issues for communication. Stuff needs to be communicated on-issue, not in a deeply hidden commit message.

Therefore, I'd suggest to completely remove those examples for longer commit messages. Or alternatively, cut them down to merely show, how a longer commit message should be formatted - but clearly state that it's not recommended to use commit messages for communication.

Daniel F. Kudwien
unleashed mind

While the longer commit messages aren't common they are a sort of standard in Git.

[SHORT SUBJECT - Ideally less than 80 char.]
[SKIP A LINE]
[Longer paragraph style explanation of the commit.]

I personally use this style on a regular basis and think it's still a good idea to explain it to folks even if it isn't a common practice just yet.

As far as i understand
http://drupal.org/project/grn

helps in extracting the commit-massages and preparing a release note.

Thomas

Combining IT and arts to organize
http://it-arts.org

From http://stackoverflow.com/questions/5064563/add-line-break-to-git-commit-...

git commit -m $'Issue #[issue number] by [username]: [Short summary of the change].\n\nA bug in [filename(s)] caused [short description of the problem]. This commit solves this by:\n* [first solution or change]\n* [second solution or change]\n* [third solution or change]\n* Adding $foo as parameter to the API call module_function() in bar.\n\n[Optional short note on the effects for code calling your APIs or functions, or users using your modules.]'

Should output
Issue #[issue number] by [username]: [Short summary of the change].
A bug in [filename(s)] caused [short description of the problem]. This commit solves this by:
* [first solution or change]
* [second solution or change]
* [third solution or change]
* Adding $foo as parameter to the API call module_function() in bar.
[Optional short note on the effects for code calling your APIs or functions, or users using your modules.]

True enough, but if you were wanting to do something like that, you'd be better to skip the -m altogether and just let git launch your text editor :-)
On-topic,
git commit --amend
Lets you update git log messages before you push them

Here are some git best practices from outside of drupal that have been in use for more than four years. Whenever I come across a developer talking about git commit messages, they usually point to these two urls:

  1. http://stopwritingramblingcommitmessages.com/
  2. http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Unfortunately, a few of the suggested practices on this page don't match up. For example, the number of characters on the first line of a commit message and past tense vs. present tense verbs (fixed vs. fix). I'd rather see the Drupal community adopt the general git community's best practice and then add on any Drupal-specific needs (issue #). Then we wouldn't have to switch git contexts in our minds when working on Drupal and non-Drupal projects.

And I would discourage the use of the -m option for the git commit command. That's great for a very, very, very simple commit message, but it also breeds laziness. I'm not sure about other editors, but vim provides color syntax to help you write better git commit messages: http://vim.runpaint.org/extending/integrating-vim-with-git/

At the moment if you look at many commit summaries, you'll see a bunch of meaningless issue numbers, each followed by a list of usernames, then if you're lucky and it's a simplier patch then maybe a couple of words describing the patch. Please can we move the usernames to the end of the commit message, so a commit summary is useful?

Current format:

Issue #[issue number] by [comma-separated usernames]: [Short summary of the change].

Proposed format:

Issue #[issue number] [Short summary of the change]; by [comma-separated usernames]

Edit: I've raised this as part of an issue, see #2230579: [policy, no patch] Credit reviewers in commit messages

but i guess this will never change.

That actually makes a ton of sense.

A long while ago, I changed my username from "kepol" to "Kristen Pol". I see "kepol" on my profile page for git attribution, e.g.

--author="kepol <kepol@8389.no-reply.drupal.org>"

Yet information above says:

"Always refer to usernames from drupal.org and not the contributors' Git account names."

So... I'm taking this to mean that the commit message should use the d.o username but the --author value should use the git username (like supplied on the profile page).

I assume this is right but maybe someone can correct me if I'm wrong ;) Thanks!

p.s. My profile page shows me to use:

git config --global user.name "Kristen Pol"

which is confusing since shouldn't this be the same as the git username? Hmm...

[Update] Maybe I found the answer from https://drupal.org/node/1022156

The e-mail address you use when you identify yourself creates the link between your commit and your Drupal.org user, so the value of user.email must correspond to an e-mail address for your account on Drupal.org for you to be properly credited with your commits.

I just noticed that my email address was different in my git config compared to what is on drupal.org so... moral of story seems to be to make sure these are aligned and then it will be able to map you to the right d.o and git accounts.

-Kristen
Blog: http://kristen.org
Drupal 7 Multilingual Sites: http://kristen.org/book

Is there a standard commit message format to use when creating a "follow up" commit? i.e., something associated to a previous commit, or an issue already marked fixed, for example.