14 ms·

How to write a Git commit message (2014)

268 points by baristaGeek 4y ago

carlosdp 4y ago
I prefer Github's method of "git commit messages don't matter, pull requests do". Nowadays, you can easily enforce that the ultimate commit log looks rather nice by doing this: 1. Make it so the only merge strategy allowed on a repo is "Squash and Merge", so each PR = 1 commit in main branch 2. Have engineers care about the pull request quality rather than commit messages It's easier to be more expressive in a pull request, and intermediate changes while working on a PR aren't super interesting to me.
- elpakal 4y ago
  If you really want just one commit on your PR you can reset your branch to its target before you merge: git reset --soft <target> Which will undo all commits and leave all modified files in the staging area. Then you can make one commit and force push it to replace your branch @ remote.
  - fbormann 4y ago
    Thanks for the tip, man! Really helpful indeed.
  - bern4444 4y ago
    You could also rebase and squash all commits into a single one and then rewrite the commit message with git commit --amend.
  - xorcist 4y ago
    Or just git rebase -i like normal people.
    - 1ark 4y ago
      Not sure why downvoted, this is the "correct" way. Can also do --autosquash etc. at the same time.
      - elpakal 4y ago
        what makes this more correct than the other way? if anything an interactive rebase requires a lot more ceremony
        xorcist 4y ago
        Throwing away the commit and doing it again can easily go wrong. It is easy to commit unintended changes by mistake. The interactive rebase is a completely normal operation and intended for exactly this situation. It is also much easier to craft more than one commit, and last minute fixes of spelling errors and such things.
  - ninkendo 4y ago
    Careful here… if <target> is not in the ancestry of HEAD, resetting to it may have the effect of undoing any changes that have happened on the <target> branch that aren’t in yours. To be safe, you can do: git reset $(git merge-base <target> HEAD) Which puts HEAD at the last commit in common between your branch and <target>… which, if target is already a parent/ancestor of your commit, is the same thing. But if target has had changed since you branched from it, this prevents you from undoing any recent commits.
- mwt 4y ago
  This works well enough if (and only if) your company has a culture of small, atomic PRs.
  - munk-a 4y ago
    Not really, I recently merged in a two commit branch where one commit was me changing all the vendor configuration for the framework we were using to a new version and the other was all the changes needed to support the change. That PR affected thousands of files in total but the need to frequently rebase the branch to avoid killer merge conflicts encouraged a low commit count. rebase -i can be your friend if you've got a long branch history that adds essentially no value (i.e. "Tried this thing/Didn't work reverting/Tried this other thing/Still no dice/Switching workstations"). An arbitrarily large number of file changes can be packed into a single commit, sometimes for review purposes it makes sense to purposefully isolate different groups of changes in a manner that doesn't mesh with how the dev work was actually done - sometimes I just don't want to have an ugly commit history. I'm allowed to be OCD about my work and sweep the commit where I added print __LINE_NUM__ between each LOC to track down a bug one time that I was too lazy to use gdb under the rug.
    - mwt 4y ago
      Yeah, I mean my comment more as a criticism of universally squash-merging as a policy since, not so much an endorsement of it in general. I run into cases like you describe pretty often, and I doubt I'm alone. Switching to squash-merging has some benefits but it's also brought out a fresh form of hell when too many changes are happening in too many branches at once.
      - munk-a 4y ago
        Oh absolutely - we have a pretty modest sized company and we do tend to "always create merge commit" because it makes some of our deployment tooling easier but otherwise git preferences are left up to the dev and the particulars of the situation.
- eikenberry 4y ago
  But the PRs aren't part of your git repository? IMO a git repository should be self contained and not require a hosted provide to give context. It lets you manage your work with superior local tooling and without a browser running. Basically I take the exact opposite approach where my PRs are always just a short summary of the commit messages and provides a place for me to put the github specific things like the "Fixes #..". But I make sure my commits are a clean artifact of the changeset by themselves (ie. I do any squashing, etc, on them outside of the PR).
  - mwt 4y ago
    GitHub (by default) uses the name of the PR as the merge commit message and also includes the commit message of each commit in the log. Having whitespace-altering "Dummy commit to trigger CI, ugh!" commits in a git history isn't good but it still clutters the `git log` with stock squash+merge GitHub use. I can't speak for everybody, but if GitHub goes down completely and I only had access to my git logs, I'd struggle to recreate ~20% of the information scattered across issues and PRs. This issue is external to merging preferences, but it's definitely not solved by squash-merges and descriptive merge messages.
    - shagie 4y ago
      > Having whitespace-altering "Dummy commit to trigger CI, ugh!" `git commit --allow-empty` may be sufficient for that "there is a new commit" trigger in many cases. If so, that may be preferable to whitespace changes as those clutter up the blame. As an aside, my initial commit on a repo is an empty one so that I can branch from a completely empty repo to do radical rewrites and yet maintain a history relationship with that initial empty commit (which I feel is preferable to an orphan branch and then a merge with unrelated histories ... though those tell slightly different stories in the log).
      - stormbrew 4y ago
        > As an aside, my initial commit on a repo is an empty one so that I can branch from a completely empty repo to do radical rewrites and yet maintain a history relationship with that initial empty commit (which I feel is preferable to an orphan branch and then a merge with unrelated histories ... though those tell slightly different stories in the log). Oh cool, I thought I was literally the only person on the planet to do this lol. I'd do it for branchpoints too except git rebase by default acts very poorly with empty commits in the edited history (deletes them). I wish this was normalized (ie. there was a flag to `git init` to add a commit message for a root commit).
- Everlag 4y ago
  That's such a different approach than I've grown used to, but different platforms encourage different flows. I've been using bitbucket (not the shiny nice new bitbucket) at work for years and its PR search is so abysmally bad that anything in the PR message but not in the commit message may as well not exist once its merged. `git log` is forever, bitbucket search is /dev/null I'm curious what other affordances or lack of affordances encourage what git behavior.
- simonsaysso 4y ago
  For the code review step, sure, commit messages don't really matter unless your team reviews PRs commit-by-commit. How many times do you actually change the default squashed message? If you write a series of garbage commit messages, I don't particularly trust that you'll write a very good squashed message, either. How many times do people skip updating the PR description with new information or features from comments? If your commit messages are good, the auto-squash message will be good and one will have a network dependency on GitHub to figure out what decisions went into that change. In general I agree with your goal of a great commit log: 1 PR = 1 commit in the main branch. But I feel like GitHub is just the wrong tool to use if you want that. I used to use Gerrit, where commit messages _are_ your PR description. Sure, it makes you interact with git in some unfortunate ways, but the tradeoff is enforced commit cleanliness.
  - woojoo666 4y ago
    Everybody I've seen modifies the squash message in a professional setting. After all, that's the one that everybody else will see. Commits on your feature branch don't really matter and the entire branch can be deleted afterwards anyways
- rubyist5eva 4y ago
  this works until you want to leave Github for whatever reason
  - lelandfe 4y ago
    This happens sometimes when private repos change hands. I've worked at places where we've been given zips of git repos – commit messages reference PR and issue #'s from long distant organizations. I've since started policing PRs whose commit messages reference things inside of our GitHub. At least provide a summary of what you're linking, for the worst case future.
  - ericmcer 4y ago
    Why? Wouldnt the commit history contain only the one squashed commit and its legible message?
- js2 4y ago
  There's a few reasons why this is a lossy workflow compared to commits with proper messages that are later merged, not squashed into one. 1. The PR itself becomes a single giant commit. To adequately explain the diff in a single message would require writing an essay instead of a few paragraphs. It is also now hard to tell which part of the PR message is associated with which part of the massive diff. 2. If something breaks, you can't dissect into which part of the diff caused the problem. 3. It's harder to document your work as you go. I may be working on a PR for days or weeks. Commits give me an opportunity to document each part of my change _at the time I make the change_. It's a chance for me to record how and why at the time it's fresh in my head. If I wait to do this until the PR is ready, I likely will have forgotten some bit of context I wanted to record about the commit. 4. It encourages sloppy commits, making a large PR harder to review. Ideally, I should be able to review a large PR by looking through each commit. If your reply to all this is to say you should just submit smaller and more frequent PRs, fine, but then why ever have PRs that consist of more than one commit?
- swalladge 4y ago
  > I prefer Github's method of "git commit messages don't matter, pull requests do". This is a bad idea unless it works well for your specific company workflows and you don't care about the future possibility of changing platforms. Git repos are designed to be self contained, decentralised, and offline-first. If you only care about how things look on github, then the repo will have poor usability outside of github - ie. on your workstation, in your local git tools, on a repo mirror, etc. Git commits can be a powerful tool for understanding code if the messages are useful. They are immediately accessible through local tools and can quickly add context to a block of code without breaking immersion. But that immersion is broken as soon as you hit a commit messages like "Merge pull request #123" or "fix bugs".
