Last updated 11 July 2017.

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.

The Credit & committing section of an issue will automatically format commit messages for you, including --author attribution, so that you can just edit the message (it defaults to the issue title) as needed.

Providing non-code issue credits

Note that the Credit & committing UI also allows maintainers to save credit for the issue itself (outside of the git repository). This will record the efforts of all contributors and their attributed organizations, and that data will then be available for display on their profiles.

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: Fix outdated commit message standards

Note the punctuation.

At the bottom of each issue, there is a fieldset named "Credit and committing". It gives you a nice commit message for any issue.

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 an imperative verb

  • Add (new feature)
  • Fix (bug fix)
  • Change (task)
  • Update (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 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, give the issue number, preceded by a number/pound/hash sign (#). This convention is interpreted by the commit log on 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: Add 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: Add 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: Update README.txt

Always refer to usernames from 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
+++ 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: Fix improper use of t() in module install file


A sample commit message:

Issue #46746 by Matt: Fix inconsistent encoding of path aliases

Longer messages are possible, but commonly not used, since the 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: Fix 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 Note, however, that you'll also see non-conforming commit messages there.


sun’s picture

Apparently, no one on 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 'sun' Kudwien

bryan kennedy’s picture

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

[SHORT SUBJECT - Ideally less than 80 char.]
[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.

Thomas_Zahreddin’s picture

As far as i understand

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

mikeytown2’s picture


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.]
dman’s picture

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 :-)
git commit --amend
Lets you update git log messages before you push them

dkingofpa’s picture

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:


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:

ianthomas_uk’s picture

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: [meta] Allow crediting reviewers (and other non-coders) as first-class contributors

sirtet’s picture

but i guess this will never change.

othermachines’s picture

That actually makes a ton of sense.

chOP’s picture

ianthomas_uk, I couldn't agree more with your suggestion. The short format commit message should be useful in a summary format. Having attribution and user details at the end would help. Moving them into the long-format message, or removing them altogether would be even better. Really, we're duplicating information with this attribution that could be better left to a git --author parameter or in the issue queue itself.

This may never happen. It seems that changing the course of the ship takes a lot of effort.

More developers are moving to other git collaboration platforms and using as a simple release publishing and distribution system. This is probably where we should be heading. The team could focus their efforts on supporting the Drupal community in ways that don't involve recreating the wheel or competing with established practices and tools.

Stick with and support existing standards and/or good practice. Allow the community to thrive and choose the tools that best suit the task. Encourage easy transition for new developers coming from other frameworks, platforms and languages.

Madness takes its toll.
Please have exact change.

Kristen Pol’s picture

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 <>"

Yet information above says:

"Always refer to usernames from 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 "Kristen Pol"

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

[Update] Maybe I found the answer from

The e-mail address you use when you identify yourself creates the link between your commit and your user, so the value of must correspond to an e-mail address for your account on 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 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.

Drupal 7 Multilingual Sites:

jwilson3’s picture

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.

joachim’s picture

The defacto standard that core uses, looking at the git log, is:

Issue #12345 followup by name1, name2: Description.

(Though some say 'follow-up'.)

AohRveTPV’s picture

Should users who contribute to a commit, but whose code is not present in the commit, be listed in the commit message?

For example, users who:
- Report issues
- Suggest a code change but do not submit the code (either in a patch or directly in a comment)
- Submit a patch that is not ultimately committed
- Help isolate the cause of a bug
- Review and/or test a patch

geekygnr’s picture

I have been trying to find an answer to the same question.

Perhaps that section should be updated to be more clear as to what is considered a contribution.

geekygnr’s picture

I decided to look at some Drupal core commits and compare them to the issues they fix.

It looks like the only usernames that are mentioned are the ones who actually submit a patch.

I also noticed that there is another part of the commit message that I haven't seen in the documentation. There is a | [issue reporter] on some of the commit messages. I think it is only used when the reporter doesn't submit a patch of their own.

I am still learning the Drupal ways myself so hopefully someone with a little more experience can confirm this and update the page.

AohRveTPV’s picture

Looking at the revisions of this page, it was previously documented that pipe should be used as follows:

If people gave significant contributions to the patch without writing actual code, such as extensive reviewing of large patches, writing an excellent issue summary, or discovering and reporting a major issue, add these users to the contributor list separated with a pipe.

Accordingly, Dreditor automatically adds a user after a pipe according to a formula which is something like:

IF ((issue has >= 10 posts) AND (user's posts comprise 30% of posts))

(I can't recall the exact formula offhand.)

However, the section on using a pipe was subsequently removed from this page with this commit message:

Removed bogus advice on pipes. Please do not interpret incorrect behavior as a means of declaring a recommended standard. You should not retain the pipes, just because some weird user script generated them.

Dreditor still uses the pipe format despite its removal from this page.

So now it seems the pipe should not be used, but it might still appear both due to old developer habits and Dreditor. (I am not aware of other development tools implementing this format.)

The question of whether and how to credit non-code contributions is still an open one.

Charles Belov’s picture

This page might better be started with the first piece of advice being who gets credited, including when to credit non-code contributors. Then deal with how to accomplish that credit.

Charles Belov
SFMTA Webmaster

DYdave’s picture

In page's content the link on "project release nodes" is currently Access denied.
Could somebody with the proper access permissions take a closer look at this page?
Either to remove the link, replace it with something else, or update target page's permissions so we can actually view it.

Thanks in advance!

Davyin Internet Solutions - Drupal in China

markcarver’s picture

That node is for an archived page that references the old CVS methods. The new page is:

I'm leaving these comments here until the page can be updated properly (either by myself or someone else) to also include the recent changes in Dreditor and

mccrodp’s picture

Should these docs and/or Adding a commit author state that " doesn't support force pushes" or "re-writing history"? That the only way to modify a commit e.g. 'author' is to revert the commit, change the author and recommit.

I could not find docs on this elsewhere and got this information from the helpful people over on IRC.

dman’s picture

I've added a note to that effect over at

mccrodp’s picture

Thank you!

DigitalFrontiersMedia’s picture should alert submitters when other people have already submitted the same proposed patch to an issue and alert the maintainer should the second submitter continue with their submission. I used to just shrug off the lack of netiquette in seeing others get credit for patches I'd already submitted, but it has happened a number of times and it's getting old since a certain amount of profile credibility with clients is tied to "how much one contributes."

Cell: 941.773.2036
Phone: 941.677.DFM1 ( 941.677.3361 )
Skype: DigitalFrontiersMedia
Twitter: DigitalFrontier