24 ms·
Commit messages guide
- callmekatootie 8y agoThe best advice that I got came from CodeSchool's github course (this was about 5 years back so I am not sure if they have updated it). It said that the commit message should indicate what will happen if that commit is applied by another user, not what changes have been carried out. It's worked well for me so far.
- indentit 8y agoI personally don't like hard wrapping the body of a commit message because it then looks terrible every where - GitHub website, git client etc. and it becomes much harder to read
- jklm 8y agoThat’s interesting, IIRC short lines are supposed to increase readability because longer ones are harder to mentally wrap.
- ceejayoz 8y agoSure, but there’s no reason that has to be done manually. Leave it to the client.
- yawaramin 8y agoMost clients don't wrap in a way that helps readability, though. Look at Hacker News comments for example. At 1:1 zoom the text is spread out across the screen in super-wide lines that are hard to read. The classic recommended 72-char hard wrap guarantees a good reading experience on all but the narrowest of screens.
- Reelin 8y agoI often browser HN in a half width window for this exact reason. To be clear, I don't fault HN for this; I can trivially resize my window to whatever works best for me. Commit messages are different because people often interact with them via command line based tooling.
- u801e 8y agoWhat about parts of the commit messsage that shouldn't be wrapped and having them wrapped hurts readability? If you rely on soft-wrapped, then there's no way to prevent that from happening.
- red_dinosaur 8y agoThe repository does not follow its own guidelines. Also, there's a lot of unnecessary stuff in there. Capitalization and imperative? Not at the top of my list. The relevant points are nicely summarized by Linus Torvalds: https://github.com/torvalds/subsurface-for-dirk/blob/a48494d2fbed58c751e9b7e8fbff88582f9b2d02/README#L88 https://github.com/torvalds/subsurface-for-dirk/blob/a48494d...
- js2 8y agoOr look to git's repo itself for examples: https://github.com/git/git/commits/master https://github.com/git/git/commits/master
- dcbadacd 8y agoI heavily dislike the hard wrap requirement. Why do that if our clients could do it nicely, based on screen size, preference and everything?
- andreareina 8y agoMaximum flexibility with minimum complexity. You want lines that wrap because humans are going to read the message. But you need to be able to not wrap when needed, e.g. when posting code snippets. You need something that any client (including email clients written 10 years before git was a thing) is going to recognize and know how to display correctly. Hard-wrapped plain text fits the bill.
- cjonas 8y agoWhy would you need to support a commit message in a 10 year old client? This is like saying you need to support IE8 in a web app. If the person doesn't like things being broken, then maybe they should update there software...
- buster 8y agoThe ability to display commit messages nicely probably is not the metric by which people chose their email client. Wrapping text where it makes sense is also a task which is best done by the human writing it. I'd rather have a meaningful text flow with sense than some machine hard wrapping in the mi dle of the sentence.
- deleted 8y ago[deleted]
- interfixus 8y agoThis is strictly my own idiosyncrasy, I know, but it has stubbornly refused my many attempts to change it over the years: I cannot get used to the imperative. Do this or do that always signals some pending issue, something yet having to be done. Whereas a message saying did this or did that tells me exactly what I need to know, namely what the commit was about in the first place. But then, my linguistic instincts are probably all slightly off: I have so far never gotten used to pull request not meaning 'kindly asking permission to download some code from your repo'. I really feel Linus should have consulted me on that one.
- daniel-cussen 8y agoI find Scandinavians are much better English speakers than they give themselves credit for (they are sometimes deeply apologetic about immaculate English). Idioms, however, are the hardest part about any language and in English they are hard to nail without painstaking dedication to that language, to the exclusion of native speech in other languages. And that's how you get idioms like pull request, or Ace of Base "All that she wants / is another baby". The latter is supposed to mean "another lover" but it conveys "another pregnancy".
- interfixus 8y agoLinus and I are equally Scandinavian, so please let me take this and run with it: The one brief, shining splitsecond of my life where I may actually have perceived something clearer than he did. You are right, of course. Idioms are eminently slip-upable, especially - I would guess - for someone coming from a closely related language with many fixed expressions beguilingly close, just not quite as close as they may sound on first hearing.
- k3nt0456 8y agoThe simple rule is to pretend all commits start with "once committed, this change will ..." Or more simply, "this will ..."
- Joky 8y agoPast-tense is about the what the programmer did to get to the patch, present (imperative...) tense to me is describing in the absolute what is a diff is doing (it describes the act of `git am` this patch). While the past tense makes sense from the author point of view describing what just happened until they typed `git commit`, I'm in the "present" camp since I find it more relevant to me when reading `git show <rev>`: it tells me what the commit is doing at this particular point in history. I don't really care about the programmer/author centric point of view at the time the message was written.
- areyouseriousxx 8y agoThis is one of those interesting bits where things feel more like personality types as opposed to ways to create maintainable software. I have yet to see a project fail because commit messages were or were not in imperative form or if the first letter was capitalized. I have no problem doing it if someone in the team finds it important, and I have no issue if someone on the team does not do it. The same is generally true about rebasing etc. Due to the high visibility of commit messages, a lot of details certainly look pretty bike shed-ish. What can be important is simply a general concept of meaningful messages when they make sense. For example, bug fixes that may not be obvious by looking at the code, should probably have a reasonably detailed description of the bug. Commits implementing a brand new feature and involving a ton of changes, probably don't need a whole lot more than what the feature is and what is the expected behavior. Possibly some info about potential future bugs that could happen. When updating the readme, "Updating documentation" is just fine plenty of times. Otherwise, probably just make sure you include some important keywords to make it easier for people to git-grep and I think most projects will be just fine. There ar certain personality types that really enjoy organization and rules. And the feeling of security that comes from having a well defined set of procedures everyone must follow. It really isn't about making software more maintainable based on any existing research we have about how maintainable software is. But if it benefits some of my coworkers mental health by following those rules, it really doesn't take me any additional effort to follow those rules so I have no problem doing it.
- deleted 8y ago[deleted]
- rabidrat 8y agoThis is the start of a Strunk&White-level style guide. There are reasons for things beyond what the OP goes into; for example, the imperative form in English is also the infinitive, which is the most basic form of the word and the one that someone ESL would know or could easily recognize and look up ("caught exception" vs "catch exception"). This is consistent with wording your bug report titles the same way. I played around with several different tenses and styles for awhile and eventually came to nearly the same conclusions as the OP. If another style has genuine merit, then by all means, do what feels right. But if you've never given it a thought, just do these basic things. Use `git add -p` (to make atomic commits) and spend a few seconds crafting each your commit messages to conform to this standard style. In the long run having a standard style guide actually makes things easier for you as a committer.
- woile 8y agoI prefer conventional commits, I have created a tool that prompts some info to make it easier to remember, I can also bump automatically the version using the commits. I've been using it with friends with no issues. I really like how the commit log looks https://github.com/Woile/commitizen https://github.com/Woile/commitizen
- jeena 8y agoYour commit messages don't explain why stuff is happening. That might be ok for a private git repo, but once you have different teams working on it over several years it's not good enough.
- c3534l 8y agoWhat do you mean? Feat, fix, etc. Those are all short, instantly understandable explanations of why a change was made. If you're looking for an explanation for why the code itself was coded a certain way, that's not what git messages are for. That's what comments are for. You're explaining why you made the commit, not why you wrote the code the way you did.
- intertextuality 8y ago"refactor: changed stdout statements" is a useless commit message. I should not have to manually open the commit to find out what was actually changed. The message should specify changed X to a. If it's too long, that's what the git commit description is for. The keywords are also redundant. I don't need to see doc) if the rest of the commit message reads "update README". That's obviously documentation. "style: black to files" ??? all that was changed was styling here with newlines and quotes. [0] --- To be frank, it's not that hard to write a good commit message. It just requires you to use your brain for more than .2 seconds to write a good, concise summary. Forcing yourself to do this also in turn makes you write better (concise, focused) commits instead of just shutting off your brain and following some tool. [0]: https://github.com/Woile/commitizen/commit/9cecb9224aa7fa68d4afeac37eba2a25770ef251 https://github.com/Woile/commitizen/commit/9cecb9224aa7fa68d...
- sirsuki 8y agoLook, the simple matter is that commit messages are designed from the bottom up to be a medium of prose in the same way email is. I would venture to guess that an email written with good grammar, capitalizes subject (that is less then 50 characters), and a articulated thoughts would ecstatically welcomed compared to the drivel we normally recieve. Commit messages are no different. If one feels that a one liner is sufficient to establish context because the code is so impeccable then that is nothing short of arrogance. Think of commits like little emails. They have a subject that should fit in a subject cell of a table. They have a body. And they have attachments (the diffs). Why wrap lines? Because it is text. If you feel every client ever created handles wrapping appropriately then I’d ask to move the rock you’ve been under. For 30 years I’ve watched client after client screw up text wrapping. Heck, just sample a few government websites. By claiming commit messages are text you are taking back control of the crazy cesspool that is the modern app era and crafting a prose and typesetting fit for your own high standards. As Steve Jobs once quoted: “Be a yard stick of quality. Some people aren't used to an environment where excellence is expected.“
- u801e 8y ago> Think of commits like little emails. They have a subject that should fit in a subject cell of a table. They have a body. And they have attachments (the diffs). In fact, git has a command[1] to convert your commits to email messages. [1] https://git-scm.com/docs/git-format-patch https://git-scm.com/docs/git-format-patch
- city41 8y agoI think the most important thing is to create atomic commits. Each commit should do one thing and do it cleanly. In other words, if you later regret the change, you should only have to revert one commit to remove it. If when reverting you need to go back and reapply part of the commit (due to it being unrelated), that's the sign of a bad commit. I've worked with people who were adamant white space and formatting changes should always be in their own commit. But in my experience, it's never been a problem.
- peterwwillis 8y agoThis is subjective. Sometimes your change has to touch other things in small ways, that other code then depends on over time. Even if your project tries to avoid this, it'll happen to any big or old enough code base. I think your suggestion is most useful for making code review easier. It's annoying to read 5 commits to understand a change versus just one.
- city41 8y agoThat's a fair point. Thinking more on it, you're right it is more about making reviewing old commits easier.
- wst_ 8y agoIf your change must touch too many other things that may be a sign of tight coupling. Not a good sign. Maybe it would be good to think about splitting things apart as a separate lib, or service. Then you'd be able to make small, safe, changes that are atomic.
- int_19h 8y agoDecoupling is not free (especially long term, because it creates a new boundary), and when you decouple without any particular reason to do so, you often end up with more complicated code to do the same thing.
- Negitivefrags 8y agoWhen you are trying to merge a commit to a branch, and it wont merge cleanly because of some trivial white space change someone made in an unrelated commit, you will understand why people dislike it. It's a pain in the ass. At least if the whitespace / formatting changes are in their own commit, then you can just merge that one first and continue on with your day, rather than having to manually resolve the merge problem potentially leading to more merging problems down the road.
- deleted 8y ago[deleted]
- kadendogthing 8y agoWhy is this being submitted on HN?
- pinjasaur 8y agoI find commits very relevant when grokking unfamiliar codebases. The history and changes (plus, how they're documented) are half the battle for me in that context. The article mentions the use of line-length and commit-templates. Personally, I have my .vimrc [0] configured to handle columns for commits (50 for the title & 72 for the body). Then, in my .gitconfig [1] I set a template [2] to be used for all commits. It's a relatively minimal addition, but it's improved my CLI experience with Git immensely. [0]: https://github.com/Pinjasaur/dotfiles/blob/89ca76eaaef24165e877e51ddd524f79e16f3ca1/.vimrc#L89-L99 https://github.com/Pinjasaur/dotfiles/blob/89ca76eaaef24165e... [1]: https://github.com/Pinjasaur/dotfiles/blob/89ca76eaaef24165e877e51ddd524f79e16f3ca1/.gitconfig#L71 https://github.com/Pinjasaur/dotfiles/blob/89ca76eaaef24165e... [2]: https://github.com/Pinjasaur/dotfiles/blob/89ca76eaaef24165e877e51ddd524f79e16f3ca1/.gitmessage https://github.com/Pinjasaur/dotfiles/blob/89ca76eaaef24165e... Edit: fix link formatting
- Gibbon1 8y agoYes! Someone unfamiliar[1] with the code-base should be able to make basic sense of what was done and why. [1] Like my boss tomorrow. Or me in 6 months.
- fuck-right-off 8y agoHa ha! Fuck you! Fuck your commit messages. What a load of fucking bullshit. How to be a good citizen. How to pay your taxes. How to hold your cake fork and soup spoon properly at high tea. How to properly tie a neck tie. How to be punctual. How to be a good speller. How to have good penmanship. Yeah, gee. Thanks. I'll get right on that.
- aizatto 8y agoI have my own notes here: https://www.aizatto.com/engineering-code/commit-messages https://www.aizatto.com/engineering-code/commit-messages I think what I really like Angular's Commit Message Guidelines that suggest you include a "type" (build, docs, feature, fix, refactor) prefix into the commit message to help organize at a quick glance what the commit does. https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit https://github.com/angular/angular/blob/master/CONTRIBUTING.... Here are some other resources Erlang https://github.com/erlang/otp/wiki/Writing-good-commit-messages https://github.com/erlang/otp/wiki/Writing-good-commit-messa... Gerrit https://www.mediawiki.org/wiki/Gerrit/Commit_message_guidelines https://www.mediawiki.org/wiki/Gerrit/Commit_message_guideli...
- regularfry 8y agoI can see the value in gerrit's suggestion of including the component name in the header. I'm not sure I see the value in adding the commit type. Where do you see it as useful?
- wirrbel 8y agoI don't know how people are programming. I have good unit tests and regression tests and even though I commit frequently, most of the time I don't end up with single purpose commits and usually when I trace back commit history these single purpose commits don't help me much, even if the team mates were writing commit messages like these. How much time do people spend to put too changes they did almost at once to make the code compile or the tests pass into two commits? Much more valuable are larger commits at the size of a small PR.
- MrBuddyCasino 8y agoI don’t understand why the history of the code matters so much to some people. Give me well designed and commented (!) code, with tests, designed to be understood by humans. Thats a bar few code bases clear, if I need to look at the git history its a sign the code is crap and I have to use all the information that I can get, with history being my least favorite because it has shitty UX (discoverability, navigation).
- schroffl 8y agoHaving properly separated and single-purpose commits is awesome when running `git bisect` [1] — especially with automatic tests. As well when you revert said commits after the offender is found. [1]: https://git-scm.com/docs/git-bisect https://git-scm.com/docs/git-bisect
- 8y ago
- chipotle_coyote 8y agoWhile I've naturally gravitated toward the "capitalize and use the imperative," I've never been down with the "good commit messages are 50 characters or less" mantra. Why 50? Is there an important tool that breaks if my commit message is 55, 60 or even (gasp) 70 characters? Is there a real case to be made that "Add total vocab entries per capsule limitation" is a good commit message that becomes an utter irresponsible trash fire if one spells the entire word "vocabulary?" Yes, short, clear commit messages are good. I'm not saying "write a paragraph"; I'm not even saying that it's bad to have an arbitrary maximum length beyond which a commit message can be considered poor form. It's just that 50 is a weirdly arbitrary choice.
- regularfry 8y agoThe commit header becomes the email "Subject:" line. 50 characters is less than 72, and allows for the inevitable "Re: Fwd: [Re:] Re:..." mess of email threads, without losing context.
- Joeboy 8y agoIs that the reason? So if your commits aren't getting emailed anywhere, you can ignore this rule (within reason)? I would think only a small minority of git projects have email notifications enabled.
- jstimpfle 8y agoSeveral ways to display the history, like "git log --oneline", or versions thereof that include the author and date, do profit from short head lines.
- jlg23 8y agoBut "For long commit messages, give a summary in up to 50 characters first" solves that as well. There are good reasons to use longer commit messages: * Link to issue in tracker (Projects can liver longer than the use of a single tracking software or use multiple in parallel - e.g.: public and private ones). * Important changes in behaviour might warrant a deep link into the relevant docs, even though they are part of the commit. * Justification why something was changed can be lengthy, especially in a loaded environment (crunch time, intra- or inter-team politics). I am aware that various workflows exist, supported by various tools, that at least partially solve the problems I mentioned. But the larger the number of people involved or the longer the history of a project, the harder it tends to be to agree on a complete chain of tools just for the sake of keeping commit messages short.
- perlwle 8y agoI have been recommending this article to my teammates: http://chris.beams.io/posts/git-commit/ http://chris.beams.io/posts/git-commit/
- swalladge 8y agoAgreed. This is by far the best guidelines for git commit messages I'v found.
- anonytrary 8y agoAuthor suggests using imperative form commit messages ("add X") as opposed to past tense ("added X"). Past tense should be avoided, but using imperative form sounds unnatural and incomplete. I prefer present tense. Just follow this template and you'll be fine: Q: What does the commit do? A: The commit <commit>. Example: Q: What does the commit do? A: The commit adds extra padding to the header. In this example, "adds extra padding to the header" is your commit message.
- intertextuality 8y agoBoth are natural, but imperative is simply more commonly used. When applied, this commit will <refactor abc controller>. This commit <refactors abc controller>. I personally prefer imperative because when you look at a commit it hasn't necessarily been applied yet. But it's like arguing about the difference of potato and potato. As long as you're consistent (and write good messages in whatever style) it doesn't really matter.
- sbmthakur 8y agoI read the following tutorial on the topic few years ago and it has really helped me with commit messages: https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/
- 1wd 8y agoThis guide is strange. The order of rules is in no relation to their importance: Imperative, Capitalize, Self-contained, Explain, Avoid "stuff", Length limit, Consistency. That's like a health guide listing: Circumcision, Limit coffee, Exercise, Vitamins, Avoid "Russian roulette", Vaccination, Brush teeth.
- z3t4 8y agoWhen I look at commit messages its to know why the and who the . Note. Its still OK to leave comments.
- tigershark 8y agoI don’t think that this guide is focusing on the important stuff. It’s advocating really minor things like the capitalisation of the first letter and the use of the imperative form while it completely ignores the most important rule for a commit message: Add the Jira id (or whatever issue tracker you are using) in the commit message. In this way when doing a blame on a file it’s immediately clear why something has been done in that way, with a in-depth explanation of the use case just one mouse click away in the issue tracker system. For me this is much more important than capitalising the first letter of the commit since it provides an immediate and durable value.
- swalladge 8y ago> most important rule for a commit message: Add the Jira id (or whatever issue tracker you are using) in the commit message. I think it's worth noting that the actual text in a commit message stays with the repository. The contents of an issue referenced by the id does not. This is something to be considered especially if this is for an open source project or otherwise somewhere where the git repository itself is more important/central than the issue tracker platform.
- tigershark 8y agoObviously it’s a possibility, but in my experience, in the several jobs that I had in my life I experienced 1 or 2 source control migration in pretty much each of the places that I have been, and a grand total of ZERO issue tracker software change between all of them. It’s obviously anecdotal but pretty much everyone is migrating to git, changing issue tracker is something that you experience much less. And even if it happens a proper migration would preserve the ids, so nothing is lost if it’s done correctly.
- avodonosov 8y agoSubversion recommened commit messages to be single line, without breaks. The argument was that it's good for scripting, the one record = one line approach usual for unix scripts. I have this habit since then and format all my git commits that way, despite the multi-line tradition in git. Was Subversion wrong?
- vojta_letal 8y agoI do not like the idea of giving anyone access to my email account. I'd rather see a desktop version of an inbox-clone.
- melansoncholia 8y agoPssst... https://news.ycombinator.com/item?id=19705440 https://news.ycombinator.com/item?id=19705440
- darth_mastah 8y agoWhat's wrong with Angular commit message guidelines? https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines https://github.com/angular/angular/blob/master/CONTRIBUTING....
- tomxor 8y agoNothing - in the context of angular project, which this is not. They are not general enough, everything isn't angular. But if you want to compare, I also dislike how they choose to expand the line width to arbitrarily accommodate certain git web uis but shun minimum terminal widths.
- marcinzm 8y agoShouldn't your terminal view be able to wrap the text itself before showing it to you? That seems a UI display issue rather than one to solve by changing the underlying data representation. I understand why that's not good with code but commits are almost always non-code.
- tomxor 8y agoYou know what, that's a fair point, but it's also just not how it works... The reason for the 72 rule is that minimum terminal columns (since the beginning of time) is 80. git-log will pad the message with a 4 space margin, so to keep it centred you want it to be 72... alternatively to keep it from sprawling to illegible lengths you want to hard wrap it at about that width anyway. So you will find one of 2 undesirable things happen if you don't hard wrap to this length: 1. Your terminal or pager _will_ wrap the text, but knows nothing of the formatting, so it will wrap onto the next lines without indentation (this does reduce legibility, making it harder to see where one commit ends and another begins in the full log). 2. Your terminal or pager _wont_ wrap, in which case have fun scrolling to the right - a lot. You could rightly argue that if the terminal + cli + pager and git were one monolithic UI, then it would have a more holistic view of whats going on and smarter decisions could be made - but then we lose all the benefits of those separations (the unix way). There is no win win, but it is at least pretty trivial to hard wrap text automatically in your editor.
- oml3t3 8y agoI'm sorry, but this is a load of self congratulatory, pseudo software engineering masturbation. > "Why are commit messages important?" They aren't. It's metadata. They serve as contextual checkpoints for the author of the changeset, and nothing but. > "To speed up and streamline code reviews" Comments and Pull Request descriptions aren't enough here? > "To help in the understanding of a change" See previous point. > "To explain "the whys" that cannot be described only with code" Aka. "Comments" (both code-based as well as tooling based in systems such as Azure DevOps/Crucible/Github/Bitbucket) > "To help future maintainers figure out why and how changes were made, making troubleshooting and debugging easier" "Why" should be covered by the previous points, OP just keeps repeating themselves here. As for the "how the changes were made" - the code itself is the "how".
- fideloper 8y agoThe value of git is the tooling around pushing code to a central place. Version control is a relatively minor (albeit occasionally very helpful) part of the value of git. I’d argue that central storage (somewhat ironically), open source support, CI automations (esp. web hooks), issue management, etc offer far more value. In other words, GitHub (and friends) are the value worth spending time in, rather than being in the weeds of using Git “perfectly”.
- kabdib 8y agoGahhh. Ignore most of that stuff about language, it doesn't add much value. Just use common sense: Be clear, be informative, don't waste people's time. You're not writing deathless prose or trying to craft the Greatest Commit Comment of All Time. The Grammar Police are not going to break down your door with their milspec copies of Strunk and White and put you up on charges. One thing I try to do is be a little entertaining. Just little things, a twist of a phrase or something that might cause a commit to stick in someone's head for a while. I've had comments like "Best commit logs of the project," so at least people were looking forward to reading them. Which, if you are scientific and dry and oh-so-grammarly-correct, they won't be. I've had people mention some source-code comments I'd made a decade or two earlier (e.g., in public headers). That was fun.
- bloak 8y agoI think the form being used is "infinitive" rather than "imperative". The forms are identical in English, so it's hard to be sure, but in other European languages it would be the infinitive, I think, so I would guess that it's the infinitive in English, too. Also, it just doesn't seem like a command to me. The document is translated into two other European languages, but the examples are still in English, which is a shame. A translator who is keen to go the extra mile would provide the examples in English and the target language, in my opinion.