- deleted 4y ago
  [deleted]
- jen20 4y ago
  This would be a lot more reasonable if GitHub would provide tools to review the ultimate commit message in the same manner as the commit content.
- Izkata 4y ago
  > 1. Make it so the only merge strategy allowed on a repo is "Squash and Merge", so each PR = 1 commit in main branch Please don't do this. It erases history that's really useful for tracking down the cause of bugs. There's plenty of ways to use git log to filter commits if a pretty history is your goal.
- woojoo666 4y ago
  I agree with this. Oftentimes I am experimenting around (obviously on a separate branch) and use commits as checkpoints. Not every commit is a perfectly polished state. Using separate branches and then squashing when it is ready, gives me the freedom to experiment without constraint, and then clean things up when it is ready
- teeray 4y ago
  I abhor “Squash and Merge”, because I do take time to make good commits. They each pass tests, they have messages, and I rebase fixup commits away. For me, a merge commit is semantically meaningful (it even gives me a place to put who reviewed it in the merge commit message). This probably seems like a whole lot of work for no benefit. However, I can’t tell you he number of times I’ve been on crappy plane wifi, hit `git blame` on some line and been able to comprehend my state of mind making a change years in the past. Git history is a form of communication.
- u801e 4y ago
  > I prefer Github's method of "git commit messages don't matter, pull requests do". By doing that, you lock yourself into relying on Github in order to get the context behind a change rather than looking at the commit messages for a particular branch. That means, you cannot easily get that information just using git on the command line. On the other hand, if you put the context in a series of well formatted commit messages, you can get that context by reading through the commit log, either on the command line, or in Github by clicking on each commit. > 1. Make it so the only merge strategy allowed on a repo is "Squash and Merge", so each PR = 1 commit in main branch This leads to very large commits which cannot easily be reverted once any other commits that update the same files are added to the base branch. Also, in this case, the merge commits are essentially redundant, so why have them? There's nothing that prevents one from amending their commit to reference the PR number and eliminate the merge commit entirely. > It's easier to be more expressive in a pull request, and intermediate changes while working on a PR aren't super interesting to me. It really comes down to how those changes are presented. For example, if the change is one commit that adds a new method, and a second commit that adds calls to that method, that makes the change easier to review. Also, if a bug is found in the method, you can make a revert commit to remove all the calls to the new method, another commit to demonstrate the bug with one or more tests, another commit to fix the bug and update the tests to reflect that the fix works as expected. If the commit was just a single PR commit, and another PR was merged, then one would have to craft a commit to undo the changes pertaining to that bug and then make a new commit in another PR to add the updated implementation. This makes it harder to see what the fix was since you essentially remove the entire feature and then commit a new version of that feature.
- brunellus 4y ago
  The individual commits aren’t interesting until you need them. They should be organized such that they remove the desire to squash them together. Having a well written commit history is in the spirit of the tool and is the more professional approach.
themanmaran 4y ago
For those who write multi paragraph commit bodys, is there a tool you use to format them? Example commit on the React repo [1]. It just seems like a lot to type in the command line. [1] https://github.com/facebook/react/commit/ec52a5698e2dfea7050a0b015f0b79abfb2d81b7 https://github.com/facebook/react/commit/ec52a5698e2dfea7050...
- xorcist 4y ago
  Command line? git normally opens your chosen editor and you are free to write away to your heart's content. I guess you could stuff multiple -m in there and git will format it nicely, but the editor is for writing and is best used for that.
- jrib 4y ago
  My vim will automatically wrap when I am typing a git commit message. Should be set by default from here: https://github.com/vim/vim/blob/2f0936cb9a2eb026acac03e6a8fd0b2a5d97508b/runtime/ftplugin/gitcommit.vim#L13 https://github.com/vim/vim/blob/2f0936cb9a2eb026acac03e6a8fd...
- imron 4y ago
  vi :set tw=70
- a_t48 4y ago
  There's a good chance this was made in Github's squash+merge dialog. Edit: never mind, it's auto wrapped at some number
- knoebber 4y ago
  Emacs + magit and auto-fill-mode
- rubyist5eva 4y ago
  > It just seems like a lot to type in the command line. I spend my entire workday day in Vim.
- teeray 4y ago
  If you don’t supply `-m`, `git` will pop open your `$EDITOR` with the new commit message. You can use whatever tools you like to wrangle text in there. I use vim, so it’s just a quick `gq<motion>` to format everything.
bern4444 4y ago
I like the conventional commit style [0]. You may have seen these in open source repos or used them at work. They look like feat: support new line chart fix: update props for new line chart chore: bump dependency version What's also cool is there are tools (semantic release) that will then handle automatically the versioning and publishing of your module based on these commits using the commit type (feat, fix, chore etc) to determine the next appropriate version [1]. [0]https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ [1]https://github.com/semantic-release/semantic-release https://github.com/semantic-release/semantic-release
- _virtu 4y ago
  I built a full pipeline around this. Basically allowed for a paved road for devs to automatically semantically version and deploy application and module artifacts for npm with semantic release by spinning up a repo with some boilerplate generators I made available to the team. Since then I've been obsessed with the conventional commit format everywhere for my own projects. Even if the commits aren't parsed for versioning, it just gets you into the habit of thinking about the scope of the commits. The laughable part about building that full paved road pipeline is that the biggest friction point was always when devs didn't use semantic commits. At the time when I implemented it I didn't have checks for the commit format at the pr phase. I DID have a commitizen cli option as well but that was "Too much friction". Oh boy did I get bit. As someone who was working on DX I was constantly surprised by how many questions I got about something as seemingly simple as the conventional commit format from a crowd of enginerds.
  - tardismechanic 4y ago
    +1 on conventional commits (big fan) also, +1 on fully paved road approach! You might want to check out this GitHub Action to enforce PR title matches the spec: https://github.com/amannn/action-semantic-pull-request https://github.com/amannn/action-semantic-pull-request
  - irrational 4y ago
    > I was constantly surprised by how many questions I got about something as seemingly simple as the conventional commit format from a crowd of enginerds. I'm not. Writing code and writing git commit messages take entirely different types of thinking. With code you are having to think logically and problem solve to tell the computer what to do. Git messages are more analogous to writing a term paper (though shorter). You have to think about the what you are trying to communicate, how best to describe what this commit is all about, maybe trying to figure out if this counts as a fix or something else, etc. Writing code is fairly easy for me. Writing git commit messages is extremely difficult for me. I sometimes go days without commiting because I'm dreading having to write a commit message.
mwt 4y ago
This is from 2014, but I guess not much has changed since then.
transitivebs 4y ago
95% of the commits on my personal open source projects use emoji commit messages. https://github.com/transitive-bullshit/commit-emoji https://github.com/transitive-bullshit/commit-emoji PRs matter a lot more than commit messages, especially if you're squashing + merging / rebasing.
- sph 4y ago
  But why? That's even more useless than just describing a commit in a couple words. I'd rather see a commit saying "fix bug" when bisecting or reading a commit history than ":heart:"
- slaymaker1907 4y ago
  I've tried with the idea of an autocommit chron job or something which just uses timestamps and periodically rebases things to avoid tons of commits.
- mwt 4y ago
  Honest question, do you really expect your history to be meaningful long-term? Or are you simply taking the approach that the commit message is meaningless and a developer instead use GitHub search to find a PR relevant to a change they're investigating. For example, I pulled up one of your projects and the history (https://github.com/transitive-bullshit/kwote/commits/main https://github.com/transitive-bullshit/kwote/commits/main) is less than meaningless, compared to i.e. using emojis as a shorthand (https://github.com/tiangolo/fastapi/commits/master https://github.com/tiangolo/fastapi/commits/master)
  - Bolkan 4y ago
    What if I want to revert to a previous state / compare current state with a previous state. "starting work on bizon gradiants" is way better than . Edit: apparantly HN blocks emojis. Love this feature.
  - wdroz 4y ago
    Fastapi use gitmoji [0], this is well-documented and structured. [0] -- https://gitmoji.dev/ https://gitmoji.dev/
deleted 4y ago
[deleted]
pvg 4y ago
Previously https://news.ycombinator.com/item?id=13889155 https://news.ycombinator.com/item?id=13889155 2017, 118 comments https://news.ycombinator.com/item?id=10212582 https://news.ycombinator.com/item?id=10212582 2015, 90 comments
ufo 4y ago
I hate that rule about 50 characters. IIRC, it started because someone noticed that the average commit message in the linux kernel is about 50 characters. Then, for whatever reason it morphed into this widely propagated mantra saying that the maximum should be 50 characters.
- slaymaker1907 4y ago
  Writing a good commit message within those constraints is kind of like writing a haiku. It's kind of entertaining sometimes, though I think it should be a suggestion rather than a rule.
  - remram 4y ago
    It's usually fine unless your change concerns a specific function/module whose name is 20+ characters. Often I am renaming a function/module/package and can't fit its name in the first line which I find really annoying. Trying to refer to it in a different way or abbreviating it is so awkward.
