22 ms·

My favourite Git commit (2019)

• aeurielesn 3y ago
  I had a terrible time when someone used "smart quotes" (beautified Office quotation marks) in a configuration file. I believe this was only possible because they copied it from Outlook.
  • karagenit 3y ago
    Yeah, I've been bitten by those quotes in the past too. I noticed recently that VSCode (probably other IDEs too) highlight these characters pretty clearly to help avoid these issues.
    • jboy55 3y ago
      I wonder how much infighting there was between orgs at Microsoft over this. with an Outlook/Word PM escalating... "Make the languages understand smart quotes!"
  • atahanacar 3y ago
    >smart quotes I never understood why a "stylistic" choice requires separate characters. If we don't need a serif and non-serif version of every character and instead leave it to the software, why can't we do the same with the "smart" quotes?
    • kristjansson 3y ago
      Typographic quotes are left- and right-handed, vs. the ASCII double quote which is just a single character: “quoted” "quoted" Who in the blazing highs of techno-utopianism fervor thought it was a good idea to automatically translate the latter to the former we'll never know.
      • atahanacar 3y ago
        Why not stylize it as typographic but store it as a "regular" double quote though?
        • account42 3y ago
          One problem with that is that the correct start/end quotes to use depend on language which is not always know for all text snippets.
        • mbork_pl 3y ago
          How do you handle non-paired ones then?
          • maleldil 3y ago
            Render them as standard double quotes? The same way Markdown renders a single backtick as just a backtick, but text surrounded by backticks becomes code.
            • mbork_pl 3y ago
              Nice try, but the problem with this is that typography is _really_ complex. For example, there is a rule in English typography (I'm not sure if it's often used today though) that when you have a quotation spanning several paragraphs, you should put an _opening_ quote at the beginning of each paragraph – but only one _closing_ one at the end of the quote.
              • yencabulator 3y ago
                We've let go of other historical typographic and spelling conventions, it's time to let go of that one too.
                • kristjansson 3y ago
                  Computers exist to represent, transmit, and display _human_ communications. If a computer system cannot represent a human utterance we should extend the representational capacity of the computer system, not force the human to conform to the limitations of the technology.
    • jotaen 3y ago
      > I never understood why a "stylistic" choice requires separate characters. I don’t think it’s a purely stylistic choice, there is actually semantics to it: “ opening quotation mark, i.e.: starts the quote ” closing quotation mark, i.e.: ends the quote You could otherwise make the same point about parenthesis: why not just |do this| instead (of this)?
    • thaumasiotes 3y ago
      It's not a stylistic choice. Opening quotes and closing quotes are different things, and it isn't possible to tell the difference (when not already provided) without parsing the language in which they're used. That's why in TeX you have to manually specify which kind you want, and in software like Wordpress that just guesses, the guess is usually wrong and your published text looks ridiculous.
      • yencabulator 3y ago
        The complaint was purely about software replacing normal quotes with "smart quotes", not that it did it wrong.
        • thaumasiotes 3y ago
          But the question was why there's more than one code point between normal quotes, left quotes, and right quotes, and the answer is that it isn't possible for left and right quotes to share a code point.
    • mgdlbp 3y ago
      "quote unification'': most typefaces: “Hello” „Hallo“ Verdana: “Hello” „Hallo“
    • o11c 3y ago
      Double quotes can be unambiguously autodetected by checking word boundaries, but separate single quotes are needed since apostrophe is the same character as a close quote, but can appear at the start of a word. Note that most smart-quote-generating software does fail badly at this. Some common ambiguous pairs: ’bout - abbreviation for "about" ‘bout - starting a quote about a round of a fight ’cause - abbreviation for "because" ‘cause - starting a quote about a reason or ideal ’em - abbreviation for "them" ‘em - starting a quote about typographical units ’n’ - abbreviation for "and" ‘n’ - speaking of the letter itself
  • euroderf 3y ago
    For a long time there was a Perl script called the Demoronizer that fixed this kind of nonsense.
  • selimthegrim 3y ago
    I think this pops up in MacOS shells too
    • dblitt 3y ago
      IIRC TextEdit.app has options like smart quotes, auto capitalize, and spell check turned on (in addition to being rich text by default), so you have to change all those to be a dumb plain text editor.
      • fishyjoe 3y ago
        TextEdit and the Notes app have both caused me to copy/paste the specialized quotation marks. Now I only use vim as a scratchpad because I've been bitten too much by GUI apps
  • keybored 3y ago
    In other words real quotes that people use in published writing.
