great article, thanks! somehow i think past tense makes more sense in the commit message.
We were unable to load Disqus. If you are a moderator please see our troubleshooting guide.
Recommending means this is a discussion worth sharing. It gets shared to your followers' Disqus feeds, and gives the creator kudos!
great article, thanks! somehow i think past tense makes more sense in the commit message.
it is always longer than the imperative, without being more informative
Same. It doesn't actually give a single reason as to why to use imperative other than that git itself does.
If
anything, when it's talking about how it should follow the structure
"If applied, this commit will release version 1.0.0", I feel it would
make sense for it to just have it in past tense so you don't have to
follow such an arbitrary convention.
Thank you. I'm teaching this to my students.
Coming back here from time to time and now thought that I could leave a comment.
Often read, Often forwarded. Just a really nice article. Probably one of the best/straight forward articles about this topic.
Fun fact: Today I realized what kind of codebase you must be working on having a look at the the commit messages in detail and also I recognized pwebb :)
Beautiful article, nicely written. This has helped me a lot.
Chris, what do you think about GitKraken?
Just to clarify, what you call imperative, I would say is actually infinitive.
"If applied, this commit will INFINITIVE FORM"
If applied this commit will fix the bug.
Imperative would be:
"Please Chris, IMPERATIVE FORM"
Please Chris, fix the bug.
Though they are written in the same way. Correct me if I am wrong, english is not my native language.
"this commit will fix the bug." is the future tense. The future tense and imperative are not written the same way, because the conjugate in the future tense for regular verbs results in saying or writing "will" before the infinitive: I will go, you will eat, he will leave, we will celebrate, etc. Does that help?
Very well written article. I could use your article, to change the opinions of my team to use the proper / verbose commenting method.
Very good.
But I didn't understood this:
"However, when a commit merits a bit of explanation and context, you need to write a body. For example:"
Could you give me a realistic example (with command ) where we need to write a body?
we can summarize it with be clear and descriptive, and we can add this rules to it (8) Write commit messages in present tense, not in past tense ,and thank you its helpful article
For advanced commit messages you may wanna use this plugin.
https://github.com/sbimocha...
Thank you for the article. If you are interested in a very short introduction into Git and its comparison to other version control systems, I recommend this blog post.
Thanks for this post Chris. I've never really thought about commit messages in this way until now!
Thanks for the tip on "writing imperative commit messages." and Git Pro book is indeed great!
Thanks for the article, it really covers the basic assumptions really well. I also like adding a tags for commit titles to easily filter them out and search through the git history ( like: fix, refactor, feat). It makes the commits even more readable.
Inspired on this I took it a one step further on my blog and extended this information by explaining how to make well-defined commit messages in the productive way using git commit templates.
https://driggl.com/blog/a/h...
If you care about your commits, that might be interesting for you as well.
Can I share this in my blog by chinese?
Yes, and please share the link here when the post is up. Thanks!
Thank you for your license, this is my post in chinese: https://blog.ryoma.top/post...
I'm a bit confused about *why* to use the imperative. Reading the example commit made me feel like the author wanted me to do these things.
The imperative style is because git handles patches, not revisions. Using imperative style is a lot about mindset where you may end up re-ordering patches, dropping some patch, inserting a new patch between some existing pathes, etc. If you label your commits as history you'll automatically limit the way you think about git.
Using imperative style also makes it easier to understand what will happen if you revert (instead of dropping) any given patch.
Note that if you never bother to really learn about `rebase -i`, all of the above may seem just a chore for you.
The reasoning for imperative is that it matches the grammatical mood of messages that Git generates automatically, e.g., merges, reversions, and the like.
Additionally, it matches the tense of how the log indicates what’s happening: each commit does the thing their diff indicates. I.e., as you look at a particular commit, it is not a reflection of what happened, but what is happening.
That's really not a good reason, though--that boils down to "tradition." A good reason to use the imperative form is that it generally allows you to compress information into fewer characters--in English, at least.
What do you think about writing ticket/PR number in the commit header?
I think it's a bad idea, let's strat with that.
But I do see projects that put the ticket/PR number inside the header. Do you think there is a good reason to do that?
Adding the number inside the commit body is great for keeping track of the history why this commit was created, but putting it in the header looks like a random number of a week or two, let alone a year.
I think including ticket/PR number in the subject is okay. I prefer sticking it at the end of the summary like this
Framework: add UI components needed for GDPR conformance #354
Of course, if none of your UIs that you use to view git history support linking from such numbers to correct location, this really does not make any sense. In that case, it's much better to use full URLs in the commit body.
I like to adding ticket identifiers in the PRs, but not in every single commit messages, as there is a limitation of how many characters you can use without truncating it in half.
Instead I like referring tickets and links to issue tracking system in the footer of the commit description.
It woul have been nice to give an example of how to commit long messages in the post, so it is self included =D
Nice one anyway!
what of git commit -m "Initial commit" ?
I try, if I can, to summarize what sort of project I'm starting.
I always do the following:
git commit -m ‘Initialize repository’ --allow-empty
i knew i needed this the first time i didn't know what commit message to write. Informative thanks!!
Nice one. Thanks for the recommendations!
Thank you for nice and helpful article
A very useful article, thanks for sharing your thoughts! But just to clarify these are my thoughts for reflection of the readers:
I agree 80% with this article, I agree with the capitalize rules and the content if necessary, but the article seems to be for anyone who uses a commit message as "changing behavior of X" without plan an strategy for his commits messages.
I think that the author's idea wasn't to define a global restricted rule of commits, but shows that good patterns are required and the title "The seven rules of a great Git commit message" was a marketing strategy.
I think we need to read, analyze and improve the method that better fits for us, he recommends to use "Remove deprecated methods" to me it's like "More code" (using capitalize).
I work with Magento for many clients and the system has an architecture pattern which I use to improve the interpretation of my commits and to anyone be able to find commits fast. I use the rule 3W, for example "[Ticket number] Who > Where > What ", so my commits are small and very understandable, a real use of this pattern is "[IMS-1234] Dotmailer > Model > Remove deprecated methods".
And this is awful.
Sorry but a I'd rather prefer something like:
Remove deprecated methods
Methods removed were:
- Method X
- Method Y
IMS-1234
I would argue that we can always see from the commit diff which methods were removed. Something like Method X removed is about as helpful as saying code changes.
A more helpful message when we re-visit this commit in the future would be regarding why they were removed. What method replaced them, or what functionality was it we were removing.
Great Article !!! One Step Guide to writing Good Commit Messages.
7 Rules to writing good commit messages.
FTFY
Great article. Love the detail about git commit messages and especially the bit about the "imperative" voice.
This is a nice summary but I'd argue against pre-formatting commit messages by applying manual wrapping.
Word wrapping should done by the client that displays the message because that way formatting can happen considering the display size. If you read the commit message in a wide terminal it could properly fill the window and if you read it in a sidebar or on a phone then it could be wrapped accordingly.
You said: "Git never wraps text automatically". It should, and we shouldn't 'solve' a deficiency by creating an other problem.
The conventional format for git commits as shown in this post would still allow for a client to do its wrapping, while allowing viewers in shell environments to see the wrapped text, too. Each paragraph is separated by a blank line, so a non-shell client could recognize these paragraphs and convert the line breaks that do not have a separating blank line into plain old spaces (so that it can do its own wrapping). This is the approach taken when rendering Markdown, for example.
"a non-shell client could recognize these paragraphs and convert the line breaks that do not have a separating blank line into plain old spaces"
Let me make this clear:
The issue is that the command line git client can't wrap the commit message body, so the terminal does it by it's terms. Which is not that bad by the way.
So your solution is to pre-format the text by hand only for other clients to take that formatting, dismiss it, and re-format it again.
... instead of simply adding text-wrapping capabilities to the git cli?
And your solution doesn't even works for lists, for example. Of course it can be extended to recognize lists and a few special cases too, but isn't that just too much work for almost nothing???
Sorry, I'm not trying to be stubborn, It just feels over complicating.
One of the many things I learned as a dev that it's always a bad idea to store meaningless formatting, you should always store data as raw as possible and format as close to the presentation as possible. For the sake of flexibility.
I think it applies here. Regardless of how markdown works.
Unless you want to enforce markdown in git commit messages. That I could support :)
It’s less that “Git never wraps text”, and more about dealing with the behavior of shell & terminal environments. Git, itself, isn’t responsible for the display of its output; the shell is.
Manpages are hard-wrapped, so we’re following the example of other shell-based tools.
Additionally, legibility suffers with very large measures (i.e., wide columns). The Wikipedia page on “line length” details more about this.
The formatting for manpages was defined in the early 1970s, some half-dozen years before I entered the craft. It would be very nice to think we've progressed a bit since then, and that our tools and data formats have as well.
Is there any tool to check commit messages and validate if standards are followed ?