- js2 4y ago
  I know the articles calls it a rule, but really it's more a guideline. It's so that `git log --oneline` and `git shortlog` produce succinct output. It's also the email subject when using `git format-patch`. With all of these, the idea is to have a quick-to-read summary of the commit. That's all, really.
- kibwen 4y ago
  Indeed, I follow these rules but I routinely violate the 50 character limit. It's far more important for subject lines to be useful than to be maximally succinct; I'm not out here trying to write an essay in the subject line, but I do need it to be appropriately descriptive.
- mhitza 4y ago
  I think Linus himself recommended at some point that 50 character subject restriction (in a time when 80 character wide code lines were also still a recommendation). That wouldn't be important in itself, but Github trims your message at 50 characters as well. Because of that "feature" alone it's annoying to pass that limit.
tsuujin 4y ago
This has been my commit bible for years. I feel like it has been battle tested and has made my life easier.
cwkoss 4y ago
I saw this article early in my software development career and found it very valuable. Nostalgic and a good reminder. Send this to the still-learning software devs you care about.
rectang 4y ago
I like this post. I know people are offering their alternative conventions which they have various rationales for preferring, but I've followed the conventions this post advocates for years, and they haven't done me wrong. This post describes a widespread standard practice. People never complain about my commit messages and they don't have trouble understanding them.
anshumankmr 4y ago
Though I don’t think I am really the best coder out there, I was taught by a senior to use proper Git Commit messages which I usually follow only. I am however quite frustrated by my team mates who end up re-using the same commit message essentially for bugfixes.
goombacloud 4y ago
I rather prefer the first paragraph to be a problem statement and the second paragraph explain the change in detail. This gives the rationale upfront as the focus and helps to understand the problem and check whether the problem/goal was fully understood when making this change and whether the change actually covers what it should achieve. Overall, the change was/is just a mean to an end and other variations are possible.
imwillofficial 4y ago
A very timely article, I’ve struggled with what to put in a commit message. This gives guard rails to make it easy.
lamontcg 4y ago
I'm a heretic who prefers information in the PR. That's where the long-form back and forth arguments happen over the edge conditions. Periodically a few days after a PR has been merged I'll have a discussion with someone and realize some context was never captured, so I'll just add it at the bottom of the closed+merged PR for posterity. Yeah that means all the important information is in GH but if you migrate to GitLab or bitbucket or whatever they've got tools to pull all that info along with you when you migrate. I don't really care about individuals commits other than to find the gitsha to find the PR that they were merged into in order to find the full context.
- logbiscuitswave 4y ago
  It may be heretical but I tend to agree with this. Also at my workplace we tend to be standardized around PRs doing squash merges so there’s not really much point in having detailed interim commit messages anyway. As long as the PR has good information (and of course is linked to useful work items with good information) that’s usually good enough for me. (Of course more often than not people have empty/useless linked work items, and PRs with useless titles and descriptions but that’s a whole different kind of problem.)
- adastra22 4y ago
  Write a commit script that pulls in the PR text into the merge commit.
  - lamontcg 4y ago
    > Periodically a few days after a PR has been merged I'll have a discussion with someone and realize some context was never captured, so I'll just add it at the bottom of the closed+merged PR for posterity.
- emacs28 4y ago
  I totally agree with this, I'm not a fan of the written-in-stone nature of commit messages. Just like code, it's nice if log history is editable too in case your forgot something, or if you want the message to mention future changes that back reference it.
rafaele 4y ago
What do people think of this line? > Use the imperative mood in the subject line The only rationales I've seen for using imperative ("fix bug") over the indicative ("fixed bug") are that it's what git does by default anyways. Is it really that big of a deal to use the indicative sometimes and imperative other times? For what it's worth, I always write commit messages in the imperative, out of habit. When others write commit messages in the indicative tense, part of me notices, but I move on because I can still understand the message if it adheres to the other guidelines.
- owalt 4y ago
  None of this is really worth obsessing over I think, but one point in favor of imperative is it tends to also be the tersest phrasing, which is convenient if you're also aiming for 50 characters max.
- synicalx 4y ago
  So long as the meaning is clear, it really doesn't matter IMO. Just write it so that when viewed in isolation the meaning of the message is clear and matches the changes held within the commit. Anyone who gets up in arms over "fixed" vs "fix" needs to get a life.
- stinos 4y ago
  I use imperative, but for other projects which don't I switch to indicative if that is the style. Personally like imperative more, not sure why, just preference. > Is it really that big of a deal to use the indicative sometimes and imperative other times? 'big', don't know, but wouldn't be surprised if there's an objectively provable higher cognitive load for having to read a mix of both (or, god forbid, other styles thrown in there as well) vs one consistent style. Just like there is for code etc. And some people are affected by striving for consistency more than others, so for them lack of consisteny might cause some extra friction.
- deleted 4y ago
  [deleted]
- tremon 4y ago
  The imperative mood/future tense ("this commit will...") makes the commit the subject of the message, the past tense makes the developer the subject of the message. In my (limited, personal) experience, the people who insist on past tense commit messages have more trouble killing their darlings, are more likely to take review comments personal, and are more likely to view (part of) the codebase as theirs rather than the team's. So for me, it's not about the commit message itself, but the communication style says something about the developer and how I best approach them. My take on this requirement is that it helps developers let go of their attachment to the code they've written.
stjohnswarts 4y ago
descriptive subject with 50 chars or less skip a line more thorough description if needed. You don't need 7 rules to remember. KISS
twhitmore 4y ago
Interesting topic. From my experience Headline + Bullet Points are far quicker to convey useful information, in a form that is terse yet easy to read. For example: ---------------- improve Buffer Cache Management & logging - change 'tryDrop()' to skip immediately, if lock unavailable - move BufferCache logging to a separate logger - attach BufferTrim.Unsuccessful -> Preemptive Flush of oldest buffers -------------------------------- Having worked in many codebases & internal docs, I've found narrative significantly less efficient to read & write. In commit messages, far too many developers skip almost any detail as to what they're changing & why -- the slowness of narrative formats may substantially contribute to this. In docs (Wiki etc), narrative encourages developers to ramble about minor technical details while omitting all high-level context. Headline + bullet-points bypass a lot of struggles with narrative by allowing a simple headline and then, well, cutting to the point. This also illustrates a informed personal preference -- studies find lowercase English words faster to scan/ comprehend. See: http://literatejava.com/git/how-to-write-a-good-git-commit-message/ http://literatejava.com/git/how-to-write-a-good-git-commit-m...
- stinos 4y ago
  I don't really have a problem with bullet points, conveying relevant information is after all the most important thing the message should do, but if that example is an actual one then it would raise some flags during review. Mainly because it's not super readable (mix of styles, super terse requires extra interpreting) but also because it mostly explains what has changed (most often unneeded information, as that should be clear from the diff) and not really why it is done that way (ok, the code might have comments, but still I expect the message to explain that). In my experience, using bullet points like this is correlated with this style of messages which just list 'I did x, y, and z' whereas a more narrative style, which can still go in bullet points, is correlated with easily digestable messages explaining properly the reasons for changes. Anecdotal of course.
  - u801e 4y ago
    > it mostly explains what has changed (most often unneeded information, as that should be clear from the diff) and not really why it is done that way Ideally, commit messages should at least briefly explain what was changed (e.g., Add feature X, Fix bug Y) in addition to why it was done. When people look at git log output, they won't always show the associated diff for each log message. Also, when running git blame, they'll see the commit id and title, but not the entire change. That doesn't mean that one can't run other commands to see the associated diff, or even getting the overall branch diff from the commit ids recorded in the merge commit, but having that what was done in the commit message allows one get an understanding before looking into it in more detail.
kgeist 4y ago
We also have a rule to prepend every commit message with its issue number in our issue tracker (we don't use GitHub). That way in Git Blame/Log you can always quickly find where the change came from and why - the issue tracker usually has more detailed information.
- hansoolo 4y ago
  Yup, we do the same and it works out pretty well this way.
- toastal 4y ago
  This really treads on the char limit in the titles though
- selcuka 4y ago
  We do the same and it works pretty well. The problem with that approach, though, the codebase may live for decades but issue trackers change and old tickets usually don't get migrated to the new system.
  - kgeist 4y ago
    >old tickets usually don't get migrated to the new system Well, our current issue tracker was migrated from Jira and I can still see all the ancient Jira tickets just fine (I mean what's important: the comments). In any case, something is better than nothing at all.