• OJFord 3y ago
  One thing I disagree with is: > I wouldn’t expect all commits (especially ones of this size) to have this level of detail. (emphasis added) - actually in my experience it's often the little ones, innocuous looking things that might really need a relatively longer explanation. Yesterday I wrote three paragraphs on why I added `--limit=999` to a `gh pr list` because it's confusing: there's already a `limit(` in the `--jq` argument, and the higher it is (given say infinite PRs in total) the lower the end result will actually be. (Yes I wrote a comment too. And probably spent even longer thinking about and working it up than writing about it; hopefully I'll recall it as an example the next time someone implies the job is about churning out code!)
  • pdpi 3y ago
    I find myself commenting code in a similar pattern: A small kernel of "interesting" code that has a 1:1 ratio (or higher) of comments to code, which enables the rest of the codebase to be "boring" self-documenting boilerplate-y code that doesn’t really warrant much in the way of commenting.
  • keybored 3y ago
    For a commit that adds a language binding (and might be 100+ additions/deletions) I might just say “Add X function”. Because I’m just following established patterns. But for the linked kind of change? Yeah, several paragraphs of explanation is definitely useful.
  • unregistereddev 3y ago
    I agree with you that the little innocuous things often need a longer explanation, but the linked commit message is way too long IMO. It either wastes the readers' time, or it causes the readers' eyes to gloss over at the wall of text. You don't need to document your entire journey in order to document your findings and explain why. > This was a non-ascii whitespace character that caused `ArgumentError: invalid byte sequence in US-ASCII` when running `bundle exec rake` ^ should be sufficient. It includes enough keywords to come up in a search if someone has a similar problem in the future, it contains the root cause of the problem, and it is short enough that people are unlikely to gloss over it.
• dlvhdr 3y ago
  I do appreciate them but they’re just a pain to write sometimes
