11 ms·
How to Write a Git Commit Message (2014)
- nighthawk454 10y agoWe've used this style in our commit messages for a few years, and it's been great. We also only allow fast-forward merges of squashed commits for our branching strategy. [ISSUE-ID]: Title [Problem] State problem and customer impact [Solution] Describe and justify solution [Test] Describe automated/manual testing
- pmontra 10y agoThe most important tip is "Use the body to explain what and why vs. how". I'd also say: remove thw -m option from git and force people to open the editor. Do not accept messages shorter than 3 lines, start the editor with a template Title What changed and why it changed.
- dtech 10y agoYou can easily enforce this if you want through a pre-commit hook, but this is frankly ridiculous to enforce on everybody.
- ecma 10y agoIt's likely that this would push the tools toward being too opinionated. I spend a lot of time pushing little WIPs so I know where I am and my macros rely heavily on -m, e.g. I end up with a commit message like "WIP: don't merge these debugging lines" or "WIP: Tweak the IO timeout and profile". -m is also useful for making trivial commits, I don't use it for this often because it's easy to violate 50 chars but it's a perfectly valid use of the tool IMO.
- eriknstr 10y agoFor my own commits in my personal repos I often find that less than 80 chars are sufficient to describe the change entirely. I generally don't care about surpassing 80 chars for commit messages though, so even if my commit message is somewhat long I won't split it up. I commit very often and usually small, "atomic" changes most of the time. What I will do, is that I start the commit message with the most important sentence and add less important sentences after, so even if it exceeds 80 chars and you can't see the whole message you will still get the most relevant info without having to scroll sideways. For reference, here are the commits to a project I am currently working on: https://github.com/eriknstr/jumper/commits/master https://github.com/eriknstr/jumper/commits/master
- rosser 10y agoDogmatism like "commit messages must be at least three lines" will result in commit messages like: here's some code. Concentrating on form over substance is myopic.
- petepete 10y agoTotally agree. Using three lines of text to describe fixing a typo in the comments or rewording/reformatting a block of text will just lead to an unclear message.
- tomjen3 10y agoFrom SO: >Git can take the commit message from a file using the -F or --file flags: >git commit -F message.txt So something like echo 'pmontra\n say\n this\n should be several lines' | git commit -F /dev/stdin would get around your block.
- jwilk 10y agoYou want printf, not echo. echo is a very non-portable command. POSIX says: "if any of the operands contain a <backslash> character, the results are implementation‐defined."
- jupp0r 10y agoI really like that Gerrit code reviews allow reviewers to comment on the commit message in the same way as on the code. The way to ensure useful commit message practices is the review process, if you ask me.
- jph 10y agoMy team uses a git commit message convention that helps us read fast and also is parsable by toolchains. We agree on a short list of leading active verbs: Add = Create a capability e.g. feature, test, dependency. Cut = Remove a capability e.g. feature, test, dependency. Fix = Fix an issue e.g. bug, typo, accident, misstatement. Bump = Increase the version of something e.g. dependency. Make = Change the build process, or tooling, or infra. Start = Begin doing something; e.g. create a feature flag. Stop = End doing something; e.g. remove a feature flag. Refactor = A code change that MUST be just a refactoring. Reformat = Refactor of formatting, e.g. omit whitespace. Optimize = Refactor of performance, e.g. speed up code. Document = Refactor of documentation, e.g. help files.
- component 10y agoThis is great Some of the active verbs are also commands that automatically close/reference issues right out of the box on GitHub & BitBucket (& I'm sure on GitLab too)
- bluetwo 10y agoThat's a nice way to standardize. I like it.
- npolet 10y agoThis is a really nice way doing commits. It's the kind of simplicity that can be made into a simple document and shared easily, or printed out and put somewhere everyone can see. Might try and get my team into using this. At the moment our teams commit messages are a mangled mess of everyone's own 'commit language'. It can be really tricky to quickly scan over commit logs and get a feel of where development has been heading over the last x weeks.
- amcrouch 10y agoGreat idea, I'm gonna steal this.
- jph 10y agoFeedback on this git commit message convention is welcome, and so are pull requests: https://github.com/joelparkerhenderson/git_commit_message https://github.com/joelparkerhenderson/git_commit_message
- SEJeff 10y agoHow to write good git commit messages literally from the person who wrote git (Linus Torvalds): https://github.com/torvalds/subsurface-for-dirk/blob/0f58510ce0244513521296b75281fcc32f72a931/README#L92-L119 https://github.com/torvalds/subsurface-for-dirk/blob/0f58510... I always send this to people as I teach them git.
- tyingq 10y agoSome more from Linus: https://github.com/torvalds/linux/pull/17#issuecomment-5663733 https://github.com/torvalds/linux/pull/17#issuecomment-56637...
- deleted 10y ago[deleted]
- ratherbefuddled 10y agoDoes nobody else require there to be at least one issue tracker reference in the commit message these days? It makes automating stuff like release notes much easier.
- emodendroket 10y agoSo then you have like fifty hashes attached to the ticket?
- data_hope 10y agoMy personal, subjective impression: Commits are getting smaller and smaller nowadays. As in: In the subversion days, many people commited only few times a day, sometimes not for several days. SVN commits of course involved a sync with the server (a "push" in git lingo), and thus usually represented a much larger increment with a substantial change to the code base [X] With git, it became very common to structure changes to a code base in many, very small commits. Rename a variable? Commit. Write some docs? Commit. Of course, the overall changes when developing a feature did not become smaller, they are now just distributed over many more commits. So I'd argue that a SVN commit was often conceptionally closer to what we now have with a git pull-request. Why does this matter? Because It is kind of hard and not helping anyone if you describe your renaming of a local variable with an extensive docstring. What I do miss however, is a good description of the overall change. I.e. now often the description in the merge commit is just the autogenerated message, but this is where I would like people to really take the time and describe the change extensively. This is why I like `--squash` merges, because they let people focus on the relevant parts in their description. I know, rewriting history is bad, but overall, I favour reading a history book than 18th century newspapers. [X] not saying that there weren't small one-line-change commits, but overall they were rarer.
- robbyking 10y agoUnfortunately, I'm guilty of the opposite: I rarely, rarely commit. Maybe one commit per point. I have to consciously remind myself to commit more often.
- greenhouse_gas 10y agoWould be interesting if there was a way to annotate a set of commits, like "commit ???? - ????: refactored A,B, and C" so you'd get the advantage of small commits and clearer messages.
- data_hope 10y agoI think you can do that in a merge commit, sort of. The more I think about it, the stranger a strong aversion to rewriting commit history for clarity is. In university if I did some math / physics calculation, I would often start, and once I got somewhere, make a clean copy of the successful work to have a concise and revised version.
- stared 10y agoI really recommend angular-style commit messages: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md https://github.com/angular/angular.js/blob/master/CONTRIBUTI... type(scope) message e.g. feat(button) added play button Types are: - feat: A new feature - fix: A bug fix - docs: Documentation only changes - style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) - refactor: A code change that neither fixes a bug nor adds a feature - perf: A code change that improves performance - test: Adding missing or correcting existing tests - chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
- tazjin 10y agoAgreed. I started using these on private & professional projects a year ago (and mostly got the team to use them, too) and it's a pleasure to browse the git log! In the beginning the definition of "scope" is a bit wonky per project. However, once it solidifies you can easily start going through your log looking for "feat(endpoint)" to find new routes that have been added to an API for example.
- ericnkatz 10y agoI started using https://commitizen.github.io/cz-cli/ https://commitizen.github.io/cz-cli/ to help me self-enforce this style of commit messages.
- jph 10y agoIf you like this format, then you may want to try a similar format that uses the same purpose, plus uses words that easier to read and that make more sense to people in more cultures. We use Add, Fix, Refactor, Reformat, Optimize, etc. See my comment on this thread or https://github.com/joelparkerhenderson/git_commit_message https://github.com/joelparkerhenderson/git_commit_message
- stared 10y agoI don't mind command names. However, in the linked article no visual separation between type and message (and no scope) is something I consider less useful.
- gregmac 10y agoThe only one that really drives me crazy is > Wrap the body at 72 characters Why? Because the git CLI doesn't wrap properly? To borrow a quote, that seems like a 'you' problem, not a me problem. Maybe I'm just biased because these days I almost entirely interact with git through a GUI (either desktop client or web interface), and though I use the CLI occasionally (mostly for branch management, sometimes for quick commits) I can't think of the last time I used it for any type of history viewing -- pretty much any GUI is going to do a better job of that. My team often uses markdown (mainly bulleted lists) and the output looks terrible when you insert manual line breaks (because markdown interprets that as meaning that you explicitly want a line break there) and you're viewing it on a screen/viewport that is either larger or smaller than 72 characters wide. Unless you're explicitly using a publishing format (eg, LaTeX, PDF, postscript), the function of wrapping text should be a concern of the rendering of the output, not the origin. Am I missing something here? Is there any other reason to manually wrap text besides the git CLI's handling of it as a viewer?
- nitemice 10y agoSounds like your markdown interpreter has an issue, or you're leaving lots of white space at the end of your lines. Generally, in markdown, if you insert a line break, it won't translate to an explicit line break unless you put two in a row, or if there is 2+ spaces at the end of the line. See [1] for an illustration [1](https://johnmacfarlane.net/babelmark2/?text=This+line%0Ashould+not+be+broken.%0A%0ABut+this+one++%0Awill+be. https://johnmacfarlane.net/babelmark2/?text=This+line%0Ashou...)
- steveklabnik 10y agoEither behavior is allowed by the CommonMark spec, in fact.
- ajross 10y ago> Why? Because the git CLI doesn't wrap properly? First off, the commit message is plain text (by design) and can't be "wrapped" automatically, and any tool that tried would be insane. The reason for 72 characters is that the CLI, like lots of other presentation mechanisms (including quoting in other commits or in code), wants to indent your message for readability. And the uniform standard width for terminals has been 80 characters for like four decades now. Must it be? I dunno. I can imagine a uniform agreement among a broad team that everyone will assume a 100 character line and all tools should enforce that. Maybe a little more, but not that much because even on a modern screen you want to have two full terminals of text readable at a time. But that's just a number. You'd still be told by your commit message style guide (or checkpatch.pl, or whatever) to wrap your lines manually at 92 characters. Is 25% more bytes on a line really worth yelling about?
- trjordan 10y agoThere are so many articles like this, and all of them focus so much on prescriptive rules for commit messages. There's a similar set of articles on how to deal with branching and merging. Somehow, everybody comes to slightly different conclusions. The discussion that needs to happen before this is to understand what tools you want to make available to your developers in the future. Using git's history as a first class debugging tool is powerful, but it's by no means mandatory to provide. There's also a real cost to providing each of the tools. - Do you want bisect to be available? Well, then you should have most commits represent a fully-functional version of the software. Consider squashing branches when you merge them. - Do you want narrative documentation around strange choices? Fine-grained commits are a great place to put those thoughts, but they may discourage devs from writing those thoughts in inline comments. - Do you want ownership via git blame? Line-by-line changes may help you identify who wrote the code, but that might prevent your developers from ever fully transferring ownership, which could create bottlenecks in startups that have a few long-tenure devs and a lot of recently hired devs. I really like to think of git history as a context tool, like monitoring or unit testing or documentation. It's worthwhile to sit down with your team, define what you want them to be able to do with commit history, and build your commit style from there.
- sleepychu 10y agoI've been writing commit messages this way for a little under a year (I think this is the same guide I used when I was looking for a more consistent form to write them and to avoid the dreaded -m "Fixed some things"). One thing I noticed is that it's increased my confidence in my commits; at the moment that I go to write the commit message because I'm describing why I made the decisions I did it breaks logical inconsistencies between what I've actually done and what I think I've done. If I'm able to explain all the change I'm much more confident that it's correct. Another is that bad commit messages have trained people not to read them. Often people will ask why I've made a change and then discover that the commit message contains the answer to their question!
- nimchimpsky 10y agoI can't believe believe people write essays on how to write a git commit message. It even includes an example of not including a full stop - I'm all for examples, but sometimes they are not necessary. Do other people not have actual work to do ?
- jlgaddis 10y ago(I haven't written such an easy. Regardless...) I can't believe people whine about ways I spend my time (or what I choose to write about). It's not like you are being forced to read any of it.
- nimchimpsky 10y agoits been submitted to a message board for comments, did you expect everything to be positive ? GIT commit message are hardly significant, unless you are doing some form of automated release notes - and then you just follow whatever convention is required.
- aduitsis 10y agoThis reminds a recent tweet by Rob Pike: Goals imposed by git: Commit subject < 65 "chars", commit message lines < 70 "chars". All in service of the punch card god Hollerithus. https://twitter.com/rob_pike/status/837410954518286337 https://twitter.com/rob_pike/status/837410954518286337
- amenghra 10y agoUseful things to have in a commit message: - Test plan when there's no unit test (describes how to test that the patch actually works). - Task ID (link to whatever is used to track tasks/bugs, as there's usually more context there). - Blame rev when a patch fixes a bug, it's useful to know which commit introduced the bug.
- jononor 10y agoBlame rev is very useful for back/forward porting fixes.
- jdiez17 10y agoI've found that writing commit messages by stating the problem in the subject, and an explanation of the solution in the body makes them very clear and descriptive. For example: Problem: Windows build script requires edit of VS version Solution: Use CMD.EXE environment variable to extract DevStudio version number and build using it. I got the idea from ZeroMQ's/hintjens' various repos.
- achr2 10y agoThe main issue with commits is that they end up representing more than a single logical change. Are there any tools that allow you to initiate a commit as an 'intention stack' for work I am about to do, rather than work I have already done? I'd love to be able to write an intent message "refactor XYZ.." before starting in on that activity, then when I have to go down another rabbit hole in the middle I push another intent message to the stack, then pop back out afterward and continue with XYZ. The final overall commit message could be auto generated from the initial intention and all tangents.
- jononor 10y agoCommit each of the changes you make, including possible detours etc. Then use git rebase -i to work it into a sane history later.
- phailhaus 10y agoGit has zero opinion on when you commit or what the messages are. Commits are made in private. Commits are also immutable. This is a losing battle. If you use a code management tool like BitBucket or GitHub, it seems like the unit of work is less a commit and more a PR. A PR's description can always be edited and refined for future engineers, and a PR (almost) always represents a block of work that can be reverted. Instead of creating a hundred different approaches to writing commits that engineers essentially have to get right the first time, why not just focus on documentation in the form of PR's? It seems like if you could trivially tie a commit back to the PR and ticket it came from, most of these problems would be solved.
- CydeWeys 10y agoPrivate commits aren't immutable at all. You can change anything about them up until you push them to a remote repository that other people are syncing from. I routinely squash a bunch of private commits together before issuing a public PR, for example.
- andrewshadura 10y agoNo they are. You can create different commits replacing them though.
- CydeWeys 10y agoCalling commits "immutable" is thus verging into technically correct, but misleading and thus not useful territory. It's giving people the impression that commits are set in stone the moment they are made, when in fact this is far from the truth and you can go back and rewrite them, insert new commits between existing ones, squash them together, remove them entirely, etc. The only "gotcha" to watch out for is if other people have synced your changes; then you start having problems.
- andrewshadura 10y agoFTR I agree, I just pointed out a technical incorrectness.
- dlandis 10y agoHe mentions using the imperative mood for the subject line, but doesn't anyone else think it makes more sense and sounds better to use the present tense, e.g. Opens the pod bay doors Instead of Open the pod bay doors ?
- deleted 10y ago[deleted]
- sleepychu 10y agoMaybe but it's nice to fit in with the existing imperative mood in the automatic commits (Merge x into y) You can read them in your head like this "Applying this commit will $MSG"
- CydeWeys 10y agoWe've been using this format on our project for over a year now. Our commit history looks nice as a result: https://github.com/google/nomulus/commits/master https://github.com/google/nomulus/commits/master
- ibgib 10y ago1. Git commit templates. 2. Emoji. 3. Bullets in body. 1. Any article on structured git commit messages should mention git commit templates! https://robots.thoughtbot.com/better-commit-messages-with-a-gitmessage-template https://robots.thoughtbot.com/better-commit-messages-with-a-... I use a commit template for structure, as well as reducing boilerplate for expressive messages. Here is my default template on ibgib: https://github.com/ibgib/ibgib/blob/master/git-commit-template.txt https://github.com/ibgib/ibgib/blob/master/git-commit-templa... 2. I also use emoji (with a key there in the git commit template for reference) to communicate concepts like implemented, bug fix, etc., in a single emoji character. Note though that it is inappropriate when you start to do a pull request, as not all git message viewers will display the emoji. But I find it very useful FTMP. 3. Bullets are a simple way to enable both terse and structured comments within a commit.
- kevinmannix 10y agoI've really welcomed the recent GitHub features such as "squash & merge" and "rebase & merge". Instead of parsing through 200 commits of "typo", "lint", "spacing", a feature is placed in a compact diff with the feature title & related task id as the commit message. A commit should be a unit of work. Tests should pass before and after. The commit message should describe the change. Ensuring that you have a good commit message then influences what content you contain in a commit.
- bjourne 10y agoIt doesn't matter that much. Some things in programming mater a lot, like consistent indentation and casing. Some things doesn't, like perfectly formatted commit messages. whether the verbs in commit messages should be in imperative or present tense is just too much. I can tell you that I have been programming for a very long time. So if someone asks me "Why does it MATTER if lines are longer than 80 characters?" then I can answer "Because it means that the distribution of line-lengths will be more uniform, meaning that you will be able to fit more code on the screen, meaning that the amount of scrolling you'll have to do when trying to understand the code is greatly reduced." And scrolling interrupts your focus, which is bad. But if I ask someone, "Why does it MATTER if verbs are in present or imperative tense?" no one can answer.
- niteshade 10y agoOne reason I can think of for using the imperative tense is to use commit messages to generate changelogs. AngularJS does it this way, wouldn't be surprised if there were others.
- sandrot 10y agojust going to leave this here: http://stopwritingramblingcommitmessages.com http://stopwritingramblingcommitmessages.com
- pbosko 10y agoMy team uses task number and title as a commit message. We just can't fit all the description from task into one line of comment. So, when we look at git blame - we get a reference to a task in project management tool where we can find all the reasons behind a given change. If there are more commits for the same task, all of them bare the same commit message. After each review, we add a comment to project management tool. That way we focus only on newer commits when performing another round of reviews. Every other attempt to describe changes and intentions in one line seems doomed to me.
- sqldba 10y ago.