- atq2119 4y ago
  Curious, I've run into this approach in the past and learned to hate it with passion. That place used JIRA where the typical ticket ID was around 10 characters. That wasted a lot of prime real estate, e.g. in my email inbox, in history views (tig, gitk, and so on). I also don't see the claimed benefit for git blame. In a real code base with significant history, it happens often enough that the first blame is an unrelated refactoring and you need to dig deeper. Therefore, I find that best practice is to look at the blamed commit first instead of the ticket. That gives you the full commit message, which can still contain a reference to an issue. Putting footer lines like "Fixes: <issue>" into commit messages works much better. It's just as easily visible in git log etc. and doesn't waste space.
alexeiz 4y ago
My opinion about Git commit messages has always been the same: if you can't describe it in English, you don't know what you're committing. If your commit message is too long and messy, you're committing unrelated things that should be split into multiple commits. The commit message is a direct indicator of the quality of your commit.
marseysneed 4y ago
Sometimes I wonder about repos that do not follow any guideline. I use an open source service[0] that never describes what the commit is about, so just know that any description of the commit is better than none at all. [0]https://github.com/Aevann1/rDrama/commits/frost https://github.com/Aevann1/rDrama/commits/frost
beermonster 4y ago
Is there a reason why GitHub don’t make it easy in 2022 to write nice commit messages? Larger boxes, visual cues for character length, non default commit messages such as ‘Updated doc blah’ which are useless. Lots at our place solely use the GitHub UI to edit Markdown files mainly and their messages are typically the least useful for that reason.
Sheen96 4y ago
My philosophy tends to be that your first commit should convey the task you are trying to achieve and additional commits beyond that point should be fixups, to be rebased into the single first commit before merging. This removes the back and forth of changing and reverting the same files, changes from PR comments etc. It's much more coherent.
rendall 4y ago
A junior dev turned me onto this several years ago, and I've gone by it ever since. I was skeptical at first. For instance, the given reason for using imperative mode is not strong, in my opinion (the default git message on merge and revert is imperative is not a good reason, because other default git messages do not use the imperative). But, there are other good reasons for using it, not least of which is arbitrary consistency lowers cognitive load. Now, it's my go-to if there isn't a good reason otherwise.
hoseja 4y ago
Manual wrapping for the sake of dumb terminals is such a pet-peeve of mine. Why? It's so awful to read.
onion2k 4y ago
Every time I read something about "how to write good commit messages" it always seems to focus on reading the messages back as a log. That's great if that's how you use commit messages, but I tend to use them more for searching for a specific change so it doesn't really work for me. A more narrative style in commits I might need to go back to makes it easier to find them later. How you write your commit messages should be driven by whatever you use them for afterwards.
- sudo_chmod777 4y ago
  Define 'specific change'. A change driven by a business decision? Don't see how it won't work. A change specific to a component? Try conventional commits with scopes. Code change? You shouldn't use commit messages. Use e.g. `-G`, `-S`, `-L`, etc. instead. By the way if you are not using fzf already, you should.
revskill 4y ago
Mine is "[JIRA_TICKET] Add something" It's simple and worked well for us so far. Less rules, more information, and developers are free to use their words to express intention of changes instead of nonsense (feat, fix,....)
- tremon 4y ago
  Have you gone through a ticketing system change yet with a developer team? I've seen several, and not once was "we must import the old PR's/issues/features into the new system" given any serious consideration. Conversely, every source control system migration I've seen took great pains to preserve the committer, the date and the full commit message of each separate commit. Point being, in a few years all your [external references] will be useless. Can your commit messages explain the commit context on their own?
  - revskill 4y ago
    OK, my question is, no effective commit message system exists without a consistent ticket system. A ticket reference gives you all you need. You see it in every line of code, from there you know the reason for that code to be written, it could include a reference to slack discussion url,...
Traster 4y ago
Honestly, the best guidance is just "put more than 2 seconds effort into your commits". No one really believes "More code" is a good commit message, it's just laziness. So yeah, put a little effort in, it's literally one of the few parts of your work that will remain once you are gone. Most code I've worked on gets replaced/updated/modified after I'm done working on it - but the one thing that I know will stay is the git history that some poor bastard will have to search through to figure out why this random bit of code ended up this way. The only other thing I'll say is don't be weird. I knew a guy who would prepend his commits with a [tag] saying what part of the repo his commit was touching. This was a mixed sw/hw project and every single commit of his started with [sw]. It's like, ok thanks, firstly, you're a software engineer working the ../sw/ folder, secondly no one was confused that your 17 changes to a C++ file were going to be a hardware change.
- mmcnl 4y ago
  I like this. Any advice other than "putting in effort for more than 2 seconds" has a lot of hidden assumptions about the context and organization around your code. Some days I only do a commit once at the end of the day as a backup. Other days I have 10 commits in 1 hour because everytime I thought I was finished I found something else that needed to addressed. In practice, there often is not a very strict process around commits, so specific advice is often not very useful either.
kazinator 4y ago
I will play the devil's advocate: why would anyone outside of the realm of die-hard FOSS on Unix-like systems wrap text to 72 columns? Look, I'm not doing it now. This entire paragraph I'm entering into HN is one giant line of text that gets wrapped. Suppose you're working on software for which patches will not be sent to FOSS mailing lists that are anti-HTML, anti-MIME, anti-long-line, ... why would you wrap the body of commit messages to 72 columns?
- everybodyknows 4y ago
  > Why would anyone outside of the realm of die-hard FOSS on Unix-like systems wrap text to 72 columns? Because if the commit is performance related, including regression test results may be mandatory. Test results will be in some fixed format e.g. tabular, commonly exceed 72 columns, and become gibberish if wrapped.
  - kazinator 4y ago
    If it becomes gibberish when wrapped, why would you do exactly that? If I have 200 column wide regression test results in a nice tabular format, maybe that's the way it should stay in the commit message.
DrBazza 4y ago
I'm sure quite a few commenters on here only started writing code in the last 15 years. What's interesting is that git is (more or less) the de facto version control system and has been for that 15 years, and that likely means that what you put in your commit messages will stay around forever (for some definition of forever). As a greybeard I've gone file-based backups, then SCCS, CVS, SVN, and now git for what seems like forever (git was 2005 according to wikipedia), though probably the late 00s. And migrating from one to the next (yes, quant code from the 90s is still running in 2022, and we have the commit messages to prove it). Some people commenting above/below above the PR being the source of in depth information. As far as PRs are concerned, it's just another issue tracker, and I've been through the lot, also including various git hosting services). The commits travel with the repository. The PR discussions don't.
- epmatsw 4y ago
  100 times this. I’ve worked at a company with a commit history going back to 1979 (literal paper logs at that point, plus in-file headers), and another company where we lost ~2 years worth of historical context/info to WIP commits because “our internal GitHub instance has that info” turned out to not be true when we migrated to a new instance. Nowadays, the relevant info from our PRs gets copied to git, and I hope in 40 years if someone has a question they can still see that history if needed.
ABraidotti 4y ago
I'm a frazzled git babysitter. All I ask is that you start with a verb and keep it in present tense!
planede 4y ago
I think the most important thing is that the commit message should capture the high level intent of the change. I write "intent", because the actual effect and "intent" can differ, and commit messages are immutable. It's fine, as long as you recognize that the commit message is there to capture original intent. You often see "Fix bug #1234", but you rarely see "Introduce bug #1234". The other stuff about using consistent tense, capitalization, punctuation, etc... is important, but secondary.
incomingpain 4y ago
I have only been using git for a few years. subversion was popular for a long time. I rarely pay much attention to git commit messages. I would very much rather look at the diffs and see where/what it changed. >Capitalize the subject line Does this really matter? Really?
- gbear605 4y ago
  It matters to the same degree as being consistent about variable naming. It doesn’t change whether the system works, but if everyone is consistent then it’s easier to read and understand later.
  - incomingpain 4y ago
    > It matters to the same degree as being consistent about variable naming. It doesn’t change whether the system works, but if everyone is consistent then it’s easier to read and understand later. I must admit I don't like that PEP rule. Camel case in some places, no capitals in other places. I just whatever I want really.
zoomablemind 4y ago
In my experience, when possible, the commit messages should read as part of a spec, describing the implemented behavior (mostly imperative). Even when fixing a bug, the commit would state what the code is intended to do, just as its resp. test exercises. This way it's somewhat easier to follow the reasoning of the committed changes. Another detail is to prefix a subsystem affected, that's in case of modular or complex application. Also help focus the attention. My preference in general is to write single line messages (shorter ok, longer - ok too), unless it's something very non-trivial and source-code policy discourages lengthy comments.