• spenczar5 3y ago
  I have felt that pride in writing a great commit message, but I am less sure of the value to others. I don’t think most people search commit messages when they encounter an unusual error message, or when adding a new feature, or really almost ever. It’s a bit sad, but I have a growing suspicion that beautiful commit messages are a bit of vanity by the programmer. The person primarily impressed is often the author; others will walk on by without noticing. There is room sometimes for those aesthetic flourishes but I am not convinced they have much practical value, and I have stopped really being bothered by commit messages of “fix whitespace issue” from others. I think I am a better colleague for that. Things might be different on a project like Git or Linux with huge distributed teams and tons of commits, versus the projects I am used to which have between 1 and 100 contributors, mostly from the same organization.
  • j2kun 3y ago
    I find them valuable, especially when trying to study a new codebase. In the current era where we get immediate feedback on everything we post online, it's harder to see the value that comes from writing good commits, and the value can be delayed by weeks, months, or even years.
  • cybrox 3y ago
    If anything, this just tells us that tooling should incorporate commit messages a lot more. While these kind of messages are most valuable in large projects, there are some of them in a lot of projects and they could have saved a lot of time. Especially now with AI IDE integrations, incorporating a software's whole history into supplemental tools would be more useful than ever before.
  • bombcar 3y ago
    > I have felt that pride in writing a great commit message, but I am less sure of the value to others. I don’t think most people search commit messages when they encounter an unusual error message, or when adding a new feature, or really almost ever. They have value even if the only person who will ever look at them is you - and I will say that when bisecting an issue, the commit message of the commit I finally find is really useful (or it could be if it wasn't fixed thing). It also means that if you encounter a similar issue again, you know that there's a note on a commit you can find.
• deleted 3y ago
  [deleted]
• keybored 3y ago
  Here is a context-full commit message.[1] This is so common that the maintainer wrote this[2] [1] https://github.com/git/git/commit/d70f554cdf38b0b05cfaa8e8eb9f80d54a5ae11c https://github.com/git/git/commit/d70f554cdf38b0b05cfaa8e8eb... [2] https://lore.kernel.org/git/xmqqedevo8ps.fsf@gitster.g/ https://lore.kernel.org/git/xmqqedevo8ps.fsf@gitster.g/
• Zambyte 3y ago
  I guess it makes sense that it's a common name, but I was expecting this David Thomson[0] instead :-) [0] https://dthompson.us/ https://dthompson.us/
• excitom 3y ago
  It's a great commit message, but could be even better with "TL;DR non-breaking space in a comment can cause parser problems".
• adrianmsmith 3y ago
  I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. (I mean you could obviously with "rebase" but are you really going to alter something written one year ago, already merged to "main", and cause a bunch of pain with everyone's feature branch etc.?) Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleague can write something and if I see a way to improve it I can go ahead and do that, and other colleagues can improve on what I've written. In this particular case I suppose the bug is fixed and won't come up again. But I also myself find it tempting to describing the design of a particular component when I commit that component, and that's something I now avoid. What about when that component needs to be changed by a future commit e.g. due to the business requirements changing? Will the commit documentation just describe the differences? Then in order for a new team member to find out how the system works by reading the documentation they've got to read multiple commit messages and "merge" them in their head.
  • macintux 3y ago
    There's no reason this documentation can't be replicated in another context, and for all we know it was.
  • tyrust 3y ago
    I think commit messages are mostly valuable for a future code reader asking "why is this bit like this?" and then looking at blame logs for the answer. As you point out, bigger picture stuff ought to be elsewhere (documentation, tracking bug). Keeping docs in version control and including doc changes with the code changes is a nice way to address your concern.
  • josephg 3y ago
    I really think git made a mistake in conflating the immutable log of what was changed with the (ideally mutable) story of what got merged in. So you see people arguing over squashing commits vs rebasing vs merging. Squashing commits makes the history of commits a better story of features being added. Merging preserves the immutable log of the actual changes made to the code, and rebasing sort of does a bit of both. But, I don't see any reason we can't have our cake and eat it too. We're programming computers after all and we can make them do whatever we like. If I wrote my own git, I think I'd split commits into those two parts. I'd leave the history of changes immutable - probably with some sort of Merkle DAG like Git does. And then have a separate associated data store which stores the commit messages, in a nice sensible, editable log describing the work that actually happened. Let people arrange and rearrange the commit descriptors however they like. If you want, group commits around feature tags, fix typos and make any changes to the messages that you want. But, the whole while the underlying log of diffs ("what actually changed in the code") can remain (gloriously) unaffected.
• fusslo 3y ago
  great commits are great. This is fantastic As an aside, I'm tired of documenting: - in code - in commits - in jira - in confluence - in daily standups - in release notes
  • marcosdumay 3y ago
    The code and commit documentation are about different things. One is about what this thing is, the other is about what is changing. But then, jira is about what is changing, confluence is about what is changing, standups are about what is changing (oh, but this is doing them wrong), and release notes are about what is changing. So your complaint is completely reasonable, just the first item shouldn't be there.
    • fusslo 3y ago
      I dont think Ive worked at a company that used commit messages to record what is changing. Im not saying that I am disagreeing with you on that point. I’m just sharing my experience We tend to rely on the diff and PR for the ‘what is changing’ The PR doesnt list the commit messages anyway, just the last commit message and the PR description We add links to jira/confluence a lot in code to give direct access to the dev. Commits are tied to features or bugfixes So effectively commit messages are not useful anymore The only one that might be useful is the merge commit message Again, not disagreeing, just complaining lol
    • GuB-42 3y ago
      You also get what is changing by doing "git diff", and often, it is self explanatory, especially if you have already commented in code why you did what you did. For example: - code: MAX_SIZE=1024 // maximum size the backend supports - commit: limit the size to 1024, as it is the maximum the backend supports - jira: fixed the problem by limiting the size to 1024, as it is the maximum the backend supports - confluence: do not exceed 1024, as it is the maximum size the backend supports - standup: I set the maximum size to 1024, as it is the maximum the backend supports - release note: Maximum size set to 1024, as it is the maximum the backend supports This is all redundant. I used a simple example for the sake of brevity, and one-liners are reasonable in every case, but the problem is when you are expected to write a wall of text every time, when in reality, there is everything you need in the code.
• rpsw 3y ago
  Overall agree with the sentiment, but I would add a more specific Bottom Line Up Front (BLUF) such as: "Fix test issues caused by non-breaking space character \xa0". Tells me exactly what the problem was straight away, but I'm still free to choose to read more if I want to know more.
  • nextaccountic 3y ago
    I love this concept. I always begin messages with the most actionable or important thing at the top, and the rest that follows is the context. Respect the time of others and don't bury the lede
    • SamuelAdams 3y ago
      You see this all the time in business proposals. Executive summary at the top, typically 2-3 paragraphs max. Manager summary, 1-2 pages. Engineer detailed overview, 3-10 pages. Anything else is an addendum.
  • master-lincoln 3y ago
    This would be my ideal commit message as well. The rest of the commit body in the article is just how it was discovered. I don't think describing how one works belongs into a git commit message. Your message tells me why and which change was made, that's enough to me.
  • Anon1096 3y ago
    Yep this message is way better. And honestly, looking at the diff in github it is pretty obvious to me what has changed (and why really, since the only reason for a changeset to have a diff look identical is that non-visible characters have been added or removed). So all I'd require is a good main message for history-search purposes. A short story about how you went to Narnia and came back to find the root cause of a bug isn't really relevant imo but I'm also not against writing it if you just want to vent in a PR description/commit's extended message.
    • ninkendo 3y ago
• andrewfromx 3y ago
  I stated using gofakeit's "hackerphrase" for all commit messages. https://github.com/andrewarrow/feedback/commits/main/ https://github.com/andrewarrow/feedback/commits/main/ hp | git commit -a -F - hp is a golang binary that just spits out a hacker phrase. I have this aliased with the letter q for "quick" so I'm always checking in stuff with q return push done.
  • karmajunkie 3y ago
    I've been using opencommit[1] and have been pretty happy with the summaries its generating. I usually add a one liner at the top to summarize the reason for the PR but it saves me a lot of typing documenting what was actually done at a high level. [1] https://github.com/di-sukharev/opencommit https://github.com/di-sukharev/opencommit
  • lexicality 3y ago
    that's a great idea but you can make it even more efficient head -c50 </dev/urandom | xxd -p -u | git commit -a -F - That way you'll never accidentally overflow the commit message first line length and no one will even begin to think that the messages might mean something!
    • andrewfromx 3y ago
      this is great. If I do a mix of these + hacker phrase I'll be able to find a commit like, "oh yeah, it's the one right after the urandom bytes.
• WalterBright 3y ago
  At the DLF, our pull requests are usually accompanied by a link to the bugzilla entry, which usually have a detailed explanation. P.S. Having multiple Unicode values that exhibit identically when displayed are a huge veer-into-the-ditch mistake. I.e. the notion that code points should have semantic value is simply wrong.
  • boolemancer 3y ago
    > P.S. Having multiple Unicode values that exhibit identically when displayed are a huge veer-into-the-ditch mistake. I.e. the notion that code points should have semantic value is simply wrong. Should a cyrillic `а` and a latin `a` have the same code point? If they did then there's no consistent way to group those two alphabets, one or the other would end up with letters outside it's main grouping. And what happens if the shapes of those two characters divege over time? Do you have a breaking change to introduce a new code point for one of the languages, or do you just make it impossible to have a font that can be used for both latin and cyrillic at the same time? This isn't just a theoretical problem, by the way. There are characters in Chinese and Japanese that share a code point but the shapes of the characters aren't the same in the two languages.
    • WalterBright 3y ago
      > Should a cyrillic `а` and a latin `a` have the same code point? Yes. Consider a book. Can you tell if it's a cyrillic or a latin `a`? Of course you can, because of the context. Unicode is about visible text, having hidden semantic meaning makes it something else. Besides, 'a' can have all kinds of semantic meanings - all depending on the context in which they are used. There is no way to encode all this into Unicode. > If they did then there's no consistent way to group those two alphabets Doesn't matter. > And what happens if the shapes of those two characters divege over time? If it actually looks different, then it becomes a different code point. > There are characters in Chinese and Japanese that share a code point but the shapes of the characters aren't the same in the two languages More evidence that the Unicode committee lost its way. Think of it this way. Printing Unicode text on a piece of paper, and then OCRing it back into Unicode, should be a lossless operation. Or another way - anyone should be able to tell what the code point value is by looking at the visual representation of it.
• ajuc 3y ago
  I agree commit messages are the most important form of documentation. But I disagree about the format. I prefer commit messages like: JIRA-123 one-line 80-char-at-most description Long description if needed (but preferably keep it in JIRA).
  • masklinn 3y ago
    > but preferably keep it in JIRA Jira is an additional indirection to a tool you will (not might) eventually lose. I’ve seen commits which had lived through 3 VCS transitions. Not only that, but a lot of information is often considered undesirable on tickets.
  • computerfriend 3y ago
    Deeply strange to me that you can think that they're the "most important form of documentation" and then propose to put the documentation elsewhere.
    • ajuc 3y ago
      JIRA contains more context than you can put in even most elaborate comment. For example links to duplicates, test cases, screenshots, core dumps, discussion with testers/customers, etc. And it's updated over time. Would you change the commit message if a tester noticed something about your explanation of the bug was wrong but the fix still works? Additionally the context is already there in the JIRA, retyping it in detail in a different format into the commit message is more friction for little benefit.
• bhasi 3y ago
  For great commit messages, just browse the git history of the Linux kernel where this is the standard. The first line always mentions the subsystem affected by the change, followed by a one-line imperative-mood summary of the change. Subsequently, three questions are answered in as much detail as possible: 1. What is the current behaviour? 2. What led to this change? 3. What is the new behaviour after applying this change? Example: "Currently, code does X. When running test case T, unexpected behaviour U was observed. This is because of reason R. Fix this by doing F."
• chjj 3y ago
  Just an aside: is there a vim syntax command to highlight weird unicode whitespace as an error? Something like: syn match unicodeWhitespace /[list of unicode whitespace]/ hi def link unicodeWhitespace Error
  • a_e_k 3y ago
    I wouldn't know about the Vim equivalent, but I wrote this in my Emacs config long ago: (defun find-non-ascii () "Find and show all of the non-ascii characters." (interactive) (occur "[[:nonascii:]]")) It has proved quite useful on occasion. (Yes, I could just invoke Occur directly, but I can never quite remember the regexp character class and syntax here.)
    • chjj 3y ago
      No worries. I managed to whip something up: autocmd BufWinEnter * match ErrorMsg /[\xa0\u1680\u2000-\u200a\u202f\u205f\u3000]/
  • xigoi 3y ago
    For non-breaking spaces specifically, there is :help 'list'.
• gtirloni 3y ago
  Great commit indeed. lots of context information. that's gold. The worst I've seen are dozens of tiny commits pushed to the master branch directly. If you want to find out what took to implement a feature, good luck. I'm a fan of tiny commits during code review but afterwards I prefer to squash everything in a functionally relevant commit. It makes git archeology much easier.
• schacon 3y ago
  For better or worse, my experience as a GitHub cofounder and author of several Git books (Pro Git, etc) is that the Git commit message is a unique vector for code documentation that is highly sub-optimal. The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. So in the case of this commit example would be the very simple message of a generic "US-ASCII error" problem. Everything they talk about in this article is what is great about the _rest_ of the commit message, which, given modern tools, is _almost never_ seen by anyone. The main problem is that Git was built so that the commit message is the _email body_, meant to be read by everyone in the project. But for better or worse, that is not generally the role of this text today. Almost nobody ever sees it. Unless it's discussed in a bunch of patch series over a mailing list, nobody reads anything other than the first 50 chars of the headline. It's actively difficult to do, by nearly every tool built around the Git ecosystem. Even if you're _very good_ at Git, finding the correct invocation of "git blame" (is it "-w -C -C -C"? Or just _two_ dash C's?) to even find the right messages that are relevant to the code blocks you care about is not widely known and even if you find them, still only show the first line. Then you need to "git show" the identified commit SHA to get this long form message. There is just no good way to find this information, even if it's well written. This is one of my biggest complaints with Git (or, indeed, any VCS before it), and I think why people just don't care much about good commit messages. It's just not easy to get this data back once it's written. If you want an example of this, search through the Git project's history. Run a blame on any file. It's _so hard_ to figure out a story of any function implementation in any file, but the commit messages are _pristine_. Paragraphs and paragraphs of high quality explanation for almost every single commit. Look at any single commit that Jeff King has done for the last decade. Hundreds of hours of amazing documentation from a true genius that almost nobody will ever appreciate. It's horrifying. I don't know exactly what the answer is, but the sad truth of Git is that writing amazing documentation via commit message, for most communities, is almost entirely a waste of time. It's just too difficult to find them.
  • codemac 3y ago
    It's great for historical research though. It's one of the few pieces of documentation that will live with the code forever. github and other forms of centralization are not open data formats that folks trivially backup/convert/carry forward. They usually leave the data behind if they move the project somewhere else. So no, I don't think it helps the current community much either. But it helps the debugger years later.
• mo_42 3y ago
  I have a different opinion about favourite Git commit messages. I think commits should be small steps that display the thought process of the author. Every individual commit should be self-explanatory. So the commit message should not describe (again) what the changes are but why it’s necessary. Sometimes the change is not self-explanatory and then I'd put a longer description below. Somehow I came up with this on my own, so I'd be interested if it really makes sense or if others have a similar style.
  • kelnos 3y ago
    I just don't think this is feasible, and I think you're maybe over-estimating the diff-reading skills of others. I agree that changes should be as small and self-contained as possible, but I don't think it's reasonable to expect a later diff-reader to be able to understand what the change is just by looking at it. Certainly a commit message should include the why, but it should include -- start with, really -- the what as well.
• gumby 3y ago
  That first line of the commit message is most important so that `git log` can address chesterton's fence. And IMHO in this case the committer whiffed. The key is not to put what you did in that first line, but why. Anyone interested in what can just look at the code, perhaps via a diff. So something like "nginx .conf files must be in us-ascii" Then "changed blahblah.erb to remove nonbreaking space character" Then the rest of the commit message which is quite good. Think of it as a news article: write in decreasing levels of importance and increasing levels of detail, assuming the reader could stop reading at any point.
  • nathan_phoenix 3y ago
    > Think of it as a news article: write in decreasing levels of importance and increasing levels of detail, assuming the reader could stop reading at any point. Great quote and life advice, will definitely steal this! Thanks!
  • hatsix 3y ago
    Nah, first line needs to be a summary of what you changed, so that you can find the offending commit in the first place. A news article doesn't explain WHY in the headline, it explains what. In this case, the OP's first line is spot on... if you're reading through git log, you can see that this commit likely didn't change anything functional about a test, and you should move on.
    • tux1968 3y ago
      Hard disagree. There's little reason to search the text of commit messages to find out what changed. There are many git tools to find out which commits affected parts of the code you're interested in. Whereas, trying to find that in commit messages is really inefficient and relies on reading, rather than such automated tools. The purpose of the commit message is to help our fellow humans get a higher level understanding than is available from quickly scanning the code.
      • hermitdev 3y ago
        Totally agree with you. We already know what changed: it's the diff! We need to know why you're making the what. The message should address why the diff is necessary. Was it a bug fix? Ok, what's the bug you're fixing? What's the evidence that you think they diff addresses it? Is it a new feature? What's the requirement? I can already tell what you did by the diff, but I can't tell from the diff alone if it actually matches the requirement!
• AeroNotix 3y ago
  Essentially zero people read complex commit messages. Do with this information what you will. 9/10 the code already is documentation enough for what the code currently does, if you need to go back through history then look at the commits. The messages are generally noise. I've literally never cared _why_ someone made a change, I can see the change, I can see the effect of the old and new code. Rarely, if ever, has the thought process ever changed how I will interact with the code in question. If I am at the level of debugging or history spelunking that the _commit message_ is the thing that saves me - I've already lost and there are other glaring organizational or design issues that are the actual problem.
  • advisedwang 3y ago
    > Essentially zero people read complex commit messages I don't think that's true. I worked in support doing break/fix and outage response work at a large organization. That means constantly dipping into codebases I'm utterly unfamiliar with. Often there is complexity, un-obvious elements, previous incorrect attempts at a bugfix and so on, where understanding what the author intended can save literal hours of examination, experimentation etc. > If I am at the level of debugging or history spelunking that the _commit message_ is the thing that saves me - I've already lost and there are other glaring organizational or design issues that are the actual problem. This is kind of understanding what I mean, but there was no organizational or design failing here. This is just the nature of some work, I believe.
    • AeroNotix 3y ago
      > [..] where understanding what the author intended can save literal hours of examination, experimentation etc. The problem with that it that you are relying on an inherently unreliable source of information - a human to enter details which may or may not lead you to the correct path. The code doesn't "lie". Just read it and the current issue and work from there.
      • gray_-_wolf 3y ago
        The code might not lie, but is also does not tell you why the DNS record in your IaC was changed from 1.2.3.4 to 4.3.2.1... Well written commit messages are useful. Some people use issue tracking system instead, but commit message should have the information in more concentrated form instead of spread over 50+ messages of discussion.
• eduction 3y ago
  It's true that giving a little potted history like this is "good" (other than he should have made a nice informative first line for summaries) BUT it's not super useful to say this is good, the hard part is knowing WHEN to put this much effort in and when you can skip it. I have many instances where I could do a longer story like this but it would be exhausting to do it every time. I try to do it when the commit might look unclear in intent or effect to an outsider, when the change is being made for an important reason, /and/ where this a potentially negative consequence (like naively reverting or writing bad code) if the change is not explained. I think this is a decent example of that but not great, because no one is intentionally going to go in and start introducing nonbreaking spaces.
  • cesarb 3y ago
    > BUT it's not super useful to say this is good, the hard part is knowing WHEN to put this much effort in and when you can skip it. I learned git in the context of Linux kernel development (its original use case). In that context, the commit message is where you explain, to whoever is reading, what your change does and why it should be accepted. The more subtle the change is, the longer and more detailed the explanation must be to convince a reviewer. So basically, the rule of thumb would be: pretend you're going to email your commit to another developer, who has the power to accept or reject your change, and who is not going to consider anything outside that email in their decision. The more subtle your change is, the more detailed and convincing its explanation has to be.
• krmbzds 3y ago
  I would just go with "Remove non-breaking space characters" instead of writing a Russian novel. Also, if you're on macOS just use a Karabiner rule [0] that converts all non-breaking space characters to regular space characters to prevent yourself from accidentally typing it out. [0] https://ke-complex-modifications.pqrs.org/#nonbreaking_space https://ke-complex-modifications.pqrs.org/#nonbreaking_space
  • hoherd 3y ago
    There are also pre-commit hooks to remove the character, even one listed on the pre-commit site. This type of hook has saved me on many occasions, and would have saved my coworkers if they used pre-commit. https://pre-commit.com/hooks.html https://pre-commit.com/hooks.html
• thrdbndndn 3y ago
  I'm surprised the author (of the git commit) put that much effort into the message, but did not mention what exactly that character is (its Unicode code point).
• eviks 3y ago
  The uberdetailed exploration is worthy of a blog post, those are for stories! but a commit is way too obscure a spot to put it in, so it's just a waste of effort on the writer side, but also a waste of attention of the readers, a short message describing why a change in space resolved which bug where would be more efficient
• ryandrake 3y ago
  Git commit message aside, the described debug session raises a lot of questions about the crappy tooling developers rely on. "ArgumentError: Invalid byte sequence in US-ASCII" is a terrible, hard-to-action error message. What file? What line? What byte sequence? This "let's give the user another problem to solve" style of error messages is pervasive in our tools. Also, why does the tool even require US-ASCII as input in the first place? Are we still living in 1995? Also, if only ASCII characters are allowed, why does the code editing tooling allow non-breaking spaces in source code? Is there a good reason for having such a character in this file? This problem could have been avoided if the editor could have been smarter or highlighted the "bad" character better. This developer lost an hour of his life because of a cascading chain of defective tools.
• MeteorMarc 3y ago
  When a developer admits that a single wrong character cost them one hour, it probably took 3 hours.
• OhNoNotAgain_99 3y ago
  [dead]
• gavinhoward 3y ago
  I'm about to release 1500+ commits. I hope people will be able to praise some of my commit messages like this one.
• mrinterweb 3y ago
  This is the reason I dislike automatic squashing branches with rebase. Squashing discourages thoughtful and meaningful commit messages. What is the point of making a meaningful commit message for some specific change when it is just going to all be smashed together as a single commit on merge. I feel like rebasing is something that should be intentional to clean things up by the dev, but not as a default pattern on merge.
  • notfed 3y ago
    Squashing is very useful....for local development. The idea of squashing already-pushed commits frightens me, glad I've never had to deal with it. Where are they doing this?
    • mrinterweb 3y ago
      Github and Gitlab allow merge/pull requests to automatically squash on merge. Some teams set the squash merge strategy. My team used to squash by default, but I helped convince them otherwise.
• gfiorav 3y ago
  My rule for any developer doc is: don't tell me what, tell me WHY
• fl0ki 3y ago
  A complementary virtue is that the commit is tightly scoped to exactly one change. I still see most engineers commit whatever they had in their working directory as a sort of blanket Save Point, without any thought to how those changes can be captured as individual commits that can be commented and reviewed on their own merits. This will typically also involve completely unnecessary changes, because when you're merging unrelated changes anyway, the unnecessary ones are swept up in the noise. At best they complicate rebases for other contributors, but too often they also cause outright regressions. It goes without saying that the commit messages are a write-off at this point, because even if they felt motivated to take the time to comment it clearly, the change is so messy and nebulous that it becomes hard to comment on. If their code gets reviewed it's more likely the reviewer gives up and stamps it so they no longer have to look at it. Most people still don't seem to know that `git add -p`, `git reset HEAD`, `git stash`, `git rebase --interactive`, etc. are even available. They never learn what git is capable of, so they act like version control is a bureaucratic obligation rather than the peerless superpower that it can be. The problems they cause don't end at their terminal though, because now they've made a mess of the repository for every other contributor as well.
  • kubanczyk 3y ago
    > git add -p That command is a UX monstrosity and don't ever prompt any junior to use it. Use magit, use jj, use your IDE, just not that. I agree with your overall sentiment however. I try to measure up commits in anticipation of future revert(s). A commit is a minimal change that can still (1) pass UT (2) become a sensible revert one day. That's my measuring stick.
• declan_roberts 3y ago
  Is it a trend now to write the blog post as the commit message? I must be getting old because I hate this.
• Forge36 3y ago
  Previous discussion https://news.ycombinator.com/item?id=22519632 https://news.ycombinator.com/item?id=22519632
  • dang 3y ago
    Thanks! Macroexpanded: My favourite Git commit (2019) - https://news.ycombinator.com/item?id=22519632 https://news.ycombinator.com/item?id=22519632 - March 2020 (67 comments) My Favourite Git Commit - https://news.ycombinator.com/item?id=21289827 https://news.ycombinator.com/item?id=21289827 - Oct 2019 (370 comments)
• smashah 3y ago
  Every country should have a GDS. They do great work.
• macspoofing 3y ago
  It's not a great git commit. 1) For all that text, the first line "Convert template to US-ASCII to fix error" - could be better. Maybe a couple of extra words to state what whitespace character caused the error, and what the error was. That comment plus the diff is all the context you need. 2) Honestly, everything else is kind of pointless. It doesn't hurt, but there's not a lot of value here. The author documented their journey in tracking this bug .. who cares?
  • GreenWatermelon 3y ago
    People who like to learn and improve as programmers do care. In fact, the article explains the value of all that additional stuff which implies there are those who DO care. The article even provides a link to a search result showing multiple commits from people who learned from the fix. That commit message is a treasure trove of knowledge.
    • macspoofing 3y ago
      Outside of the small caveat that his first line could be better (which is what all future engineers will read while scanning commit messages), like I said, at worst, it doesn't hurt. I like this level of detail, whether it is at the commit, PR, or ticket level. If one of my guys did this same write-up for this same problem, especially one of my junior guys, I would have patted them on the back and told them they did a great job - because you wouldn't want to discourage them from doing more of this kind of write-up in the future. But here, we can be a little bit more honest, and the truth is, that the problem he solved was trivial, so this kind of detail is overkill for that problem. Once find that the config file has unprintable non-ascii character, immediately you know most parsers would blow chunks on that - and there is only one fix - remove the problem character. So succinctly tell me the error you saw, tell me the character, and if you know tell me HOW it got in there (which is probably the most important detail that isn't in the write-up so this could be prevented in the future) - and that's enough because if in the future another engineer does a ticket/commit search for this error in our bug tracker, hopefully these details will show up immediately.
• tehnub 3y ago
  I try to write useful commit messages. Sometimes they're as expansive as this example, but not always. On GitHub, at least the way my team uses it, the PR is the more visible unit of code change. If you have a single-commit PR, GitHub will automatically make your commit message the PR description, which is nice. It does not do that if you have more than one commit, in which case I write a general overview of the changes and write "See individual commit messages for more detail" in bold.
• vonwoodson 3y ago
  My favorite git commit is "Bug fixes"
• darioush 3y ago
  In my opinion one of the most important features of a commit message is that it fits in a single line so it can be read in git log.
• hartator 3y ago
  “Fix miss-encoded white space” is clearer to me. No need for a very lengthy explanation.
• 2devnull 3y ago
  Big fan of the straussian commit message/commentary style. You read it once and think you understand, but you come back to it much later and understand it in a second, deeper way. There’s an art to this that some people seem to have. Maybe it correlates to taste.
• daitangio 3y ago
  A good commit message must explain the reason of the commit (i.e. fix nasty char dncoding issue). This commit is nice but far too long in my humble opinion (and I like to write!) The what is already in the commit diff. Explain the why, trust me.
• pawelmi 3y ago
  I would prefer to channel that energy that went into writing this lengthy description into actually fixing the toolchain to at least fail with more actionable error message.
• jiveturkey 3y ago
  love those guys at the UK digital service!
• RustyRussell 3y ago
  I was told by a recent contributor that my approach (i.e. requirement) to git messages is "unique". Apparently my Linux kernel background is showing, but all my commit messages look like the one shown here! If about existing code, the comment belongs with the code. If it's a process thing (e.g. code that is removed or didn't work), it belongs in the commit. Most importantly, while commit messages can reference issues for convenience, they MUST reproduce the critical details: GitHub is transient, git messages are not!
• dgunay 3y ago
  I put less importance on commit messages being thorough, though I do admire when people write detailed information in the body. What's more important to me is to have good commit hygiene. It's something the industry is also generally terrible at, but has slightly more immediate value. For example, if your PRs have clean, atomic commits that can stand on their own, I can "rescue" chunks of useful functionality from review hell by cherry picking them out. I do this several times a month to help my teammates burn down huge PRs or take good ideas out of doomed branches.
  • cerved 3y ago
    Agreed. I'll settle for good commit hygiene over good commit messages. It often seems a tough ask to have both
• tomcam 3y ago
  Not completely on topic (if you read TFA) but my favorite Git commit is by compiler badass and HN frequenter, where he checks in an entire C compiler to the D language repo: https://github.com/dlang/dmd/pull/12507 https://github.com/dlang/dmd/pull/12507 https://news.ycombinator.com/item?id=27102584 https://news.ycombinator.com/item?id=27102584
• simonw 3y ago
  I used to write really long, essay style commit messages like this one. Then a friend pointed out that I was effectively writing documentation and hiding it in commit messages. Instead, I switched a lot of that effort to updating actual documentation (in a docs/ folder) that was relevant to the commit - so the commit would still have the information in it, it's just it was in an actual file and not just the commit message. I also make sure my commits almost always link to an issue thread, as that's a great place to put all kinds of extra context around the commit that can be updated independently of the commit itself.
• nickm12 3y ago
  I'm not at all a fan of this commit message. The summary line is vague (what template? what error?) and then the body spends 250 words explaining all the steps it took to get to this fix. What is this, a recipe on the web? The commit message should explain the change being made, what impact it will have, and why it is being made. The audience is the developers reviewing the change or someone looking through the logs to determine why this line changed.
  • account42 3y ago
    Agreed, this isn't a good commit message at all. Yes you should write detailed commit messages but this one is just verbose without adding much useful info. We don't need to know the exact command the original developer used to figure out the problem and we defenitley don't need to see his shell prompt including host name and all.
• jeffrallen 3y ago
  This is a nice example of Neves' Law: the harder the bug is to find, the smaller the diff will be.
• merdaverse 3y ago
  I really hate that commit message. It is extremely verbose and doesn't allow you to easily understand what was done in the commit in a single sentence or paragraph. It mixes a very narrative explanation in there that is hard to skim. It is in desperate need of a clear TLDR version. If you really like the descriptive, verbose message, then the most important description should be at the top and it should gradually go into less interesting details as you read down, like in a news article.
• schnatterer 3y ago
  This post has a similar tune: How to Write a Git Commit Message / The seven rules of a great Git commit message https://cbea.ms/git-commit/#seven-rules https://cbea.ms/git-commit/#seven-rules
• eternityforest 3y ago
  It would be cool to have a tool to add this stuff to a logfile, that gets auto dumped to the next commit message. Something like a vs code command that would add to the message for the commit I'm working on.