15 ms·
Write good git commit messages
- amelius 8y agoOr integrate with an issue tracker and/or project management tool, and you'll get: 43ec6aa Fix issue 1001 4fe84ab Fix issue 1002 753aa05 Implement feature request 1003 df3a662 Implement spec 1004
- V-2 8y agoNow you need to look up what 1001, 1002 or 1003 are. It takes time and makes you unable to skim-read the commit history. Also projects are often migrated, offshored etc., and it's not rare for repositories to get uncoupled from the ticket system. Now "1004" tells me nothing, because I've got the source code and VCS history, but no access to the original Jira where the issue was reported.
- mavidser 8y agoI really hope this was sarcastic.
- k_ 8y agoI'd say _add_ issue tracker reference, not replace the description with it 43ec6aa Fix error when the URL is not reachable (#1001) 4fe84ab Add error message if something went wrong (#1002) 753aa05 Add server fingerprint check (#1003) df3a662 Fix shadow box closing problem (#1004)
- wirrbel 8y agothis. Issue trackers like JIRA can be configured to search for commit-Ids in the messages, which will give you all commits associated with a ticket. Adding ticket IDs to commits has fallen a bit out of fashion since feature-branches and pull request workflows have become popular. But adding the ticket ID to the commit messages allows for trunk-based development style, while not losing the ability to make a code review over the commits referencing a ticket. Most of the time I write the ticket ID in the text below, which keeps the `git log --oneline` pretty, the tools can still pick it up.
- deadbunny 8y agoYup, though I usually put the ticket number in the body of the commit rather than the title.
- mcv 8y agoI tend to put it in at the front: 43ec6aa [1001] Fix error when the URL is not reachable 4fe84ab [1002] Add error message if something went wrong 753aa05 [1003] Add server fingerprint check df3a662 [1004] Fix shadow box closing problem That makes the corresponding issue easier to find.
- adtac 8y agoMe too, but I put a full hyperlink to the github/gitlab issue in the body instead of just the number so that someone can just click and start reading what it's about. It also creates a back-reference on the issue page in some web-based issue trackers like Github.
- izacus 8y agoHow about an actually informative and useful alternative: 43ec6aa Fixed crash when network fails mid transfer (#1001)
- mcny 8y agoThe meta is to use present tense (If you apply this commit, it will) fix the button.
- Etheryte 8y agoI don't really agree with this approach, you should use either tags or branch names to link issues with git, commit titles are not the right place. It's very common for an issue to span multiple commits, this solution feels insufficient. If you feel it's necessary, you can add the issue number to the commit message body, but as a title it's not that useful. Humanly readable titles are the best option, if I need to find something I will be using git log or grep anyway.
- chrisweekly 8y agoI respectfully disagree. Regardless of branching model, why not use commit titles like: `{Jira-1234} ADD flux capacitor control module` ... and put more verbose details in the commit message body if/when needed?
- pythonaut_16 8y agoI think the opposite tends to be more helpful. The title should give you as much information as possible at a glance since it's likely to be seen in a list of commits or as part of the history of a file or line of code. The more verbose details and ticket id should be in the body since I'm more likely to care about them once I've pulled up the commit to review in detail.
- chrisweekly 8y agoNot to belabor the point, but once you're familiar with the contents of a given ticket (the "{Jira-1234}" reference in my example), the commit message titles' information density goes way, way up. Adding this ~12-character prefix results in useful, scannable, one-line commit messages. I see no downside.
- maaarghk 8y agoIt's true though, I've seen this all over the place.
- skinnyasianboi 8y agoI will redirect the article to my boss and coworkers who are not conviced to commit with "Fix/Add/Update".
- Vinnl 8y agoMy favourite anecdote about this is an old coworker of mine who, at a certain point in time, had a number of successive commits with the commit message being his first name.
- rocqua 8y agoI mean, if he's called Peter, and 'to Peter' has come to mean something like 'fix tiny typos' then a commit that says 'Peter' kind of makes sense.
- ttty 8y agoYou should always put the Jira/story id in the merge commit at least.
- laurent123456 8y agoOn GitHub you can also auto-close issues using certain keywords. I use "Fixes #123" for bug fixes and "Resolves #456" when completing features. The nice thing is that it will link to the issue in the GitHub commit history.
- bryanrasmussen 8y agounless your branch name matches the jira/story id
- dasmoth 8y agoThis seems to have become really pervasive the last few years, and I recognise it’s sometimes driven by regulatory/certification requirements. But in the absence of those, what does this gain you over putting a sentence or three of human-readable motivation into the commit message?
- detaro 8y agoAll the context from the issue that doesn't fit in a sentence or three?. Of course it depends, if the issue doesn't have context it's not important, but things like "who requested/reported this", "who was involved in decisions made", "what alternatives were considered and why where they rejected" might not necessarily fit in the commit message but exist in an issue.
- vishnu_ks 8y agoIf you enjoy this article you will find the Zulip project's commit guidelines interesting as well :) https://zulip.readthedocs.io/en/latest/contributing/version-control.html https://zulip.readthedocs.io/en/latest/contributing/version-...
- tqkxzugoaupvwqr 8y agoQuestion: I use past tense instead of present tense because I explain what changed. But I see a lot of commits written in present tense. Is one better than the other? Which one?
- detailyang 8y agoditto
- FelipeCortez 8y agoGit itself uses the present tense (Merge/Revert)
- michaelmior 8y agoThis for me is the main reason I prefer to use present tense since it maintains consistency.
- Double_a_92 8y agoPast tense doesn't describe what the commit does, it describes what the developer did.
- rocqua 8y agoThis. The point of an imperative present tense voice is to consider the message from the point of the commit, not from the point of the committer. Commit messages aren't meant to show you did work, they aren't meant to show what work you did either. They are meant to show what changed.
- deleted 8y ago[deleted]
- syn0byte 8y agoYou mean "what changes." Consistency dammit!
- 8y ago
- InGodsName 8y agoWhen i Opensource project, i hire freelancers to beautify my commit messages. It makes all commit messages sound like a story where one innovation leads to another.
- bauerd 8y agoSurely this is a joke? You hire someone to clean up your commit messages?
- InGodsName 8y agoNo it's not a joke. Aesthetics matter. Look at my latest comment, it's part of the package.
- pferde 8y agoPeople hire other people to clean up their houses, why not commit messages? :)
- cygned 8y agoI always recommend this article: https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/ The recommendations are the same, it's longer and provides more rationale at some points.
- CydeWeys 8y agoYeah, it's the same advice, just Chris Beams did it over 4 years earlier. This is the article I always link people to on my team when explaining how to write commit messages. My company doesn't have a style guide for this exact thing, so this article is what I've been using. And the results are here: https://github.com/google/nomulus/commits/master https://github.com/google/nomulus/commits/master
- doanguyen 8y agoThanks, very good read. It helps me realize not only how to write comments but also when to commit.
- muratgozel 8y agoThe content of commits should be like Medium articles. I give up when I see it in the command line.
- stroebjo 8y agoI would recommend to also look at this guideline + tooling to create an automatic changelog based on your commits: https://www.conventionalcommits.org/ https://www.conventionalcommits.org/
- shouldnt_be 8y agoI always force myself to write good commit message. But I often ask myself if it is really useful or if I'm just too tight and want things to look good. This standard might be useful for library maintainers in the cases stated here: https://www.conventionalcommits.org/en/v1.0.0-beta.2/#why-use-conventional-commits https://www.conventionalcommits.org/en/v1.0.0-beta.2/#why-us... Like having everyone using the same guidelines (code style) when writing code. This might also be useful if everyone use it.
- StapleHorse 8y agoHaaaaands!!
- agumonkey 8y agoHaving checked out a forgotten 3yo fork I realize how this could be .. important.
- jimmytucson 8y agoMy take: these aren’t good commit messages. The verb isn’t supposed to be what you did, otherwise it would always be “add” or “change” or “fix”. The verb is supposed to be what the program does thanks to this change. E.g. “Check server fingerprint”, not “Add server fingerprint check”. We already know you changed or added something, it’s a git commit.
- MatekCopatek 8y agoBut how would you name the commits that fix, refactor and remove that same feature? "Check server fingerprint with less errors", "Check server fingerprint in a different way" and "Check server fingerprint no more"?
- matthewmacleod 8y ago“Handle timeout errors when checking server fingerprint”, “Use new API endpoint for server fingerprint”, and “Replace server fingerprint checking with magic”. You can still use those verbs, but the interesting thing in commit messages is what they do, rather than what changes you made. A commit message is really like a small note to future contributors; it’s not always easy to write them, but it’s always worth thinking about them from the perspective of someone who is looking at them two or three years hence.
- usrusr 8y agoBut "Replace server fingerprint checking with magic" has clearly crossed the line from "the verb describes what the code does" to "the verb describes what the developer did". "Note to future contributors" is spot on of course. The best way to write better commit messages is to consume the existing corpus as often as possible, e.g. by never trying to understand code without the blame column active in your editor of choice. My preferred format is a condensed why-what, consisting of "$verb $ticket $wherein": $verb would be the developer activity, like fix/optimize/remove/.., and it is mostly there to make it clear that the rest of the message should not describe developer activity. $ticket would reference your beloved issue tracking system (an additional short keyword describing the issue doesn't hurt as a checksum and to prevent excessive referencing, but it has to be optional because a bad keyword is worse than none). $wherein would be the customary quick rundown of how the code is supposed to work, expect future readers to only read the beginning. I like this order because it gives a rudimentary sentence structure to the formulaic parts and positions them at the beginning where they can never be pushed below the fold by the potentially rambly description of the code. Anything more complicated than that will degrade harder when rules are not followed to the letter. Perfect is the enemy of good.
- ft_TI-84 8y agoDefinitely works better than " "
- cpburns2009 8y agoI frequently use "." because my commits are all over the place. I know it's a bad habit.
- scrollaway 8y agoWriting good commit messages is one of those things that IMO make the difference between a dev who produces good code, and a dev who produces high quality work in general. The git log is one of the main entry points to an open source (or closed source, in fact) project. Following them tells a story, and can help you understand decisions made. Imagine you have two projects to bisect. One of them has clean, atomic and descriptive commits. The other has a git log that looks like this: https://github.com/pypa/pipenv/commits/master?after=d4d54eeb39ef45a9b68c78b8fc8f66c3f5396691+1154 https://github.com/pypa/pipenv/commits/master?after=d4d54eeb... I know which one I'd want to debug. This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. The thing is that writing clean commits is something that is extremely easy to do. Unlike docs and tests, it's not more work (it's less, in fact) and it's not something to continuously maintain as the code changes. It's an immediate improvement you can make to your development habits that will have a consequential improvement to your QOL. You will catch bugs doing this! (Tip when writing atomic commits: Use `git add -p`. That lets you stage patch hunks.)
- rocqua 8y agoI've had something like `git add -p` in my mind for a while now, thanks for pointing me in the right direction! It was one of the few things left in git where I prefered IDE's over the plain command line.
- abhishekjha 8y ago>This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. I am new to git. You will have to merge eventually with somebody when you are collaborating. Can you really avoid merge commits? I don't like how `git reflog` keeps track of which hash did I switch to. I only jump to hashes for a quick run. I don't want it actually tracking that in the log. Does anybody know how to avoid that as well?
- aviraldg 8y agoYes, you can rebase: https://www.atlassian.com/git/tutorials/merging-vs-rebasing https://www.atlassian.com/git/tutorials/merging-vs-rebasing (best used with --ff-only in your config to avoid unnecessary/unintentional merge commits)
- Memosyne 8y agoI've been using the commitizen prefixes (feat/fix/docs/style/refactor/perf/test/chore) but I've noticed that they make messages lengthier and a little more difficult to understand. I really wish git would have a built-in category system so that I can automatically generate changelog headings (features, tests, etc...) without sacrificing the legibility of commit messages. Git clients could display this information alongside the message (think of how Github displays the short commit hash).
- hyperpape 8y agoEmoji to the rescue! https://gitmoji.carloscuesta.me https://gitmoji.carloscuesta.me
- scrollaway 8y agoI have always been extremely peculiar about commit messages and IMO the commitizen stuff (aka "semantic commits") is one of those things which is only useful if you personally find it useful and you are the only one working on your project. I have never seen it work in a team of 2+. People mix up what each prefix means. Hell, I've seen someone "use" it but only ever use "feat:" even for typo fixes. I ended up rewriting his entire git history to strip all "feat:" instances from the commit message since they were just noise. Basically the only time I've seen it work is when all the following is true: - You're on a solo project - You commit a lot - You're very consistent with your prefixing - You want to use those prefixes to generate changelogs. … then it's useful. Otherwise, it's noise.
- Outpox 8y agoI disagree, we've been using it with friends of mine and I enjoy it. The main reason is so that's it's easier to generate a changelog as we're following the Angular commit guideline. I would consider Angular a successful project and this is their git history: https://github.com/angular/angular/commits/master https://github.com/angular/angular/commits/master
- scrollaway 8y ago
- glutamate 8y agoDisagree. This is creating barriers for people to commit early and commit often.
- z3t4 8y agoI want to know why. I can already see what you did by looking at the diff.
- jstimpfle 8y agoWhen you need an overview what happened in the last week, do you prefer to always restrict yourself to scanning 10k lines of diff (which may be missing relevant context)? Wouldn't a screenful of short commit log be helpful?
- dasil003 8y agoSure, but you’re talking about the body of the commit message, the 50-char header is all about what in a terse, scannable format.
- navinsylvester 8y agoI use the following convention to start the subject of commit(posted by someone in a similar HN thread): 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.
- hmcdona1 8y agoThis is similar to the Conventional Changelog: https://github.com/conventional-changelog/conventional-changelog https://github.com/conventional-changelog/conventional-chang... I often use a customized Commit Lint in combo with Husky to enforce conventional changelog messages: https://github.com/marionebl/commitlint https://github.com/marionebl/commitlint https://github.com/typicode/husky https://github.com/typicode/husky You can also throw in something like the Commitizen cli for newcomers: https://github.com/commitizen/cz-cli https://github.com/commitizen/cz-cli
- nindalf 8y agoAnd my personal favourite - REMOVE. I made like 5 diffs in the last week where I just removed old shit that wasn't needed. I felt absurdly happy after each one.
- buttholesurfer 8y agoWe started using commitizen at my workplace. It really seems to push the idea of good commit logs. Combined with jira ID hooks to keep people from pushing without a story/ticket. https://www.npmjs.com/package/commitizen https://www.npmjs.com/package/commitizen Edit: doh, didn't scroll to the bottom!
- TbobbyZ 8y agoWhat's the point of adding a sentence or two to a commit message? I only include a keyword and the issue number, e.g. "Closed #41" or "Fixed #41". This will link the commit to the GitHub issue, which will allow any users to see all the details they need about what was involved in the commit message.
- rco8786 8y agoThat’s not particularly helpful if you’re looking back through git logs or at a git blame. Unless you’ve memorized the context of every github issue you have. Also what if you move from github to bitbucket? Or self hosted git? Git provides a great way to keep your changelogs directly next to the code, why not use it?
- dasmoth 8y agoIt's drastically less helpful if anyone ever wants to look at the code separate from whatever issue-tracker you're currently using. Are you confident those IDs will be preserved (in a useful form) if you ever want to migrate away from Github?
- Amokrane 8y agoThis assumes that you have access to the issues page. That's not always the case (when working as a contractor for instance). Also, tickets are not always filled properly, and often changes are not accompanied by a ticket. You get so many bonuses from writing good commit messages: -> Overview of the latest changes without having to open additional links. Very handy for git bisects for instance. -> Automatic generation of change logs. -> It enforces changes that are purposeful and well scoped. -> Knowledge stays with the Git repo. No data migration issues if you decide not to use GitHub anymore for instance... -> And finally... it really just looks nice and professional. I would not take a project seriously if the Git log was just an aggregation of WIPs and Oopsies.
- Brosper 8y agoWe use commitizen and it's working well. We also autogenerate CHANGELOG.md
- arrty88 8y agoDoes merging / squashing kill good commit message?
- NateEag 8y agoGood commit message summaries are important (the short one-line overview). Including links to the issues the commit relates to in the body is important. That said, most of what I've seen in large commit message bodies (like the ones I used to write) really belongs in the patch itself, as changes to the project's formal documentation or source code comments. If you thought it was worth explaining why you made the change as you did, it likely means the choice was not obvious. If it wasn't obvious, the explanation belongs in the project proper, where anyone who cares can see it, not tucked away in a commit message that may be hard to discover four or five years down the road. If it's a decision that impacts UI, the justification belongs in the project specs or docs, where people besides devs can find it (I like to keep my specs and docs as plaintext in the repo and render them to HTML for non-devs to reference). If it's a strictly internal decision, like what algorithm you chose for a function's internals, you should explain why right there instead of hiding valuable knowledge in the commit message.
- u801e 8y ago> If it wasn't obvious, the explanation belongs in the project proper, where anyone who cares can see it A lot of times, code comments may not be updated along with code changes, so they may not be accurate. A commit message is associated with a change at the time it was made. > not tucked away in a commit message that may be hard to discover four or five years down the road. The git blame command makes it pretty easy to see what commit introduced a line of code and it also makes it easy to see the context of the change (the rest of the diff). > If it's a decision that impacts UI, the justification belongs in the project specs or docs, where people besides devs can find it There's no reason that it can't be recorded in both places. > If it's a strictly internal decision, like what algorithm you chose for a function's internals, you should explain why right there instead of hiding valuable knowledge in the commit message. But let's say you want to make a change to the method and you have a comment explaining the change there. Now you make a change to the method and some other part of the code breaks. If you looked at the commit message instead, you can get an explanation and the context of the change (meaning the other parts of the code that relied on the original change you're looking at).
- 8y ago
- ronjouch 8y agoMeh. This post is not harmful, but focuses on syntax and fails to insist on the most important thing: tell WHY you made the change; the what and how are already apparent in your code. See Greg Ward at PyCon 2014: "Documenting history, or How to write great commit messages". His talk starts at 6:07. Direct link: https://www.youtube.com/watch?v=Jb6ij4eRu6c#t=367 https://www.youtube.com/watch?v=Jb6ij4eRu6c#t=367
- joe8756438 8y agoThis is exactly right. It's easy enough to see WHAT happened by looking at the code. Of course you can document the WHY in code also, but that usually ends up in a comment that gets out of date. Whether you're trying to figure out why the shit hit the fan or understanding a new codebase: commit messages that explain reasoning are gold.
- tobeportable 8y agoI still follow my past team definition of a good commit : the commit message should answer in it's first line why this commit was done. Overtime I realized that when I git blame I never care what a commit does because this is always obvious by reading the code of the commit. The reason why, however, is most of the time not obvious at all.
- TuringNYC 8y agoFor me, an ideal git commit message is one that also links to a bug or feature ticket. Both {Github+Github Issues} and {BitBucket + Jira} support this almost seamlessly, I imagine other systems do as well.
- IE6 8y agoI agree here. OP's article mentions Chris Beam's page [1] and I have all our developers follow that structure which helps but ultimately the biggest strength is the final line with the link to our JIRA. [1] https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/
- jph 8y agoGit commit message: https://github.com/joelparkerhenderson/git_commit_message https://github.com/joelparkerhenderson/git_commit_message How to write better git commit messages, as a repo README. For example, we use wording Add/Fix/Optimize/Refactor and semantic versioning, etc. Git commit template: https://github.com/joelparkerhenderson/git_commit_template/blob/master/git_commit_template.txt https://github.com/joelparkerhenderson/git_commit_template/b... You can use a template to improve git commit messages, that prompts for writing "Why" you are making a change, and any co-authors, and any links, etc. Constructive advice welcome. I'm the author.
- Doches 8y agoI'm a big fan of outsourcing this sort of discipline to tools -- check out [Komet](https://github.com/zorgiepoo/Komet https://github.com/zorgiepoo/Komet) for a commit-specific text editor that makes it easy to write better commit messages.
- BlackFly 8y agoThese sorts of prescriptions always strike me as the sort of fastidiousness that some software developer types are stereotyped with. Just once I would like to read someone that takes a descriptivist approach to commit messages instead of a prescriptivist approach. I would prefer even a scientific approach where someone sets out to measure if these sorts of measures have a concrete measurable effect beyond people's anecdotal preferences. Prescribing what a commit message can look like implicitly prescribes what a commit can look like and that turns a flexible tool into a less flexible one. For many people, lack of flexibility can be a feature... but it is an empirical question on whether or not if it aids development and I am not really aware of anyone trying to measure these things. In the spirit of "No silver bullet," by Fred Brooks, I am skeptical that between the code comments, the code documentation, and the ticketing system that the git commits are adding much.
- nielsbot 8y agoHear hear! (I think we're in the minority)
- protonfish 8y agoThere does seem to be a strong lure to the ease of cargo-culting over being thoughtful. I guess I am always surprised that it is such a problem in software development because we pride ourselves on using our minds to solve problems.
- majikandy 8y agoBest comment I read so far on this. Taken a stage further, a well written codebase of self-documenting tdd’d clean code and commit messages become moderately useless. For all the effort they take and the rare occasion they aid in finding something useful, a completely blank entry for every commit is arguably more efficient. In the spirit of it only taking a few seconds whilst your head is in that space, a short brain dump of what it is in any format you like is an excellent and efficient choice.
- MacroChip 8y agoThis is something I put significant effort into. Same thing for test names. Most importantly, I explain why I did something. A test name "testFilterSpecialCharacters" adds no documentation. "testFilterSpecialCharactersBecauseSpecialCharactersCrashTextBoxLibV1_3" is way better. It adds documentation and context that don't exist in the lines of code in the test. I also added the exact version of the library that motivated the filtering for convince. Don't be afraid of long commit messages, test names, or varibale names.
- stefan_ 8y agoThere are some tools that basically don't support this. GitLab is the biggest offender: 1) default view is all commits in a MR squashed together 2) messages beyond the title hidden under a click on some micro expand icon 3) going through a MR commit by commit means clicking on an individual commit, waiting for the damn thing to load it's view for 10 seconds, then when you're done you have to go backwards and do it all again
- dcosson 8y agoWe use the same settings in Github of squashing PR commits. I guess it's a matter of preference but IMO this workflow is a better version of what the article describes. You get the best of both worlds, you end up with a very readable history of commit messages, where each one describes a single feature or unit. But while you're working you don't have to break your flow to write documentation every time you commit, or go back later to rearrange/rebase commits.
- chvid 8y agoOne of the many horrible things about git is that it barks at an empty commit message. Of all the documentation that whatever you are working is lacking; you want to have people writing commit messages. Seriously; no-one reads this stream of incoherent babble. If you want more documentation start somewhere else, somewhere where your documentation effort actually would be useful.
- majikandy 8y agoI can’t believe this has been greyed out. Absolutely well said. Self documenting code all the way, what a ridiculous place to hide documentation.
- chvid 8y agoOf course I was joking. All IT-projects need more documentation. And all tools should enforce that. Git should require a readme.md file all repositories and that file should not allowed to be empty. Java should require javadocs for all methods, fields and classes. Should not compile if missing or empty. And so on ...
- deleted 8y ago[deleted]
- pasxizeis 8y agoRelevant: https://github.com/agis/git-style-guide https://github.com/agis/git-style-guide
- chatmasta 8y agoI'm disappointed that the mods changed the title from "Write good commit message" (which is the actual title of the article) to "Write good commit messages," because I think this was an intentional, subtle joke by the author to make the title resemble a commit message.
- jordigh 8y agoOne thing I always want to tell people about commit messages: There’s no length limit. In fact, write as much as you can. Go crazy. Write some more. Explain. Talk about how your day went. Tell us how you found the problem. Put benchmarks that show why your change makes things faster. Show the stack trace or test output that you’re fixing. Quote other people. Put an email chain in the commit message. In a well-curated commit history, commit messages become source-level documentation available via an annotate/blame operation. Most people hate writing documentation, but commit messages are about the only time when our tools force us to write something. Take this opportunity to really write something. It’s the only time when writing is really required in any way. There’s no need for a length limit because most of the time the commit messages are hidden away, and most interfaces will hide the full commit message anyway (or can easily be configured to do so). If you want practice jamming lots of information into a small amount of space, that’s what the first line of the commit message is, but after that, don’t feel constrained by length limits. These are examples of my favourite kind of commits: https://www.mercurial-scm.org/repo/hg/rev/4fb2bb61597c?style=gitweb https://www.mercurial-scm.org/repo/hg/rev/4fb2bb61597c?style... https://www.mercurial-scm.org/repo/hg/rev/ed5b25874d99 https://www.mercurial-scm.org/repo/hg/rev/ed5b25874d99 https://www.mercurial-scm.org/repo/hg/rev/1423ff45c322 https://www.mercurial-scm.org/repo/hg/rev/1423ff45c322 https://www.mercurial-scm.org/repo/hg/rev/dd028bca9221 https://www.mercurial-scm.org/repo/hg/rev/dd028bca9221 https://www.mercurial-scm.org/repo/hg/rev/8d5584d8345b https://www.mercurial-scm.org/repo/hg/rev/8d5584d8345b
- robocat 8y agoFrom your first link: I think that comment should be placed as a source code comment near the source code: "preferedchunksize = 32768". I think magic numbers should be described at the point they are defined, or at least put a link (in a source code comment) to why the music number was chosen....
- jordigh 8y agoThat would be a lot of clutter. When you're on a codebase where people bother writing commit messages, reaching for blame/annotate output becomes second nature and reveals so much about your code. It's just as good if not better than comments, because every line in your source now has a comment.
- gcoda 8y ago"if applied, this commit will" Works like code comments, and i feel how it helps daily when using gitlens vscode plugin.
- 0xdeadbeefbabe 8y agoQuit overloading the word good.
- iliaznk 8y agoThere's this advice I read in a similar article that, I think, makes a lot of sense and is ignored in 99 cases out of 100 – put a period in the end of a commit message so a reader can clearly see that nothing is broken or corrupted and what they see is the entire message in its full. Each of the few times I would mention this requirement on a project people would look at me like I'm a retarded child and keep not using the period.
- seymour333 8y agoI always appreciate commit messages that are informative and well structured. That said, I'm not a fan of specific formats for commits. The commit messages in a project are where a lot of that project's collective "personality" is stored. If you look through the commits for a project with a "colorful" variety of messages, you'll get a sense not only of the work that was done, but of the people who helped create the project. Somewhat related: @git_commit_m on twitter has some great (and amusing!) examples of what not to use for commit messages, which are pulled from github's public data set.
- kazinator 8y agoWrite commit messages in the GNU ChangeLog format. E.g. http://www.kylheku.com/cgit/txr/commit/?id=bfc527af1af619742163d238eac9f2b24f363b0d http://www.kylheku.com/cgit/txr/commit/?id=bfc527af1af619742...
- chatmasta 8y agoI'm obsessed with writing good commit messages, for a few reasons. (1) Documentation is important, and comes in a few major forms: docs, code comments, commits, and tests. Docs and code comments are good for initial, high level understanding. Most "bad" documentation appears in the form of code comments and external docs, because they are most likely to drift out of date with the code. Tests do not have this problem (assuming they all pass) because they are in sync with the code, and provide a nice way to understand interfaces and implementations (the "what"). Similarly, commit messages, by their very nature, cannot drift out of date with the code, and provide an opportunity to document the "why". Therefore, commit messages are at least as important as tests, comments, and docs and should be treated with the same respect. (2) Often the "why" of a particular implementation touches multiple files around the codebase; in many cases you want to document the "why" in comments, but that only helps when it applies to a single section of code. A commit message is an opportunity to document the "why" of an implementation that touches multiple parts of a codebase. (3) Writing good commit messages forces you to keep the code contents of a commit tightly related to its message, lest the message be inaccurate. (4) Because good commits are groups of closely related files, you can understand the subtle interactions of a codebase by looking at which files change in the same commit. (5) A good commit log tells a story and can often provide reasoning behind what may seem like the madness of a legacy codebase. If you don't understand why a file does what it does, just search the history for all commits to that file and you will have a much better idea. There is a cool tool called Gource [0] which visualizes commits to a git repo in a way that can tell such a "story." Some of the rules I follow: (A) A short message with an imperative mood documents the "what". A longer body, in list form, documents the "why" and/or the "how." Always include the body unless its a tiny commit with an obvious why/how. (B) A pull request should follow the same idea as commits, in that it documents the how/why. It should also document the "how" of using any new features it introduces. If possible, it should include screenshots/videos/links of the changes so QA engineers / managers can quickly read it for high level expectations of the next release. Other commenters in this thread have mentioned that pull requests are where the documenting should happen. But good pull requests are just as important as good commit messages; they are not mutually exclusive. A pull request is just a higher level commit. (C) Before submitting a pull request, use `git rebase -i` against the development/master branch to squash, reorder and fixup commits. For example, sometimes one commit is "solve problem A using method X," but you change your mind in a subsequent commit "actually, solve problem A using method Y". In that case, the two commits should be squashed together if they are in the same pull request. In general, do not be afraid to aggressively reorder and regroup commits in a pull request, if it improves clarity of the pull request as a whole. For this, I like to use a tool called rebase-editor [1] that makes interactive rebasing easy and satisfying. [0] https://gource.io/ https://gource.io/ [1] https://github.com/sjurba/rebase-editor https://github.com/sjurba/rebase-editor
- kureikain 8y agoThe key to write a good commit message is to write it for others, not for you. Many time I see commit message is written for the author itself who has all the context around it. The Go programming language has very good commit messages
- dzolvd 8y agotl;dr: git gud
- ncmncm 8y agoImperative is certainly correct. However, the examples fail by emphasizing what was changed, rather than why it was changed. Sometimes those are the same, and that's ok. But when they're not, why is overwhelmingly more important. What can be seen from looking at the diff. These days, why is most usefully a PR number, and your workflow automation turns it into a URL you can click. I.e., why did you make a change not motivated by a PR?