268 points by baristaGeek 4y ago

I prefer Github's method of "git commit messages don't matter, pull requests do". Nowadays, you can easily enforce that the ultimate commit log looks rather nice by doing this: 1. Make it so the only merge strategy allowed on a repo is "Squash and Merge", so each PR = 1 commit in main branch 2. Have engineers care about the pull request quality rather than commit messages It's easier to be more expressive in a pull request, and intermediate changes while working on a PR aren't super interesting to me.

elpakal 4y ago
If you really want just one commit on your PR you can reset your branch to its target before you merge: git reset --soft <target> Which will undo all commits and leave all modified files in the staging area. Then you can make one commit and force push it to replace your branch @ remote.
- fbormann 4y ago
  Thanks for the tip, man! Really helpful indeed.
- bern4444 4y ago
  You could also rebase and squash all commits into a single one and then rewrite the commit message with git commit --amend.
- xorcist 4y ago
  Or just git rebase -i like normal people.
  - 1ark 4y ago
    Not sure why downvoted, this is the "correct" way. Can also do --autosquash etc. at the same time.
    - elpakal 4y ago
      what makes this more correct than the other way? if anything an interactive rebase requires a lot more ceremony
      - xorcist 4y ago
        Throwing away the commit and doing it again can easily go wrong. It is easy to commit unintended changes by mistake. The interactive rebase is a completely normal operation and intended for exactly this situation. It is also much easier to craft more than one commit, and last minute fixes of spelling errors and such things.
- ninkendo 4y ago
  Careful here… if <target> is not in the ancestry of HEAD, resetting to it may have the effect of undoing any changes that have happened on the <target> branch that aren’t in yours. To be safe, you can do: git reset $(git merge-base <target> HEAD) Which puts HEAD at the last commit in common between your branch and <target>… which, if target is already a parent/ancestor of your commit, is the same thing. But if target has had changed since you branched from it, this prevents you from undoing any recent commits.
mwt 4y ago
This works well enough if (and only if) your company has a culture of small, atomic PRs.
- munk-a 4y ago
  Not really, I recently merged in a two commit branch where one commit was me changing all the vendor configuration for the framework we were using to a new version and the other was all the changes needed to support the change. That PR affected thousands of files in total but the need to frequently rebase the branch to avoid killer merge conflicts encouraged a low commit count. rebase -i can be your friend if you've got a long branch history that adds essentially no value (i.e. "Tried this thing/Didn't work reverting/Tried this other thing/Still no dice/Switching workstations"). An arbitrarily large number of file changes can be packed into a single commit, sometimes for review purposes it makes sense to purposefully isolate different groups of changes in a manner that doesn't mesh with how the dev work was actually done - sometimes I just don't want to have an ugly commit history. I'm allowed to be OCD about my work and sweep the commit where I added print __LINE_NUM__ between each LOC to track down a bug one time that I was too lazy to use gdb under the rug.
  - mwt 4y ago
    Yeah, I mean my comment more as a criticism of universally squash-merging as a policy since, not so much an endorsement of it in general. I run into cases like you describe pretty often, and I doubt I'm alone. Switching to squash-merging has some benefits but it's also brought out a fresh form of hell when too many changes are happening in too many branches at once.
    - munk-a 4y ago
      Oh absolutely - we have a pretty modest sized company and we do tend to "always create merge commit" because it makes some of our deployment tooling easier but otherwise git preferences are left up to the dev and the particulars of the situation.
eikenberry 4y ago
But the PRs aren't part of your git repository? IMO a git repository should be self contained and not require a hosted provide to give context. It lets you manage your work with superior local tooling and without a browser running. Basically I take the exact opposite approach where my PRs are always just a short summary of the commit messages and provides a place for me to put the github specific things like the "Fixes #..". But I make sure my commits are a clean artifact of the changeset by themselves (ie. I do any squashing, etc, on them outside of the PR).
- mwt 4y ago
  GitHub (by default) uses the name of the PR as the merge commit message and also includes the commit message of each commit in the log. Having whitespace-altering "Dummy commit to trigger CI, ugh!" commits in a git history isn't good but it still clutters the `git log` with stock squash+merge GitHub use. I can't speak for everybody, but if GitHub goes down completely and I only had access to my git logs, I'd struggle to recreate ~20% of the information scattered across issues and PRs. This issue is external to merging preferences, but it's definitely not solved by squash-merges and descriptive merge messages.
  - shagie 4y ago
    > Having whitespace-altering "Dummy commit to trigger CI, ugh!" `git commit --allow-empty` may be sufficient for that "there is a new commit" trigger in many cases. If so, that may be preferable to whitespace changes as those clutter up the blame. As an aside, my initial commit on a repo is an empty one so that I can branch from a completely empty repo to do radical rewrites and yet maintain a history relationship with that initial empty commit (which I feel is preferable to an orphan branch and then a merge with unrelated histories ... though those tell slightly different stories in the log).
    - stormbrew 4y ago
      > As an aside, my initial commit on a repo is an empty one so that I can branch from a completely empty repo to do radical rewrites and yet maintain a history relationship with that initial empty commit (which I feel is preferable to an orphan branch and then a merge with unrelated histories ... though those tell slightly different stories in the log). Oh cool, I thought I was literally the only person on the planet to do this lol. I'd do it for branchpoints too except git rebase by default acts very poorly with empty commits in the edited history (deletes them). I wish this was normalized (ie. there was a flag to `git init` to add a commit message for a root commit).
Everlag 4y ago
That's such a different approach than I've grown used to, but different platforms encourage different flows. I've been using bitbucket (not the shiny nice new bitbucket) at work for years and its PR search is so abysmally bad that anything in the PR message but not in the commit message may as well not exist once its merged. `git log` is forever, bitbucket search is /dev/null I'm curious what other affordances or lack of affordances encourage what git behavior.
simonsaysso 4y ago
For the code review step, sure, commit messages don't really matter unless your team reviews PRs commit-by-commit. How many times do you actually change the default squashed message? If you write a series of garbage commit messages, I don't particularly trust that you'll write a very good squashed message, either. How many times do people skip updating the PR description with new information or features from comments? If your commit messages are good, the auto-squash message will be good and one will have a network dependency on GitHub to figure out what decisions went into that change. In general I agree with your goal of a great commit log: 1 PR = 1 commit in the main branch. But I feel like GitHub is just the wrong tool to use if you want that. I used to use Gerrit, where commit messages _are_ your PR description. Sure, it makes you interact with git in some unfortunate ways, but the tradeoff is enforced commit cleanliness.
- woojoo666 4y ago
  Everybody I've seen modifies the squash message in a professional setting. After all, that's the one that everybody else will see. Commits on your feature branch don't really matter and the entire branch can be deleted afterwards anyways
rubyist5eva 4y ago
this works until you want to leave Github for whatever reason
- lelandfe 4y ago
  This happens sometimes when private repos change hands. I've worked at places where we've been given zips of git repos – commit messages reference PR and issue #'s from long distant organizations. I've since started policing PRs whose commit messages reference things inside of our GitHub. At least provide a summary of what you're linking, for the worst case future.
- ericmcer 4y ago
  Why? Wouldnt the commit history contain only the one squashed commit and its legible message?
js2 4y ago
There's a few reasons why this is a lossy workflow compared to commits with proper messages that are later merged, not squashed into one. 1. The PR itself becomes a single giant commit. To adequately explain the diff in a single message would require writing an essay instead of a few paragraphs. It is also now hard to tell which part of the PR message is associated with which part of the massive diff. 2. If something breaks, you can't dissect into which part of the diff caused the problem. 3. It's harder to document your work as you go. I may be working on a PR for days or weeks. Commits give me an opportunity to document each part of my change _at the time I make the change_. It's a chance for me to record how and why at the time it's fresh in my head. If I wait to do this until the PR is ready, I likely will have forgotten some bit of context I wanted to record about the commit. 4. It encourages sloppy commits, making a large PR harder to review. Ideally, I should be able to review a large PR by looking through each commit. If your reply to all this is to say you should just submit smaller and more frequent PRs, fine, but then why ever have PRs that consist of more than one commit?
swalladge 4y ago
> I prefer Github's method of "git commit messages don't matter, pull requests do". This is a bad idea unless it works well for your specific company workflows and you don't care about the future possibility of changing platforms. Git repos are designed to be self contained, decentralised, and offline-first. If you only care about how things look on github, then the repo will have poor usability outside of github - ie. on your workstation, in your local git tools, on a repo mirror, etc. Git commits can be a powerful tool for understanding code if the messages are useful. They are immediately accessible through local tools and can quickly add context to a block of code without breaking immersion. But that immersion is broken as soon as you hit a commit messages like "Merge pull request #123" or "fix bugs".
deleted 4y ago
[deleted]
jen20 4y ago
This would be a lot more reasonable if GitHub would provide tools to review the ultimate commit message in the same manner as the commit content.
Izkata 4y ago
> 1. Make it so the only merge strategy allowed on a repo is "Squash and Merge", so each PR = 1 commit in main branch Please don't do this. It erases history that's really useful for tracking down the cause of bugs. There's plenty of ways to use git log to filter commits if a pretty history is your goal.
woojoo666 4y ago
I agree with this. Oftentimes I am experimenting around (obviously on a separate branch) and use commits as checkpoints. Not every commit is a perfectly polished state. Using separate branches and then squashing when it is ready, gives me the freedom to experiment without constraint, and then clean things up when it is ready
teeray 4y ago
I abhor “Squash and Merge”, because I do take time to make good commits. They each pass tests, they have messages, and I rebase fixup commits away. For me, a merge commit is semantically meaningful (it even gives me a place to put who reviewed it in the merge commit message). This probably seems like a whole lot of work for no benefit. However, I can’t tell you he number of times I’ve been on crappy plane wifi, hit `git blame` on some line and been able to comprehend my state of mind making a change years in the past. Git history is a form of communication.
u801e 4y ago
> I prefer Github's method of "git commit messages don't matter, pull requests do". By doing that, you lock yourself into relying on Github in order to get the context behind a change rather than looking at the commit messages for a particular branch. That means, you cannot easily get that information just using git on the command line. On the other hand, if you put the context in a series of well formatted commit messages, you can get that context by reading through the commit log, either on the command line, or in Github by clicking on each commit. > 1. Make it so the only merge strategy allowed on a repo is "Squash and Merge", so each PR = 1 commit in main branch This leads to very large commits which cannot easily be reverted once any other commits that update the same files are added to the base branch. Also, in this case, the merge commits are essentially redundant, so why have them? There's nothing that prevents one from amending their commit to reference the PR number and eliminate the merge commit entirely. > It's easier to be more expressive in a pull request, and intermediate changes while working on a PR aren't super interesting to me. It really comes down to how those changes are presented. For example, if the change is one commit that adds a new method, and a second commit that adds calls to that method, that makes the change easier to review. Also, if a bug is found in the method, you can make a revert commit to remove all the calls to the new method, another commit to demonstrate the bug with one or more tests, another commit to fix the bug and update the tests to reflect that the fix works as expected. If the commit was just a single PR commit, and another PR was merged, then one would have to craft a commit to undo the changes pertaining to that bug and then make a new commit in another PR to add the updated implementation. This makes it harder to see what the fix was since you essentially remove the entire feature and then commit a new version of that feature.
brunellus 4y ago
The individual commits aren’t interesting until you need them. They should be organized such that they remove the desire to squash them together. Having a well written commit history is in the spirit of the tool and is the more professional approach.

themanmaran 4y ago

For those who write multi paragraph commit bodys, is there a tool you use to format them? Example commit on the React repo [1]. It just seems like a lot to type in the command line. [1] https://github.com/facebook/react/commit/ec52a5698e2dfea7050a0b015f0b79abfb2d81b7 https://github.com/facebook/react/commit/ec52a5698e2dfea7050...

xorcist 4y ago
Command line? git normally opens your chosen editor and you are free to write away to your heart's content. I guess you could stuff multiple -m in there and git will format it nicely, but the editor is for writing and is best used for that.
jrib 4y ago
My vim will automatically wrap when I am typing a git commit message. Should be set by default from here: https://github.com/vim/vim/blob/2f0936cb9a2eb026acac03e6a8fd0b2a5d97508b/runtime/ftplugin/gitcommit.vim#L13 https://github.com/vim/vim/blob/2f0936cb9a2eb026acac03e6a8fd...
imron 4y ago
vi :set tw=70
a_t48 4y ago
There's a good chance this was made in Github's squash+merge dialog. Edit: never mind, it's auto wrapped at some number
knoebber 4y ago
Emacs + magit and auto-fill-mode
rubyist5eva 4y ago
> It just seems like a lot to type in the command line. I spend my entire workday day in Vim.
teeray 4y ago
If you don’t supply `-m`, `git` will pop open your `$EDITOR` with the new commit message. You can use whatever tools you like to wrangle text in there. I use vim, so it’s just a quick `gq<motion>` to format everything.

bern4444 4y ago

I like the conventional commit style [0]. You may have seen these in open source repos or used them at work. They look like feat: support new line chart fix: update props for new line chart chore: bump dependency version What's also cool is there are tools (semantic release) that will then handle automatically the versioning and publishing of your module based on these commits using the commit type (feat, fix, chore etc) to determine the next appropriate version [1]. [0]https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ [1]https://github.com/semantic-release/semantic-release https://github.com/semantic-release/semantic-release

_virtu 4y ago
I built a full pipeline around this. Basically allowed for a paved road for devs to automatically semantically version and deploy application and module artifacts for npm with semantic release by spinning up a repo with some boilerplate generators I made available to the team. Since then I've been obsessed with the conventional commit format everywhere for my own projects. Even if the commits aren't parsed for versioning, it just gets you into the habit of thinking about the scope of the commits. The laughable part about building that full paved road pipeline is that the biggest friction point was always when devs didn't use semantic commits. At the time when I implemented it I didn't have checks for the commit format at the pr phase. I DID have a commitizen cli option as well but that was "Too much friction". Oh boy did I get bit. As someone who was working on DX I was constantly surprised by how many questions I got about something as seemingly simple as the conventional commit format from a crowd of enginerds.
- tardismechanic 4y ago
  +1 on conventional commits (big fan) also, +1 on fully paved road approach! You might want to check out this GitHub Action to enforce PR title matches the spec: https://github.com/amannn/action-semantic-pull-request https://github.com/amannn/action-semantic-pull-request
- irrational 4y ago
  > I was constantly surprised by how many questions I got about something as seemingly simple as the conventional commit format from a crowd of enginerds. I'm not. Writing code and writing git commit messages take entirely different types of thinking. With code you are having to think logically and problem solve to tell the computer what to do. Git messages are more analogous to writing a term paper (though shorter). You have to think about the what you are trying to communicate, how best to describe what this commit is all about, maybe trying to figure out if this counts as a fix or something else, etc. Writing code is fairly easy for me. Writing git commit messages is extremely difficult for me. I sometimes go days without commiting because I'm dreading having to write a commit message.

mwt 4y ago

This is from 2014, but I guess not much has changed since then.

transitivebs 4y ago

95% of the commits on my personal open source projects use emoji commit messages. https://github.com/transitive-bullshit/commit-emoji https://github.com/transitive-bullshit/commit-emoji PRs matter a lot more than commit messages, especially if you're squashing + merging / rebasing.

sph 4y ago
But why? That's even more useless than just describing a commit in a couple words. I'd rather see a commit saying "fix bug" when bisecting or reading a commit history than ":heart:"
slaymaker1907 4y ago
I've tried with the idea of an autocommit chron job or something which just uses timestamps and periodically rebases things to avoid tons of commits.
mwt 4y ago
Honest question, do you really expect your history to be meaningful long-term? Or are you simply taking the approach that the commit message is meaningless and a developer instead use GitHub search to find a PR relevant to a change they're investigating. For example, I pulled up one of your projects and the history (https://github.com/transitive-bullshit/kwote/commits/main https://github.com/transitive-bullshit/kwote/commits/main) is less than meaningless, compared to i.e. using emojis as a shorthand (https://github.com/tiangolo/fastapi/commits/master https://github.com/tiangolo/fastapi/commits/master)
- Bolkan 4y ago
  What if I want to revert to a previous state / compare current state with a previous state. "starting work on bizon gradiants" is way better than . Edit: apparantly HN blocks emojis. Love this feature.
- wdroz 4y ago
  Fastapi use gitmoji [0], this is well-documented and structured. [0] -- https://gitmoji.dev/ https://gitmoji.dev/

deleted 4y ago

[deleted]

pvg 4y ago

Previously https://news.ycombinator.com/item?id=13889155 https://news.ycombinator.com/item?id=13889155 2017, 118 comments https://news.ycombinator.com/item?id=10212582 https://news.ycombinator.com/item?id=10212582 2015, 90 comments

ufo 4y ago

I hate that rule about 50 characters. IIRC, it started because someone noticed that the average commit message in the linux kernel is about 50 characters. Then, for whatever reason it morphed into this widely propagated mantra saying that the maximum should be 50 characters.

slaymaker1907 4y ago
Writing a good commit message within those constraints is kind of like writing a haiku. It's kind of entertaining sometimes, though I think it should be a suggestion rather than a rule.
- remram 4y ago
  It's usually fine unless your change concerns a specific function/module whose name is 20+ characters. Often I am renaming a function/module/package and can't fit its name in the first line which I find really annoying. Trying to refer to it in a different way or abbreviating it is so awkward.
js2 4y ago
I know the articles calls it a rule, but really it's more a guideline. It's so that `git log --oneline` and `git shortlog` produce succinct output. It's also the email subject when using `git format-patch`. With all of these, the idea is to have a quick-to-read summary of the commit. That's all, really.
kibwen 4y ago
Indeed, I follow these rules but I routinely violate the 50 character limit. It's far more important for subject lines to be useful than to be maximally succinct; I'm not out here trying to write an essay in the subject line, but I do need it to be appropriately descriptive.
mhitza 4y ago
I think Linus himself recommended at some point that 50 character subject restriction (in a time when 80 character wide code lines were also still a recommendation). That wouldn't be important in itself, but Github trims your message at 50 characters as well. Because of that "feature" alone it's annoying to pass that limit.

tsuujin 4y ago

This has been my commit bible for years. I feel like it has been battle tested and has made my life easier.

cwkoss 4y ago

I saw this article early in my software development career and found it very valuable. Nostalgic and a good reminder. Send this to the still-learning software devs you care about.

rectang 4y ago

I like this post. I know people are offering their alternative conventions which they have various rationales for preferring, but I've followed the conventions this post advocates for years, and they haven't done me wrong. This post describes a widespread standard practice. People never complain about my commit messages and they don't have trouble understanding them.

anshumankmr 4y ago

Though I don’t think I am really the best coder out there, I was taught by a senior to use proper Git Commit messages which I usually follow only. I am however quite frustrated by my team mates who end up re-using the same commit message essentially for bugfixes.

goombacloud 4y ago

I rather prefer the first paragraph to be a problem statement and the second paragraph explain the change in detail. This gives the rationale upfront as the focus and helps to understand the problem and check whether the problem/goal was fully understood when making this change and whether the change actually covers what it should achieve. Overall, the change was/is just a mean to an end and other variations are possible.

imwillofficial 4y ago

A very timely article, I’ve struggled with what to put in a commit message. This gives guard rails to make it easy.

lamontcg 4y ago

I'm a heretic who prefers information in the PR. That's where the long-form back and forth arguments happen over the edge conditions. Periodically a few days after a PR has been merged I'll have a discussion with someone and realize some context was never captured, so I'll just add it at the bottom of the closed+merged PR for posterity. Yeah that means all the important information is in GH but if you migrate to GitLab or bitbucket or whatever they've got tools to pull all that info along with you when you migrate. I don't really care about individuals commits other than to find the gitsha to find the PR that they were merged into in order to find the full context.

logbiscuitswave 4y ago
It may be heretical but I tend to agree with this. Also at my workplace we tend to be standardized around PRs doing squash merges so there’s not really much point in having detailed interim commit messages anyway. As long as the PR has good information (and of course is linked to useful work items with good information) that’s usually good enough for me. (Of course more often than not people have empty/useless linked work items, and PRs with useless titles and descriptions but that’s a whole different kind of problem.)
adastra22 4y ago
Write a commit script that pulls in the PR text into the merge commit.
- lamontcg 4y ago
  > Periodically a few days after a PR has been merged I'll have a discussion with someone and realize some context was never captured, so I'll just add it at the bottom of the closed+merged PR for posterity.
emacs28 4y ago
I totally agree with this, I'm not a fan of the written-in-stone nature of commit messages. Just like code, it's nice if log history is editable too in case your forgot something, or if you want the message to mention future changes that back reference it.

rafaele 4y ago

What do people think of this line? > Use the imperative mood in the subject line The only rationales I've seen for using imperative ("fix bug") over the indicative ("fixed bug") are that it's what git does by default anyways. Is it really that big of a deal to use the indicative sometimes and imperative other times? For what it's worth, I always write commit messages in the imperative, out of habit. When others write commit messages in the indicative tense, part of me notices, but I move on because I can still understand the message if it adheres to the other guidelines.

owalt 4y ago
None of this is really worth obsessing over I think, but one point in favor of imperative is it tends to also be the tersest phrasing, which is convenient if you're also aiming for 50 characters max.
synicalx 4y ago
So long as the meaning is clear, it really doesn't matter IMO. Just write it so that when viewed in isolation the meaning of the message is clear and matches the changes held within the commit. Anyone who gets up in arms over "fixed" vs "fix" needs to get a life.
stinos 4y ago
I use imperative, but for other projects which don't I switch to indicative if that is the style. Personally like imperative more, not sure why, just preference. > Is it really that big of a deal to use the indicative sometimes and imperative other times? 'big', don't know, but wouldn't be surprised if there's an objectively provable higher cognitive load for having to read a mix of both (or, god forbid, other styles thrown in there as well) vs one consistent style. Just like there is for code etc. And some people are affected by striving for consistency more than others, so for them lack of consisteny might cause some extra friction.
deleted 4y ago
[deleted]
tremon 4y ago
The imperative mood/future tense ("this commit will...") makes the commit the subject of the message, the past tense makes the developer the subject of the message. In my (limited, personal) experience, the people who insist on past tense commit messages have more trouble killing their darlings, are more likely to take review comments personal, and are more likely to view (part of) the codebase as theirs rather than the team's. So for me, it's not about the commit message itself, but the communication style says something about the developer and how I best approach them. My take on this requirement is that it helps developers let go of their attachment to the code they've written.

stjohnswarts 4y ago

descriptive subject with 50 chars or less skip a line more thorough description if needed. You don't need 7 rules to remember. KISS

twhitmore 4y ago

Interesting topic. From my experience Headline + Bullet Points are far quicker to convey useful information, in a form that is terse yet easy to read. For example: ---------------- improve Buffer Cache Management & logging - change 'tryDrop()' to skip immediately, if lock unavailable - move BufferCache logging to a separate logger - attach BufferTrim.Unsuccessful -> Preemptive Flush of oldest buffers -------------------------------- Having worked in many codebases & internal docs, I've found narrative significantly less efficient to read & write. In commit messages, far too many developers skip almost any detail as to what they're changing & why -- the slowness of narrative formats may substantially contribute to this. In docs (Wiki etc), narrative encourages developers to ramble about minor technical details while omitting all high-level context. Headline + bullet-points bypass a lot of struggles with narrative by allowing a simple headline and then, well, cutting to the point. This also illustrates a informed personal preference -- studies find lowercase English words faster to scan/ comprehend. See: http://literatejava.com/git/how-to-write-a-good-git-commit-message/ http://literatejava.com/git/how-to-write-a-good-git-commit-m...

stinos 4y ago
I don't really have a problem with bullet points, conveying relevant information is after all the most important thing the message should do, but if that example is an actual one then it would raise some flags during review. Mainly because it's not super readable (mix of styles, super terse requires extra interpreting) but also because it mostly explains what has changed (most often unneeded information, as that should be clear from the diff) and not really why it is done that way (ok, the code might have comments, but still I expect the message to explain that). In my experience, using bullet points like this is correlated with this style of messages which just list 'I did x, y, and z' whereas a more narrative style, which can still go in bullet points, is correlated with easily digestable messages explaining properly the reasons for changes. Anecdotal of course.
- u801e 4y ago
  > it mostly explains what has changed (most often unneeded information, as that should be clear from the diff) and not really why it is done that way Ideally, commit messages should at least briefly explain what was changed (e.g., Add feature X, Fix bug Y) in addition to why it was done. When people look at git log output, they won't always show the associated diff for each log message. Also, when running git blame, they'll see the commit id and title, but not the entire change. That doesn't mean that one can't run other commands to see the associated diff, or even getting the overall branch diff from the commit ids recorded in the merge commit, but having that what was done in the commit message allows one get an understanding before looking into it in more detail.

kgeist 4y ago

We also have a rule to prepend every commit message with its issue number in our issue tracker (we don't use GitHub). That way in Git Blame/Log you can always quickly find where the change came from and why - the issue tracker usually has more detailed information.

hansoolo 4y ago
Yup, we do the same and it works out pretty well this way.
toastal 4y ago
This really treads on the char limit in the titles though
selcuka 4y ago
We do the same and it works pretty well. The problem with that approach, though, the codebase may live for decades but issue trackers change and old tickets usually don't get migrated to the new system.
- kgeist 4y ago
  >old tickets usually don't get migrated to the new system Well, our current issue tracker was migrated from Jira and I can still see all the ancient Jira tickets just fine (I mean what's important: the comments). In any case, something is better than nothing at all.
atq2119 4y ago
Curious, I've run into this approach in the past and learned to hate it with passion. That place used JIRA where the typical ticket ID was around 10 characters. That wasted a lot of prime real estate, e.g. in my email inbox, in history views (tig, gitk, and so on). I also don't see the claimed benefit for git blame. In a real code base with significant history, it happens often enough that the first blame is an unrelated refactoring and you need to dig deeper. Therefore, I find that best practice is to look at the blamed commit first instead of the ticket. That gives you the full commit message, which can still contain a reference to an issue. Putting footer lines like "Fixes: <issue>" into commit messages works much better. It's just as easily visible in git log etc. and doesn't waste space.

alexeiz 4y ago

My opinion about Git commit messages has always been the same: if you can't describe it in English, you don't know what you're committing. If your commit message is too long and messy, you're committing unrelated things that should be split into multiple commits. The commit message is a direct indicator of the quality of your commit.

marseysneed 4y ago

Sometimes I wonder about repos that do not follow any guideline. I use an open source service[0] that never describes what the commit is about, so just know that any description of the commit is better than none at all. [0]https://github.com/Aevann1/rDrama/commits/frost https://github.com/Aevann1/rDrama/commits/frost

beermonster 4y ago

Is there a reason why GitHub don’t make it easy in 2022 to write nice commit messages? Larger boxes, visual cues for character length, non default commit messages such as ‘Updated doc blah’ which are useless. Lots at our place solely use the GitHub UI to edit Markdown files mainly and their messages are typically the least useful for that reason.

Sheen96 4y ago

My philosophy tends to be that your first commit should convey the task you are trying to achieve and additional commits beyond that point should be fixups, to be rebased into the single first commit before merging. This removes the back and forth of changing and reverting the same files, changes from PR comments etc. It's much more coherent.

rendall 4y ago

A junior dev turned me onto this several years ago, and I've gone by it ever since. I was skeptical at first. For instance, the given reason for using imperative mode is not strong, in my opinion (the default git message on merge and revert is imperative is not a good reason, because other default git messages do not use the imperative). But, there are other good reasons for using it, not least of which is arbitrary consistency lowers cognitive load. Now, it's my go-to if there isn't a good reason otherwise.

hoseja 4y ago

Manual wrapping for the sake of dumb terminals is such a pet-peeve of mine. Why? It's so awful to read.

onion2k 4y ago

Every time I read something about "how to write good commit messages" it always seems to focus on reading the messages back as a log. That's great if that's how you use commit messages, but I tend to use them more for searching for a specific change so it doesn't really work for me. A more narrative style in commits I might need to go back to makes it easier to find them later. How you write your commit messages should be driven by whatever you use them for afterwards.

sudo_chmod777 4y ago
Define 'specific change'. A change driven by a business decision? Don't see how it won't work. A change specific to a component? Try conventional commits with scopes. Code change? You shouldn't use commit messages. Use e.g. `-G`, `-S`, `-L`, etc. instead. By the way if you are not using fzf already, you should.

revskill 4y ago

Mine is "[JIRA_TICKET] Add something" It's simple and worked well for us so far. Less rules, more information, and developers are free to use their words to express intention of changes instead of nonsense (feat, fix,....)

tremon 4y ago
Have you gone through a ticketing system change yet with a developer team? I've seen several, and not once was "we must import the old PR's/issues/features into the new system" given any serious consideration. Conversely, every source control system migration I've seen took great pains to preserve the committer, the date and the full commit message of each separate commit. Point being, in a few years all your [external references] will be useless. Can your commit messages explain the commit context on their own?
- revskill 4y ago
  OK, my question is, no effective commit message system exists without a consistent ticket system. A ticket reference gives you all you need. You see it in every line of code, from there you know the reason for that code to be written, it could include a reference to slack discussion url,...

Traster 4y ago

Honestly, the best guidance is just "put more than 2 seconds effort into your commits". No one really believes "More code" is a good commit message, it's just laziness. So yeah, put a little effort in, it's literally one of the few parts of your work that will remain once you are gone. Most code I've worked on gets replaced/updated/modified after I'm done working on it - but the one thing that I know will stay is the git history that some poor bastard will have to search through to figure out why this random bit of code ended up this way. The only other thing I'll say is don't be weird. I knew a guy who would prepend his commits with a [tag] saying what part of the repo his commit was touching. This was a mixed sw/hw project and every single commit of his started with [sw]. It's like, ok thanks, firstly, you're a software engineer working the ../sw/ folder, secondly no one was confused that your 17 changes to a C++ file were going to be a hardware change.

mmcnl 4y ago
I like this. Any advice other than "putting in effort for more than 2 seconds" has a lot of hidden assumptions about the context and organization around your code. Some days I only do a commit once at the end of the day as a backup. Other days I have 10 commits in 1 hour because everytime I thought I was finished I found something else that needed to addressed. In practice, there often is not a very strict process around commits, so specific advice is often not very useful either.

kazinator 4y ago

I will play the devil's advocate: why would anyone outside of the realm of die-hard FOSS on Unix-like systems wrap text to 72 columns? Look, I'm not doing it now. This entire paragraph I'm entering into HN is one giant line of text that gets wrapped. Suppose you're working on software for which patches will not be sent to FOSS mailing lists that are anti-HTML, anti-MIME, anti-long-line, ... why would you wrap the body of commit messages to 72 columns?

everybodyknows 4y ago
> Why would anyone outside of the realm of die-hard FOSS on Unix-like systems wrap text to 72 columns? Because if the commit is performance related, including regression test results may be mandatory. Test results will be in some fixed format e.g. tabular, commonly exceed 72 columns, and become gibberish if wrapped.
- kazinator 4y ago
  If it becomes gibberish when wrapped, why would you do exactly that? If I have 200 column wide regression test results in a nice tabular format, maybe that's the way it should stay in the commit message.

DrBazza 4y ago

I'm sure quite a few commenters on here only started writing code in the last 15 years. What's interesting is that git is (more or less) the de facto version control system and has been for that 15 years, and that likely means that what you put in your commit messages will stay around forever (for some definition of forever). As a greybeard I've gone file-based backups, then SCCS, CVS, SVN, and now git for what seems like forever (git was 2005 according to wikipedia), though probably the late 00s. And migrating from one to the next (yes, quant code from the 90s is still running in 2022, and we have the commit messages to prove it). Some people commenting above/below above the PR being the source of in depth information. As far as PRs are concerned, it's just another issue tracker, and I've been through the lot, also including various git hosting services). The commits travel with the repository. The PR discussions don't.

epmatsw 4y ago
100 times this. I’ve worked at a company with a commit history going back to 1979 (literal paper logs at that point, plus in-file headers), and another company where we lost ~2 years worth of historical context/info to WIP commits because “our internal GitHub instance has that info” turned out to not be true when we migrated to a new instance. Nowadays, the relevant info from our PRs gets copied to git, and I hope in 40 years if someone has a question they can still see that history if needed.

ABraidotti 4y ago

I'm a frazzled git babysitter. All I ask is that you start with a verb and keep it in present tense!

planede 4y ago

I think the most important thing is that the commit message should capture the high level intent of the change. I write "intent", because the actual effect and "intent" can differ, and commit messages are immutable. It's fine, as long as you recognize that the commit message is there to capture original intent. You often see "Fix bug #1234", but you rarely see "Introduce bug #1234". The other stuff about using consistent tense, capitalization, punctuation, etc... is important, but secondary.

incomingpain 4y ago

I have only been using git for a few years. subversion was popular for a long time. I rarely pay much attention to git commit messages. I would very much rather look at the diffs and see where/what it changed. >Capitalize the subject line Does this really matter? Really?

gbear605 4y ago
It matters to the same degree as being consistent about variable naming. It doesn’t change whether the system works, but if everyone is consistent then it’s easier to read and understand later.
- incomingpain 4y ago
  > It matters to the same degree as being consistent about variable naming. It doesn’t change whether the system works, but if everyone is consistent then it’s easier to read and understand later. I must admit I don't like that PEP rule. Camel case in some places, no capitals in other places. I just whatever I want really.

zoomablemind 4y ago

In my experience, when possible, the commit messages should read as part of a spec, describing the implemented behavior (mostly imperative). Even when fixing a bug, the commit would state what the code is intended to do, just as its resp. test exercises. This way it's somewhat easier to follow the reasoning of the committed changes. Another detail is to prefix a subsystem affected, that's in case of modular or complex application. Also help focus the attention. My preference in general is to write single line messages (shorter ok, longer - ok too), unless it's something very non-trivial and source-code policy discourages lengthy comments.