15 ms·

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 co

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.
- schacon 3y ago
  Is it great for historical research? I feel like the format and tooling around it is uniquely _not great_ for historical research. I think it's optimized for discussions before integration, which is largely what PR descriptions and comments are largely used for now. I feel like given great commit messages, determining a story and useful history around any block of code given the Git tooling is incredibly difficult even if there are _amazing_ commit messages. Like say you are trying to determine why a 10 line function is the way that it is. You blame it. Not even with the stupid-simple GitHub UI that _I_ originally wrote, but with the more expensive CLI interface that follows renames and ignores whitespace changes, etc. Now you get a list of SHAs of commits and the first 50 chars of commit messages for each line for the last modifications, etc. How do you even stitch those messages into a useful story (in order) to tell you how that function evolved to what it is now and why?
  - cesarb 3y ago
    It might depend on which tools you're using. When I'm doing historical research for how a function evolved, I normally run "gitk" on the file, and walk through the commits; the full commit message is shown together with each diff to the file. It used to be even better in the past, when gitk showed the full commit diff, instead of the diff to just the file I passed on the command line, but "git show" on the commit hash (or another gitk which is not filtered to a path) is good enough.
  - deleted 3y ago
    [deleted]
  - lazyasciiart 3y ago
    P4V (Perforce Visual Client) is amazing for visual historical research. I haven't seen a git tool like it, but I'd love one. https://www.perforce.com/video-tutorials/vcs/using-time-lapse-view https://www.perforce.com/video-tutorials/vcs/using-time-laps...
  - somerandomqaguy 3y ago
    Tediously commit by commit. But it's often better then the alternative. Design decisions and business logic separately from the code or source control are infinitely harder to reference code against, and realistically that documentation will be lost. At least if you have the git repo then there's at least some chance to be able to git through the history of some code that's kept with the code. Especially for stuff that code cannot document and you're working with devs that seem to be firmly believe that code is self documenting. Doesn't mean that every code base needs to have amazing git commits. But code bases expected to live a long time at least give some possibility to string together a history after some work.
tcoff91 3y ago
Many editors have great git blame integration that makes these messages quite accessible. It's really easy in emacs with magit to view commit messages from git blame view. I believe vim, vscode, and jetbrains IDEs all make this simple.
- nijave 3y ago
  Yeah, a lot of these also have Github and ticket tracker (Jira, etc) integration so they'll also pull in context from those, too Most of the stuff I work on uses merge commits on Github so you can just click the PR # in the merge commit message and arrive at the PR, browse through commit messages, discussion, etc
- cerved 3y ago
  Using vim-fugitive it's :Git blame %
ep103 3y ago
I know the OP didn't mean it this way, but after reading HackerNews for the last decade or whatnot, it never ceases to surprise me how often developer complaints stem from developers just not doing their damn job. "Almost nobody ever sees it.... nobody reads anything other than the first 50 chars of the headline." On the one hand, I get it. If a tool makes something difficult, people are less likely to do it, and as engineers we want to make tools to cause people to fall into the pit of success. So, improving this part of git makes sense. On the other hand, just do your damn job. If a coworker doesn't understand a code change, because they didn't bother to read the commit message, they're a bad developer. If they didn't write a git commit message because "no one is going to read it anyway", they're a lazy engineer. These things aren't excuses, they're incompetence, and not everything needs to cater to the least competent people in our profession.
- herrkanin 3y ago
  If writing good commit messages isn't specifically defined as part of your job, why would you waste business hours writing commit messages that are beyond what is expected of you and frankly useless since nobody would ever read it anyway?
  - groestl 3y ago
    I'd do it for CYA purposes in case smt goes wrong and my commit is involved.
  - DarkNova6 3y ago
    In my company we norm the titles of MRs, give it a ticket number and squash it all. If you can’t concisely describe what you did you need to split your MR. Helps with reviewing as well as blaming.
  - erik_seaberg 3y ago
    Writing good commit messages is part of your job in the sense that no reviewer should be approving anything without them, knowing that you may or may not be available if it breaks next year at 3 AM.
mb7733 3y ago
Well, `git` is still the primary way I interact with a git repository, and `git log` shows the entire commit message by default. So I don't run into this problem. If some "modern" git frontend is only capable of displaying the first line of a commit message, then this is a problem with that tool, not git itself. (I'm also not convinced this is a limitation of all modern tooling...)
- schacon 3y ago
  I can't tell if this is engaging with trolls or not, but I can't imagine that all of your interactions with your codebase are via `git log` with no other flags. Even the with the normal Git CLI that most of us use daily, most of us use `--oneline` or whatever to simplify useful calculations and visualizations like `--graph`, etc. But we're talking here mostly about code archeology, learning about the history of a block of code, so this comment seems somewhat ridiculous in that context.
  - bee_rider 3y ago
    Is it possible that you’ve been hit by https://xkcd.com/2501/ https://xkcd.com/2501/ ? git log | less /whatever Works OK for those of us who don’t know any git flags.
    - account42 3y ago
      Why an explicit `| less`? Git already uses a pager by default.
    - fl0ki 3y ago
      The only sets of arguments I use to git log regularly: * `git log branch` because I want to cherrypick or checkout parts of another branch. * `git log --stat` because what files changed can be a big clue for what I'm looking for. * `git log -- dir1/ file1/` because I only care about commits to a certain part of the tree. Other than that, `git log` already provides so much information to /search or even `grep` through that I can't think of any other flags I use regularly, and if you don't use them regularly you forget them. The real GOAT that people are sleeping on is `git rebase --interactive` where you can go back and edit part of your branch to clean it up before rebasing or merging towards main. The cleaner the commits are, the more useful they become later for other tools like log, merge, rebase, cherry-pick, bisect, etc.
tux1968 3y ago
I never considered the idea that it was atypical, but I read full commit message text all the time. There are many different ways to drill down into a commit, and then read the entire commit once you know it's relevant. Even doing a simple git log, and then a searching for some keyword through every full commit message, can be useful.
globular-toast 3y ago
This is a failure of GitHub etc. GitHub tries to dumb things down for users because I guess it's judged they can't reason with commit histories and this is one of the consequences. The mess in especially private GitHub repos is beyond belief sometimes. The thing is there's nowhere else for such documentation to go. It's not appropriate for a code comment. But we've got a whole generation of developers now who think git is GitHub and the only purpose of git is uploading changes to GitHub. Git sucks, but it sucks a lot less than everything else. But we need to go back to basics and understand what version control is actually for.
dkarl 3y ago
> 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. This is a feature, and a crucial one. No one would include fifty lines of explanation if everyone had to see it. It would be better to throw the information away than to inflict it on everyone who was scanning through the commit history looking for a particular change. Yet it is valuable information that only makes sense in the context of that change. There is nothing in the corrected version you can connect to the issue that was fixed. It's obnoxious to include comments about errors that have been removed, like this: # where civica QueryPayments calls are taking too long # use ASCII whitespace (This is ridiculous, but not unrealistic. I've seen code comments that said things like "# removed syntax error in invocation of query generator." This is what you get from programmers trying to juice their LOC stats.) The commit message is the right place for this kind of information, but most people reading the commit messages don't care. They're scanning through looking for something else, and all they need is a few words that tell them if this is the commit they're looking for. The person who needs to see the full story is the person who is interested in this change in particular. Maybe they found it by grepping the git log for "invalid byte sequence". Maybe they found it because they're looking at all the changes in that file, because some tooling that occasional modifies that file keeps messing it up. What matters is that if they have a special interest in that change, they have a way to see whatever information they committer felt was worth preserving, and the committer has a place to put that information where only someone with a special interest will see it.
brabel 3y ago
> 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 I am terrible at git on the terminal, but with IntelliJ or emacs and magit, I can trivially find every commit ever to change a file, and easily navigate the commits to see every full commit message. It's not hard when you use a proper tool, and I have a feeling almost everyone has something like that?! Do you really try to stick with the git CLI and memorize hundreds of commands and flags?? Why?!
- schacon 3y ago
  I don't know IntelliJ well, but I would be surprised if they did the rather expensive rename following that the multiple -C invocations did. Maybe someone can inform us here? GitHub definitely does not, but that is 100% my personal fault I assume.
- DarkNova6 3y ago
  100% this
- bradjohnson 3y ago
  IME git abstractions make it easy to read and navigate standard workflows, but incredibly difficult to repair issues that arise due to divergence of some kind or another because they are so opinionated. I use git 99% in the terminal, and 1% in some git tool for visualization, but I find that a lot of people use it in the opposite way and have problems working with others that use a very slightly different workflow. You don't need to memorize hundreds of commands and flags, honestly a dozen or two gets you to expert status in most respects.
  - brabel 3y ago
    I don't have any problem at all, when some really tricky stuff needs to be done, I google for a solution and run whatever command magic I find. If you don't need to google for git commands to do uncommon things, I imagine you have a huge capacity to memorize things, good for you, but most of us don't. I do understand how git works and could use the CLI most of the time if I wanted to, but there's exactly zero reason to do so. The GUIs offered by modern tools make it much more convenient and efficient to do things correctly. You really should't commit stuff without doing a careful review of the changes first, which is terrible to do in the terminal compared with using a GUI for that, for example.
goku12 3y ago
I don't know how it's for everyone else, but I do value the body of the commits from others. It's true that I see only the subject line for most commits. But I eventually read the full body of commits I'm interested in. Honestly, it's frustrating when commit messages don't carry enough context. Sometimes that context fits in the subject line. For others, I expect an elaborate body.
- madsbuch 3y ago
  On my work I make 1-15 commits a day. If I have to spend thought cycles on the commit message, that is time that goes from other productive endeavours. I think, as the original commenter also wrote, this might be worth it in much slower paces projects that is run in another cadence / over mailing lists. I particularly think that high paced application development do not benefit from git as documentation.
  - floating-io 3y ago
    I would argue (rightly or wrongly) that there are two common truths to such a scenario: Scenario 1, you’re doing a bunch of small changes that work towards a larger purpose. They’re what I like to call “checkpoint commits”. They aren’t the whole story —- just a step along the way to whatever you’re trying to accomplish. Scenario 2, you’re coding instead of thinking. Making “random” changes until you get what you want, but because you’re continuously delivering, they all go to production. Note that “you” here might be the developer, or it might be business people demanding things from said developer. In scenario 1, IMO you should be working on a branch. Then, when you’re finished, you squash your commits and replace the countless mini-messages (“fixed”, “Oops”, “wtf?”) with the actual message you want to be there when you merge it. In scenario 2, especially if it’s driven by business, you’re probably SOL. In this instance, however, I tend to feel like people are making more work for themselves. If they stopped and thought it through for half an hour before starting work, it might only take an hour’s worth of work and one commit, instead of a day and thirty commits. Of course, there are always shades in between. :)
    - madsbuch 3y ago
js2 3y ago
As someone who has contributed to Git since before GitHub existed and who maintains legacy code, I simply cannot disagree more. I use `git blame`, `git log`, and `git show` in the terminal all the time. It's trivial to follow the history of a file. It takes me seconds to use `git log -G` to find when something was added or removed. Nothing pains me more than to track down the commit and then find a commit message that's of the form "bleh" or "add a thing" when the developer could have spent 60 second to write down why they did it. Nothing gives me more joy than to find a commit message (often my own) that explains in detail why something was done. A single good commit message can save me hours or days of work. Let me also just say, and this is a bit of shot: GitHub contributes to the problem of bad commit messages. If I'm lucky, folks have put some amount of detail in the PR description, but sadly that's not close at hand to the commit log. It's another tool I have to open. Usually though, the PR is just a link to Jira, so that's another degree of indirection I need to follow. Then the Jira is a link to a Slack conversation. And the Slack conversation probably links to a Google doc. As an industry, we're _terrible_ at documentation. But folks like Jeff King are fighting the good fight. At the end of the day, I don't think the problem is with the technology. I think it's a people problem. Folks perceive writing documentation as extra work, so they don't. There's no immediate value to it. The payoff comes days, weeks, or months later. Please, write good commit messages. Just spend a minute saying why you did something so that every commit isn't a damn Chesteron's fence exercise. Put it in the commit message where I can easily find it. Your future self and I thank you. Edit to add: I didn't address your argument, that commit messages are too hard to find. First, I don't find this to be true. I rarely have trouble following the history of a line of code, a function, or a file. Second, commit messages have value at the time they are written even if they are never seen again. I find that writing a good commit message helps ensure that I've written in code what I've intended to (I often view the diff while writing the commit message) and they have value to the people reviewing my code.
- neilkk 3y ago
  The thing is that writing a good commit message for future people doing `git blame` is only worth it if it's a line of code which someone in the future will look at and need to know why it was changed from its previous form to the current form. If you simply want to comment the current state of the code, you should add a comment in the code. No one will ever need to know in the future why that particular space character is an ascii space, so the whole commit message is just a blog entry in the wrong place. It would have made sense to just put a comment at the top of the file saying "make sure encoding is whatever".
zaptheimpaler 3y ago
I feel half vindicated about my rant a few weeks ago[1] arguing that we should make commit messages as long as we like instead of the stupid 50 character or whatever limit. If enough people do that, maybe tools like GH will stop wrapping the message by default. Even if not, atleast the first line is usually easy to see in most tools by hovering over it or something. [1] https://news.ycombinator.com/item?id=38831282 https://news.ycombinator.com/item?id=38831282
- cerved 3y ago
  Presumably you're referring to commit subjects. And no, they should absolutely not be as long as you like. It breaks things
gorkish 3y ago
Making sense of code (or any system that changes over time) vis a vis its own history is one of those things where I really think AI/ML tools can really shine. Even with relatively low quality commit messages, I can look at something that happened 15 years ago in a codebase I am familiar with, and there will probably be enough information that I can assemble the full context, even if finding some of that information is challenging or time consuming. git log, git blame, look at the other code made in the commits, read the issue descriptions, read the code reviews. It just seems like a model could slurp that up and do a decent job of giving you a couple of paragraphs about why the line of code you are staring at is the way it is. TBH putting such a detailed writeup in the git log doesn't really have any return -- for it to ever be useful to you again, you have to know the information is there; you then have to actively seek it out, with the hope that whatever you did to make it 'searchable' is going to work for you again. I can say with surety that if I were looking at a bug similar to the one linked from this article, I would not look to the git log for inpsiring a fix; I'd just fix it. Any extra time I would take would be to understand how a UTF8 nbsp ended up where it shouldn't have been in the first place -- something that the author of this commit seemed to have no interest in doing, but which likely has greater relevance than the documentation of the fix. I want to be clear that I support commit messages that say what they do though; I'm not advocating for -m 'fixed' shenanigans, however at the same time I believe that -m 'fixes #1234' is often enough
OhNoNotAgain_99 3y ago
[dead]
keybored 3y ago
I’m surprised that you (in particular) would say this. git-log is, to me, fine for displaying the whole message (not just the subject). And sure, I often fiddle with copy-pasting SHA1s like a caveman, but it’s fast enough for some quick history spelunking. Finding the history of a particular code change is even more manual for me: maybe doing a chain of `git log -S'line'` where `line` copy-pasted in at every step. But doable and not a time-sink for my off-hand what’s-this thoughts. (But: something more convenient that isn’t an unreadable Unix pipeline one-liner would be very nice.) My litmus test is simple and doesn’t involve hallucinating that other people are even reading my messages: am I reading my own past commit messages? Yes. I am curious why I did or didn’t do something on a daily basis(!)
ManuelKiessling 3y ago
I agree for the use case of scrolling through a git history, yes, but when I land at a certain commit, e.g. by hitting the blame label in IntelliJ on a line whise reason d‘change I‘m interested in, then I will totally read the whole commit message in the hope that it helps me understand the change (in addition to looking and trying-to-understand the change itself).
lisper 3y ago
> The main issue is that most of the tooling ... generally only shows the first line. > I don't know exactly what the answer is Isn't it obvious? Write better tools. There is no reason you have to be stuck with the deficiencies of what someone else has built. That's the whole point of open-source software. It's more than a little concerning that a "GitHub cofounder and author of several Git books" has to have this pointed out to them.
- ParetoOptimal 3y ago
  >There is no reason you have to be stuck with the deficiencies of what someone else has built. There is a concerning trend of "we only use vscode" and popular preference shifting to "adjust to popular tool" rather than "use best tool". This means sadly things like GitHub start to define git even more for your coworkers.
caskstrength 3y ago
> 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. The good way to browse git blame a read commit messages is to use Magit. It is also great at letting you seamlessly rebase/split/merge long patch series.
zellyn 3y ago
If you follow a pull-request based workflow, and if you typically squash down to one commit, then finding these messages isn't too bad, since the commit description pre-populates into the pull request description. I often track changes down not to their commit, but to their pull request. Granted, that's not exactly `git`, but rather `github`…
nightfly 3y ago
git log. git blame, grab hash, git log hash. You make it sound like some arcane magic...
kelnos 3y ago
While this may be how most people interact with git, I couldn't disagree more when it comes to my personal use. I use 'git blame' (I've never needed to pass any options to it) and 'git show' liberally if I'm trying to understand a change that was made, and if the committer took the time to write a commit message body, of course I'll see it and read it. > ... 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. I think people don't care much about good commit messages because they are unprofessional and sloppy. They just want to get the commit in, push the PR/MR, get it reviewed and merged, close that Jira ticket, and get credit for those sweet sweet story points (ugh). And on top of that, they generally don't care to document their changes because they personally don't see the value of doing so. Surely they'll remember the change if they ever revisit it (no of course not, but many people think they will), and they don't really give much thought to the possibility that others might need more context. And besides, all the discussion about the bug or feature or whatever was happening in the bug tracker, so providing a link to that issue in the commit message is enough, right? (No, it's not; I hate it when people do that and think that's all they need to do.) > The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. Then maybe this is GitHub's fault; fix your web UI, then. I avoid GUI interfaces to my dev tools as much as possible, and I think the git command line is perfectly fine for this. It absolutely does not only show the first line, generally. 'git log', 'git show', etc. give you the full message by default. In general I would say you have to go out of your way (by providing more command line options) to hide the message when using the command line tools. > the Git commit message is a unique vector for code documentation that is highly sub-optimal. Sure, because it's not a vector for code documentation, it's a vector for change documentation. And there's no better place to put the description of a change than in the record of the change happening. While I agree that many people write very poor commit messages, I don't think the tooling and discoverability is why.
jeremyw 3y ago
I take Scott's point with a difference perspective. Though commit messages are ephemeral and hard to utilize in the future, they're the stream of consciousness of the project. They convey very important shifts in direction, discoveries in the making, code smells, limits of current architecture, and markers of tech debt. We don't know what this beast will be. And we figure it out commit by commit. Document it.
- yencabulator 3y ago
  Commit messages are the very opposite of ephemeral; they are the longest-lasting history a project is likely to have!
  - jeremyw 3y ago
    Yes, I misworded. The usefulness of commit messages, Scott's point.
deleted 3y ago
[deleted]
jakub_g 3y ago
In my experience it all depends on what kind of codebase it is (product? library/framework? private company? opensource?), commit velocity, release cadence & how the codebase is used in general. In low-velocity opensource libraries, good and clean commit messages can be really helpful when debugging arcane issues. I used to be maintainer of a frontend framework & widget library and we tried to have good commit messages as we'd often go back when over old commits when fixing bugs. I agree that using git from command line for blame is not easy, this is something I always do from GitHub UI instead. When GitHub is the repo's choice for PRs, and the codebase is product codebase with high velocity, having a pristine git history and clean commits and commit messages is not practical; however, the expectation should be to at least have good PR descriptions. When blaming commits in GH UI, it's easy to go to the PR which introduced the commit (it's linked below commit title); and PR descriptions can be enforced via templates in .github folder. PR descriptions have an advantage that they can use images, videos etc. to better explain what they change. This is especially useful for frontend codebases. I work on a big frontend monorepo. We have tools in place to do visual bisect between pull requests (each PR gets its own preview env). We very much do read PR descriptions when doing bisect to confirm which of the recently merged dozens of PRs introduced a regression in production N hours ago. But in general I agree that commit messages are not good place to storage general knowledge (they're good for "what and why is changing here"). For documenting gotchas etc. I prefer to have code comments in relevant places of code; or README.md in subfolders. (Sadly, I notice most programmers just don't document anything anywhere at all).
b33j0r 3y ago
Author of nit, here. I tried to move the landscape towards semantic reasoning. It’s on github but kind of abandonware. Life and incompetency happened ;) No shilling. I commented here because I still think my framework was decently thought out, and mostly that calling someone a nit or a git is exactly what linus was thinking. Make it easy enough for anyone to use. Nit is something people could take as a thought experiment.
twosdai 3y ago
Completely agree, the value with the message is really just to link an external ticket Id, the user experience is much better in external ticketing systems for all of the story telling that the article loves. Don't read "external ticket system" as closed either, plenty systems are open to the public.
- cerved 3y ago
  Right. The massive commit with minimal description and a PR number which I can look up in Azure DevOps to find a review with no description, no discussion and a mention of a number I can go and look up in Jira, where some Scrum master wrote half a sentence of what needs to be done and asking to "reach out to Jeff" for explanation. So much more valuable and great user experience
  - yencabulator 3y ago
    Just wait till next year when your employer migrates away from Azure DevOps and that PR number will be a dangling link forever lost.
    - cerved 3y ago
      Or you just move the repository to a different protect
6510 3y ago
Just do a threaded conversation in a comment at the top of each file. Add your name and the date.
krobelus 3y ago
> 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. I find this very hard to believe. Isn't it "everyone who is interested in the commit subject/files touched should read the body". Why would anyone else read immutable historical documentation? > 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 sounds like you are joking. Any good IDE will be able to annotate each line with blame info, and show the diff at the press of a button. On such diffs, the IDE should allow recursive blaming on context/deleted lines. Tools like Tig allow exactly that. GitHub certainly does make it hard to see commit messages, I give you that :) > Hundreds of hours of amazing documentation from a true genius that almost nobody will ever appreciate. It's horrifying. ?? It's not like it was written for fun. This documentation attached to a commit exists to reduce the risk of accepting the patch from someone who might not be around in future, to fix any problems introduced. By disclosing all their relevant thoughts, the author shows their good intentions: they enable others to build on top of their work. If the author kept their thoughts to themselves they would gradually build up exclusive ownership of the code, which is often not a good idea. Also a commit message serves as proof of work, which can be important when there's too many patches. For commercial projects some of this is less important.
- makeitdouble 3y ago
  I might be in the minority, but parent's comment is probably about people like me: most of my coworkers have context free, or at best succinct commit messages. I never read more than the first line listed in the commit list, and don't even assume the description is always accurate. Instead I'll spend my time stalking the related merge request, where the full description of the whole change resides, with probably a link to the ticket or reference documentation, and all the back and forth on why something is or isn't a good idea. I think the world could be a better place if all of that was in git directly, but that's also utting much more burden on an already complex tool.
tibbar 3y ago
In practice, I think GitHub/GitLab/etc solve this UX problem pretty well. Inline git tools let you jump immediately to the PR that generated the code change, and the PR description + code reviews + snapshot of the commit help to understand what the point of the change was. You can search the PRs when you want to find some context. (It's unfortunate that PRs are not stored in the repository itself. I mean, Git is not a great database for a multi-user webpage, so this wouldn't quite work... but it would be nice if the archive was durable and easy to export/share.)
sohamssd 3y ago
Your entire argument boils down to the fact that it's hard to view git blames. It's not. As stated by other people, IDEs like VSCode and IntelliJ do an extremely good job of showing the blame. And they DO show the entire commit, body and everything at once.
da_chicken 3y ago
> The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. This has been an issue with version control tooling for quite a long time. I'm fairly certain both CVS and SVN did the same thing. But I agree that you're still right. I'm also very amused by the number of replies to your comment along the lines of, "oh, it's actually very easy because I always use <third party tool>". Which is, of course, rather proving the point.
- dragonwriter 3y ago
  No, because the point is about common tooling, and the common tooling does not, actually, make this difficult.
  - da_chicken 3y ago
    That's rather a matter of opinion. One that I and GP both clearly disagree with. Insisting it's easy doesn't mean everyone will agree with you.
palata 3y ago
> The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. Maybe I do it wrong, but the most basic interface I use to check the git history is `git log`, which shows the whole commit message. GitHub takes me 18 clicks to find the commits, I don't see why I would even bother using it.
- ParetoOptimal 3y ago
  Many engineers primarily or even exclusively use git via githubs interface and have never made a commit with a body.
  - cerved 3y ago
    Those "engineers" go on _The List_
  - palata 3y ago
    Right, but then maybe the main issue is those engineers, and not the tooling? When I see someone using a hammer the wrong way, I don't usually blame the hammer.
    - ParetoOptimal 3y ago
      The problem is the network effects. If enough people start hammering with the side to pull out nails, like 95%, there's a chance that could become known as "the right way". I think a lot of the "get shit done" crowd for instance sees using Github and not "futzing around with git" as the right way to do things for getting shit done.
      - palata 3y ago
        Sure, but because "the majority thinks it is the right way" does not mean it is. My point is that when the majority of people don't know how the most basic tool they use is meant to be used, then it is a problem. It would still be better to say "I know how a hammer is meant to be used, but I choose to use it this other way", but that is not the situation right now. The situation right now is that more and more devs don't know that git != GitHub. And that inequality is an objective fact, it has nothing to do with network effects. Everybody believing that the Earth is flat would not make it flat.
djha-skin 3y ago
This sounds like an excellent sales pitch to use email based good workflows such as those advocated for by Drew DeVault[1]. 1: https://git-send-email.io/ https://git-send-email.io/
heads 3y ago
To tack one additional problem onto your excellent list: the commit message is usually only the start of a conversation about why a change should be made. The rest of that discussion is whether it meets the bar and what needs to be adjusted before it can land on the collaborative trunk. Done well, that is valuable reading. Git was designed with the distributed viewpoint. A commit message, as written by the author, is necessarily correct: I’ve decided this is right, and it’s on you to decide if you want to merge it into your history too. In our current systems we usually have a URL in the commit message that links to the actual story behind the commit — the discussion on the pull request, merge request, or code review. I rarely see the results of these discussions being amended into the commit message. If the repo lives forever but the database behind the code review tool gets toasted then something just as important is lost forever. (I come from a background of one idea equals one amended, fast forwarded commit to master. It’s possible other people rely on branch history to reflect the evolution of ideas and how they go from a request for review to approved code. In my experience branch histories tend to have very low quality commit messages and even then they only show one side of the conversation — the author’s responses to their reviewer’s and their own critiques.)
phaedrus 3y ago
So then I am not wrong that I do all my git commit messages via the "-m" commandline option with a short phrase like "frob the baz"? (Initially I started using -m to avoid getting trapped in Vim. But even after I gained the option to use e.g. Notepad++ as the editor, I never saw the point in using anything more than "-m 'message'".)
- kimixa 3y ago
  Git respects the EDITOR environment variable and has done for decades (so likely before many here really used it) - you should probably be setting that (or equivalent on your platform) to the editor you want anyway. Weird workaround just to avoid basic configuration seems like more work in the long run.
colelyman 3y ago
One tool that I think promotes commit messages like the OP is magit in Emacs. Before using magit, I always used `git commit -m '...'` and didn't realize that commit messages could be longer than a line. I agree that this is a tooling problem, but magit is a breath of fresh air in many ways (including verbose commit messages).
- nequo 3y ago
  What I like about magit is that it shows me the diff of the would-be commit when I write the commit message. And also that I can pick which sections of the diff to a file I want to include in the commit. I used Vim + git CLI before and this was much less convenient. (I never tried fugitive though. It might be similarly great on these two features.)
lambda 3y ago
It's amazing, your experience with Git is so different than my own. I routinely open a file in my editor, hit "Ctrl-c v B" for Git Blame mode, go to the line I'm interested in, and hit "Enter". Bam, there's the full commit message. From there I can can continue to trace backwards, blaming lines and reading full commit messages. But, you know, not everyone uses Emacs and Magit, fair. How about just using "git gui blame file"? Click on a blame line, see the full commit message. This is a tool included with Git (available in a separate package in some installations). OK, rather use an IDE? Install GitLens in VSCode. Easily accessible blame in your editor, where you can hover or click in various places to see full commit messages. I mean, I agree in part; there are some tools which make good commit messages hard to write or find. The tiny little commit message edit box in VScode is not ideal. Lots of people use a workflow of "commit lots of crappy commits with one liner commit messages, let GitHub/GitLab squash them on merge." But as an expert Git user who has managed to convince some teams to have a good commit message culture, if you do get people used to writing good commit messages, they can be very easy to find and read later on, there are tons of tools that make them easy to browse.
- kimixa 3y ago
  I regularly use the git command line, and "git show (pasted SHA)" in my second terminal doesn't really feel like the road block to understanding the grandparent seems to make it out to be. It takes me many orders of magnitude more time understanding what is output rather than searching for it, and like you mentioned there are any number of UIs (third party, editor integration, or even shipped with git like gitk) that wire everything up into a nice UI. And I also disagree with the GP's complaint that "Most people only read the shortlog" being any kind of disadvantage. The commit message isn't for everyone, it's for the one time someone needs to figure out exactly what it did and why that commit was made, and why a change in X causes a behavior change in Y, and can save hours of work. It's like code comments, 99 times out of 100 you don't need them as you're just interacting with a documented API, but that 1 other time they are a godsend.
adityaathalye 3y ago
> 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. I completely agree that well-written git log messages are goldmines of information. I wish makers of popular git forges had made it easier to create and consume this information. Almost all my wiki pages start with piping git log messages into a text file. Git logs are the entry point to good project documentation. (edit: fix formatting)
Groxx 3y ago
I feel like this explains a lot about why GitHub is so consistently hostile towards showing or writing decent commit messages. Which has helped push people away from writing useful ones, on an unprecedented scale, which makes it a self-fulfilling prophecy. Great. Just great.
gloosx 3y ago
I use fugitive.vim, and blaming is very convenient there as well as every other git workflow. I can press a shortcut to see when every line in the current file was changed, and who changed it along with the commit hash. If I need more – I can expand every hash to see the full context, including full commit text and diff. Maybe cli git is not too easy to use since how complex it is, but there exists a git wrapper so awesome it should be illegal
schacon 3y ago
To be clear from reading some of the other comments, I don't work at GitHub anymore so while I may have partially caused the issues I'm complaining about, I don't have the ability to fix them anymore. Also, while most GUIs and editors have blame capability (as does GitHub actually), most of them don't ignore whitespace changes (-w), code movement or renames (the -C options) so they're often of limited use. Finally, I _would_ like people to write good commit messages, I just would like to see a tool that actually uses that work in a way that helps document your code in an easy and valuable way, and the Git/Hub tooling makes that process at best "tedious" as someone in the thread says. I am working on a new Git client called GitButler[1] and would like to address this at some point down the line, so maybe it ends up being me who helps fix this after all :) 1: https://gitbutler.com https://gitbutler.com
lawtalkinghuman 3y ago
The reason people (myself included) rather like good Git commit messages is evident when one compares them to the alternative. You're working in a commercial/closed source environment and want to find out why line 57 in src/blah/db/utils.py does that. Where do you look? - inline code comments. Usually non-existent. Often out-of-date, sometimes misleading, frequently tells you no more than you can discern from just reading the code itself (especially now type annotations are trendy again). Rarely explains why the code exists. There's a reason people caution against too many comments, and that translates into people probably not putting enough commentsin. - calling code? Helpful, but thanks to microservices and increased levels of abstraction (APIs, DI frameworks, messaging buses, config parsing) you've got to go check 900 different repos out to work out what is going on. - email? Give up. You'll find invitations to the company Christmas party and Q2 sales figures but actual tech explanations are in short supply. - Slack etc - same problems as email, plus developers who hide away all the interesting stuff in private team channels - Google Docs - you probably don't have access to the relevant doc, and there's no way to know that you don't - wiki/docs? Half baked, wrong etc. Or it'll be autogenerated JavaDoc type stuff that'll tell you what you already know or can reasonably infer from the code. Also, findability sucks. Or the developers just avoid the whole thing because the software is nasty and corporate and barely usuable. - bug tracker/ticketing system? You ask around and someone says "oh yeah, Dave made that change two years ago" and then you search for tickets that match related keywords only to find out that those tickets weren't brought over from Trello into JIRA, and now you need to go ask IT to give you access to the legacy Trello board which they don't want to do because then it'll put them over the five users per month limit or whatever. - Architecture Decision Records / decision logs / whatever you want to to call them - nice if they exist, I guess. - ask the person who wrote it? This assumes they still work there and can remember. Plus you gotta do the asking around routine which takes days and destroys all hope and joy in the world. By a process of elimination, commit messages are the closest you're going to get. They're right there - on your computer, neatly integrated into your editor, hopefully. You can search them fast in a terminal window rather than in some slow web-based monstrosity. If you're lucky, they're actually useful. Even if they aren't, they're at least contextually useful in helping you narrow down your search strategy for the inevitable plunge through email/slack/JIRA/Trello/internal wiki etc. Ideally what should happen is the really useful commit messages get copied into stable technical documentation like decision logs or a properly maintaned wiki. If people did that, great, but it's pretty rare. A culture of sharing weird interesting tech things in a Slack-type system can help because future devs can at least search but you do that at the cost of more interruptions for colleagues now. The broader issue is of all the bad options you can choose, it often tracks the wrong thing. In something like Trello/JIRA/whatever, if you're looking for the technical reasons, it'll have the business reasons without the technical stuff, or vice versa. You generally want both, and most systems only give you half the story.
lucioperca 3y ago
Of course Emacs has a mode for it: https://github.com/redguardtoo/vc-msg https://github.com/redguardtoo/vc-msg
deleted 3y ago
[deleted]
FrederickZh 3y ago
> 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. This was why I created gh-ph [1]. [1] https://github.com/Frederick888/gh-ph https://github.com/Frederick888/gh-ph

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.

schacon 3y ago
Is it great for historical research? I feel like the format and tooling around it is uniquely _not great_ for historical research. I think it's optimized for discussions before integration, which is largely what PR descriptions and comments are largely used for now. I feel like given great commit messages, determining a story and useful history around any block of code given the Git tooling is incredibly difficult even if there are _amazing_ commit messages. Like say you are trying to determine why a 10 line function is the way that it is. You blame it. Not even with the stupid-simple GitHub UI that _I_ originally wrote, but with the more expensive CLI interface that follows renames and ignores whitespace changes, etc. Now you get a list of SHAs of commits and the first 50 chars of commit messages for each line for the last modifications, etc. How do you even stitch those messages into a useful story (in order) to tell you how that function evolved to what it is now and why?
- cesarb 3y ago
  It might depend on which tools you're using. When I'm doing historical research for how a function evolved, I normally run "gitk" on the file, and walk through the commits; the full commit message is shown together with each diff to the file. It used to be even better in the past, when gitk showed the full commit diff, instead of the diff to just the file I passed on the command line, but "git show" on the commit hash (or another gitk which is not filtered to a path) is good enough.
- deleted 3y ago
  [deleted]
- lazyasciiart 3y ago
  P4V (Perforce Visual Client) is amazing for visual historical research. I haven't seen a git tool like it, but I'd love one. https://www.perforce.com/video-tutorials/vcs/using-time-lapse-view https://www.perforce.com/video-tutorials/vcs/using-time-laps...
- somerandomqaguy 3y ago
  Tediously commit by commit. But it's often better then the alternative. Design decisions and business logic separately from the code or source control are infinitely harder to reference code against, and realistically that documentation will be lost. At least if you have the git repo then there's at least some chance to be able to git through the history of some code that's kept with the code. Especially for stuff that code cannot document and you're working with devs that seem to be firmly believe that code is self documenting. Doesn't mean that every code base needs to have amazing git commits. But code bases expected to live a long time at least give some possibility to string together a history after some work.

tcoff91 3y ago

Many editors have great git blame integration that makes these messages quite accessible. It's really easy in emacs with magit to view commit messages from git blame view. I believe vim, vscode, and jetbrains IDEs all make this simple.

nijave 3y ago
Yeah, a lot of these also have Github and ticket tracker (Jira, etc) integration so they'll also pull in context from those, too Most of the stuff I work on uses merge commits on Github so you can just click the PR # in the merge commit message and arrive at the PR, browse through commit messages, discussion, etc
cerved 3y ago
Using vim-fugitive it's :Git blame %

ep103 3y ago

I know the OP didn't mean it this way, but after reading HackerNews for the last decade or whatnot, it never ceases to surprise me how often developer complaints stem from developers just not doing their damn job. "Almost nobody ever sees it.... nobody reads anything other than the first 50 chars of the headline." On the one hand, I get it. If a tool makes something difficult, people are less likely to do it, and as engineers we want to make tools to cause people to fall into the pit of success. So, improving this part of git makes sense. On the other hand, just do your damn job. If a coworker doesn't understand a code change, because they didn't bother to read the commit message, they're a bad developer. If they didn't write a git commit message because "no one is going to read it anyway", they're a lazy engineer. These things aren't excuses, they're incompetence, and not everything needs to cater to the least competent people in our profession.

herrkanin 3y ago
If writing good commit messages isn't specifically defined as part of your job, why would you waste business hours writing commit messages that are beyond what is expected of you and frankly useless since nobody would ever read it anyway?
- groestl 3y ago
  I'd do it for CYA purposes in case smt goes wrong and my commit is involved.
- DarkNova6 3y ago
  In my company we norm the titles of MRs, give it a ticket number and squash it all. If you can’t concisely describe what you did you need to split your MR. Helps with reviewing as well as blaming.
- erik_seaberg 3y ago
  Writing good commit messages is part of your job in the sense that no reviewer should be approving anything without them, knowing that you may or may not be available if it breaks next year at 3 AM.

mb7733 3y ago

Well, `git` is still the primary way I interact with a git repository, and `git log` shows the entire commit message by default. So I don't run into this problem. If some "modern" git frontend is only capable of displaying the first line of a commit message, then this is a problem with that tool, not git itself. (I'm also not convinced this is a limitation of all modern tooling...)

schacon 3y ago
I can't tell if this is engaging with trolls or not, but I can't imagine that all of your interactions with your codebase are via `git log` with no other flags. Even the with the normal Git CLI that most of us use daily, most of us use `--oneline` or whatever to simplify useful calculations and visualizations like `--graph`, etc. But we're talking here mostly about code archeology, learning about the history of a block of code, so this comment seems somewhat ridiculous in that context.
- bee_rider 3y ago
  Is it possible that you’ve been hit by https://xkcd.com/2501/ https://xkcd.com/2501/ ? git log | less /whatever Works OK for those of us who don’t know any git flags.
  - account42 3y ago
    Why an explicit `| less`? Git already uses a pager by default.
  - fl0ki 3y ago
    The only sets of arguments I use to git log regularly: * `git log branch` because I want to cherrypick or checkout parts of another branch. * `git log --stat` because what files changed can be a big clue for what I'm looking for. * `git log -- dir1/ file1/` because I only care about commits to a certain part of the tree. Other than that, `git log` already provides so much information to /search or even `grep` through that I can't think of any other flags I use regularly, and if you don't use them regularly you forget them. The real GOAT that people are sleeping on is `git rebase --interactive` where you can go back and edit part of your branch to clean it up before rebasing or merging towards main. The cleaner the commits are, the more useful they become later for other tools like log, merge, rebase, cherry-pick, bisect, etc.

tux1968 3y ago

I never considered the idea that it was atypical, but I read full commit message text all the time. There are many different ways to drill down into a commit, and then read the entire commit once you know it's relevant. Even doing a simple git log, and then a searching for some keyword through every full commit message, can be useful.

globular-toast 3y ago

This is a failure of GitHub etc. GitHub tries to dumb things down for users because I guess it's judged they can't reason with commit histories and this is one of the consequences. The mess in especially private GitHub repos is beyond belief sometimes. The thing is there's nowhere else for such documentation to go. It's not appropriate for a code comment. But we've got a whole generation of developers now who think git is GitHub and the only purpose of git is uploading changes to GitHub. Git sucks, but it sucks a lot less than everything else. But we need to go back to basics and understand what version control is actually for.

dkarl 3y ago

> 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. This is a feature, and a crucial one. No one would include fifty lines of explanation if everyone had to see it. It would be better to throw the information away than to inflict it on everyone who was scanning through the commit history looking for a particular change. Yet it is valuable information that only makes sense in the context of that change. There is nothing in the corrected version you can connect to the issue that was fixed. It's obnoxious to include comments about errors that have been removed, like this: # where civica QueryPayments calls are taking too long # use ASCII whitespace (This is ridiculous, but not unrealistic. I've seen code comments that said things like "# removed syntax error in invocation of query generator." This is what you get from programmers trying to juice their LOC stats.) The commit message is the right place for this kind of information, but most people reading the commit messages don't care. They're scanning through looking for something else, and all they need is a few words that tell them if this is the commit they're looking for. The person who needs to see the full story is the person who is interested in this change in particular. Maybe they found it by grepping the git log for "invalid byte sequence". Maybe they found it because they're looking at all the changes in that file, because some tooling that occasional modifies that file keeps messing it up. What matters is that if they have a special interest in that change, they have a way to see whatever information they committer felt was worth preserving, and the committer has a place to put that information where only someone with a special interest will see it.

brabel 3y ago

> 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 I am terrible at git on the terminal, but with IntelliJ or emacs and magit, I can trivially find every commit ever to change a file, and easily navigate the commits to see every full commit message. It's not hard when you use a proper tool, and I have a feeling almost everyone has something like that?! Do you really try to stick with the git CLI and memorize hundreds of commands and flags?? Why?!

schacon 3y ago
I don't know IntelliJ well, but I would be surprised if they did the rather expensive rename following that the multiple -C invocations did. Maybe someone can inform us here? GitHub definitely does not, but that is 100% my personal fault I assume.
DarkNova6 3y ago
100% this
bradjohnson 3y ago
IME git abstractions make it easy to read and navigate standard workflows, but incredibly difficult to repair issues that arise due to divergence of some kind or another because they are so opinionated. I use git 99% in the terminal, and 1% in some git tool for visualization, but I find that a lot of people use it in the opposite way and have problems working with others that use a very slightly different workflow. You don't need to memorize hundreds of commands and flags, honestly a dozen or two gets you to expert status in most respects.
- brabel 3y ago
  I don't have any problem at all, when some really tricky stuff needs to be done, I google for a solution and run whatever command magic I find. If you don't need to google for git commands to do uncommon things, I imagine you have a huge capacity to memorize things, good for you, but most of us don't. I do understand how git works and could use the CLI most of the time if I wanted to, but there's exactly zero reason to do so. The GUIs offered by modern tools make it much more convenient and efficient to do things correctly. You really should't commit stuff without doing a careful review of the changes first, which is terrible to do in the terminal compared with using a GUI for that, for example.

goku12 3y ago

I don't know how it's for everyone else, but I do value the body of the commits from others. It's true that I see only the subject line for most commits. But I eventually read the full body of commits I'm interested in. Honestly, it's frustrating when commit messages don't carry enough context. Sometimes that context fits in the subject line. For others, I expect an elaborate body.

madsbuch 3y ago
On my work I make 1-15 commits a day. If I have to spend thought cycles on the commit message, that is time that goes from other productive endeavours. I think, as the original commenter also wrote, this might be worth it in much slower paces projects that is run in another cadence / over mailing lists. I particularly think that high paced application development do not benefit from git as documentation.
- floating-io 3y ago
  I would argue (rightly or wrongly) that there are two common truths to such a scenario: Scenario 1, you’re doing a bunch of small changes that work towards a larger purpose. They’re what I like to call “checkpoint commits”. They aren’t the whole story —- just a step along the way to whatever you’re trying to accomplish. Scenario 2, you’re coding instead of thinking. Making “random” changes until you get what you want, but because you’re continuously delivering, they all go to production. Note that “you” here might be the developer, or it might be business people demanding things from said developer. In scenario 1, IMO you should be working on a branch. Then, when you’re finished, you squash your commits and replace the countless mini-messages (“fixed”, “Oops”, “wtf?”) with the actual message you want to be there when you merge it. In scenario 2, especially if it’s driven by business, you’re probably SOL. In this instance, however, I tend to feel like people are making more work for themselves. If they stopped and thought it through for half an hour before starting work, it might only take an hour’s worth of work and one commit, instead of a day and thirty commits. Of course, there are always shades in between. :)
  - madsbuch 3y ago

js2 3y ago

As someone who has contributed to Git since before GitHub existed and who maintains legacy code, I simply cannot disagree more. I use `git blame`, `git log`, and `git show` in the terminal all the time. It's trivial to follow the history of a file. It takes me seconds to use `git log -G` to find when something was added or removed. Nothing pains me more than to track down the commit and then find a commit message that's of the form "bleh" or "add a thing" when the developer could have spent 60 second to write down why they did it. Nothing gives me more joy than to find a commit message (often my own) that explains in detail why something was done. A single good commit message can save me hours or days of work. Let me also just say, and this is a bit of shot: GitHub contributes to the problem of bad commit messages. If I'm lucky, folks have put some amount of detail in the PR description, but sadly that's not close at hand to the commit log. It's another tool I have to open. Usually though, the PR is just a link to Jira, so that's another degree of indirection I need to follow. Then the Jira is a link to a Slack conversation. And the Slack conversation probably links to a Google doc. As an industry, we're _terrible_ at documentation. But folks like Jeff King are fighting the good fight. At the end of the day, I don't think the problem is with the technology. I think it's a people problem. Folks perceive writing documentation as extra work, so they don't. There's no immediate value to it. The payoff comes days, weeks, or months later. Please, write good commit messages. Just spend a minute saying why you did something so that every commit isn't a damn Chesteron's fence exercise. Put it in the commit message where I can easily find it. Your future self and I thank you. Edit to add: I didn't address your argument, that commit messages are too hard to find. First, I don't find this to be true. I rarely have trouble following the history of a line of code, a function, or a file. Second, commit messages have value at the time they are written even if they are never seen again. I find that writing a good commit message helps ensure that I've written in code what I've intended to (I often view the diff while writing the commit message) and they have value to the people reviewing my code.

neilkk 3y ago
The thing is that writing a good commit message for future people doing `git blame` is only worth it if it's a line of code which someone in the future will look at and need to know why it was changed from its previous form to the current form. If you simply want to comment the current state of the code, you should add a comment in the code. No one will ever need to know in the future why that particular space character is an ascii space, so the whole commit message is just a blog entry in the wrong place. It would have made sense to just put a comment at the top of the file saying "make sure encoding is whatever".

zaptheimpaler 3y ago

I feel half vindicated about my rant a few weeks ago[1] arguing that we should make commit messages as long as we like instead of the stupid 50 character or whatever limit. If enough people do that, maybe tools like GH will stop wrapping the message by default. Even if not, atleast the first line is usually easy to see in most tools by hovering over it or something. [1] https://news.ycombinator.com/item?id=38831282 https://news.ycombinator.com/item?id=38831282

cerved 3y ago
Presumably you're referring to commit subjects. And no, they should absolutely not be as long as you like. It breaks things

gorkish 3y ago

Making sense of code (or any system that changes over time) vis a vis its own history is one of those things where I really think AI/ML tools can really shine. Even with relatively low quality commit messages, I can look at something that happened 15 years ago in a codebase I am familiar with, and there will probably be enough information that I can assemble the full context, even if finding some of that information is challenging or time consuming. git log, git blame, look at the other code made in the commits, read the issue descriptions, read the code reviews. It just seems like a model could slurp that up and do a decent job of giving you a couple of paragraphs about why the line of code you are staring at is the way it is. TBH putting such a detailed writeup in the git log doesn't really have any return -- for it to ever be useful to you again, you have to know the information is there; you then have to actively seek it out, with the hope that whatever you did to make it 'searchable' is going to work for you again. I can say with surety that if I were looking at a bug similar to the one linked from this article, I would not look to the git log for inpsiring a fix; I'd just fix it. Any extra time I would take would be to understand how a UTF8 nbsp ended up where it shouldn't have been in the first place -- something that the author of this commit seemed to have no interest in doing, but which likely has greater relevance than the documentation of the fix. I want to be clear that I support commit messages that say what they do though; I'm not advocating for -m 'fixed' shenanigans, however at the same time I believe that -m 'fixes #1234' is often enough

OhNoNotAgain_99 3y ago

[dead]

keybored 3y ago

I’m surprised that you (in particular) would say this. git-log is, to me, fine for displaying the whole message (not just the subject). And sure, I often fiddle with copy-pasting SHA1s like a caveman, but it’s fast enough for some quick history spelunking. Finding the history of a particular code change is even more manual for me: maybe doing a chain of `git log -S'line'` where `line` copy-pasted in at every step. But doable and not a time-sink for my off-hand what’s-this thoughts. (But: something more convenient that isn’t an unreadable Unix pipeline one-liner would be very nice.) My litmus test is simple and doesn’t involve hallucinating that other people are even reading my messages: am I reading my own past commit messages? Yes. I am curious why I did or didn’t do something on a daily basis(!)

ManuelKiessling 3y ago

I agree for the use case of scrolling through a git history, yes, but when I land at a certain commit, e.g. by hitting the blame label in IntelliJ on a line whise reason d‘change I‘m interested in, then I will totally read the whole commit message in the hope that it helps me understand the change (in addition to looking and trying-to-understand the change itself).

lisper 3y ago

> The main issue is that most of the tooling ... generally only shows the first line. > I don't know exactly what the answer is Isn't it obvious? Write better tools. There is no reason you have to be stuck with the deficiencies of what someone else has built. That's the whole point of open-source software. It's more than a little concerning that a "GitHub cofounder and author of several Git books" has to have this pointed out to them.

ParetoOptimal 3y ago
>There is no reason you have to be stuck with the deficiencies of what someone else has built. There is a concerning trend of "we only use vscode" and popular preference shifting to "adjust to popular tool" rather than "use best tool". This means sadly things like GitHub start to define git even more for your coworkers.

caskstrength 3y ago

> 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. The good way to browse git blame a read commit messages is to use Magit. It is also great at letting you seamlessly rebase/split/merge long patch series.

zellyn 3y ago

If you follow a pull-request based workflow, and if you typically squash down to one commit, then finding these messages isn't too bad, since the commit description pre-populates into the pull request description. I often track changes down not to their commit, but to their pull request. Granted, that's not exactly `git`, but rather `github`…

nightfly 3y ago

git log. git blame, grab hash, git log hash. You make it sound like some arcane magic...

kelnos 3y ago

While this may be how most people interact with git, I couldn't disagree more when it comes to my personal use. I use 'git blame' (I've never needed to pass any options to it) and 'git show' liberally if I'm trying to understand a change that was made, and if the committer took the time to write a commit message body, of course I'll see it and read it. > ... 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. I think people don't care much about good commit messages because they are unprofessional and sloppy. They just want to get the commit in, push the PR/MR, get it reviewed and merged, close that Jira ticket, and get credit for those sweet sweet story points (ugh). And on top of that, they generally don't care to document their changes because they personally don't see the value of doing so. Surely they'll remember the change if they ever revisit it (no of course not, but many people think they will), and they don't really give much thought to the possibility that others might need more context. And besides, all the discussion about the bug or feature or whatever was happening in the bug tracker, so providing a link to that issue in the commit message is enough, right? (No, it's not; I hate it when people do that and think that's all they need to do.) > The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. Then maybe this is GitHub's fault; fix your web UI, then. I avoid GUI interfaces to my dev tools as much as possible, and I think the git command line is perfectly fine for this. It absolutely does not only show the first line, generally. 'git log', 'git show', etc. give you the full message by default. In general I would say you have to go out of your way (by providing more command line options) to hide the message when using the command line tools. > the Git commit message is a unique vector for code documentation that is highly sub-optimal. Sure, because it's not a vector for code documentation, it's a vector for change documentation. And there's no better place to put the description of a change than in the record of the change happening. While I agree that many people write very poor commit messages, I don't think the tooling and discoverability is why.

jeremyw 3y ago

I take Scott's point with a difference perspective. Though commit messages are ephemeral and hard to utilize in the future, they're the stream of consciousness of the project. They convey very important shifts in direction, discoveries in the making, code smells, limits of current architecture, and markers of tech debt. We don't know what this beast will be. And we figure it out commit by commit. Document it.

yencabulator 3y ago
Commit messages are the very opposite of ephemeral; they are the longest-lasting history a project is likely to have!
- jeremyw 3y ago
  Yes, I misworded. The usefulness of commit messages, Scott's point.

deleted 3y ago

[deleted]

jakub_g 3y ago

In my experience it all depends on what kind of codebase it is (product? library/framework? private company? opensource?), commit velocity, release cadence & how the codebase is used in general. In low-velocity opensource libraries, good and clean commit messages can be really helpful when debugging arcane issues. I used to be maintainer of a frontend framework & widget library and we tried to have good commit messages as we'd often go back when over old commits when fixing bugs. I agree that using git from command line for blame is not easy, this is something I always do from GitHub UI instead. When GitHub is the repo's choice for PRs, and the codebase is product codebase with high velocity, having a pristine git history and clean commits and commit messages is not practical; however, the expectation should be to at least have good PR descriptions. When blaming commits in GH UI, it's easy to go to the PR which introduced the commit (it's linked below commit title); and PR descriptions can be enforced via templates in .github folder. PR descriptions have an advantage that they can use images, videos etc. to better explain what they change. This is especially useful for frontend codebases. I work on a big frontend monorepo. We have tools in place to do visual bisect between pull requests (each PR gets its own preview env). We very much do read PR descriptions when doing bisect to confirm which of the recently merged dozens of PRs introduced a regression in production N hours ago. But in general I agree that commit messages are not good place to storage general knowledge (they're good for "what and why is changing here"). For documenting gotchas etc. I prefer to have code comments in relevant places of code; or README.md in subfolders. (Sadly, I notice most programmers just don't document anything anywhere at all).

b33j0r 3y ago

Author of nit, here. I tried to move the landscape towards semantic reasoning. It’s on github but kind of abandonware. Life and incompetency happened ;) No shilling. I commented here because I still think my framework was decently thought out, and mostly that calling someone a nit or a git is exactly what linus was thinking. Make it easy enough for anyone to use. Nit is something people could take as a thought experiment.

twosdai 3y ago

Completely agree, the value with the message is really just to link an external ticket Id, the user experience is much better in external ticketing systems for all of the story telling that the article loves. Don't read "external ticket system" as closed either, plenty systems are open to the public.

cerved 3y ago
Right. The massive commit with minimal description and a PR number which I can look up in Azure DevOps to find a review with no description, no discussion and a mention of a number I can go and look up in Jira, where some Scrum master wrote half a sentence of what needs to be done and asking to "reach out to Jeff" for explanation. So much more valuable and great user experience
- yencabulator 3y ago
  Just wait till next year when your employer migrates away from Azure DevOps and that PR number will be a dangling link forever lost.
  - cerved 3y ago
    Or you just move the repository to a different protect

6510 3y ago

Just do a threaded conversation in a comment at the top of each file. Add your name and the date.

krobelus 3y ago

> 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. I find this very hard to believe. Isn't it "everyone who is interested in the commit subject/files touched should read the body". Why would anyone else read immutable historical documentation? > 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 sounds like you are joking. Any good IDE will be able to annotate each line with blame info, and show the diff at the press of a button. On such diffs, the IDE should allow recursive blaming on context/deleted lines. Tools like Tig allow exactly that. GitHub certainly does make it hard to see commit messages, I give you that :) > Hundreds of hours of amazing documentation from a true genius that almost nobody will ever appreciate. It's horrifying. ?? It's not like it was written for fun. This documentation attached to a commit exists to reduce the risk of accepting the patch from someone who might not be around in future, to fix any problems introduced. By disclosing all their relevant thoughts, the author shows their good intentions: they enable others to build on top of their work. If the author kept their thoughts to themselves they would gradually build up exclusive ownership of the code, which is often not a good idea. Also a commit message serves as proof of work, which can be important when there's too many patches. For commercial projects some of this is less important.

makeitdouble 3y ago
I might be in the minority, but parent's comment is probably about people like me: most of my coworkers have context free, or at best succinct commit messages. I never read more than the first line listed in the commit list, and don't even assume the description is always accurate. Instead I'll spend my time stalking the related merge request, where the full description of the whole change resides, with probably a link to the ticket or reference documentation, and all the back and forth on why something is or isn't a good idea. I think the world could be a better place if all of that was in git directly, but that's also utting much more burden on an already complex tool.

tibbar 3y ago

In practice, I think GitHub/GitLab/etc solve this UX problem pretty well. Inline git tools let you jump immediately to the PR that generated the code change, and the PR description + code reviews + snapshot of the commit help to understand what the point of the change was. You can search the PRs when you want to find some context. (It's unfortunate that PRs are not stored in the repository itself. I mean, Git is not a great database for a multi-user webpage, so this wouldn't quite work... but it would be nice if the archive was durable and easy to export/share.)

sohamssd 3y ago

Your entire argument boils down to the fact that it's hard to view git blames. It's not. As stated by other people, IDEs like VSCode and IntelliJ do an extremely good job of showing the blame. And they DO show the entire commit, body and everything at once.

da_chicken 3y ago

> The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. This has been an issue with version control tooling for quite a long time. I'm fairly certain both CVS and SVN did the same thing. But I agree that you're still right. I'm also very amused by the number of replies to your comment along the lines of, "oh, it's actually very easy because I always use <third party tool>". Which is, of course, rather proving the point.

dragonwriter 3y ago
No, because the point is about common tooling, and the common tooling does not, actually, make this difficult.
- da_chicken 3y ago
  That's rather a matter of opinion. One that I and GP both clearly disagree with. Insisting it's easy doesn't mean everyone will agree with you.

palata 3y ago

> The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. Maybe I do it wrong, but the most basic interface I use to check the git history is `git log`, which shows the whole commit message. GitHub takes me 18 clicks to find the commits, I don't see why I would even bother using it.

ParetoOptimal 3y ago
Many engineers primarily or even exclusively use git via githubs interface and have never made a commit with a body.
- cerved 3y ago
  Those "engineers" go on _The List_
- palata 3y ago
  Right, but then maybe the main issue is those engineers, and not the tooling? When I see someone using a hammer the wrong way, I don't usually blame the hammer.
  - ParetoOptimal 3y ago
    The problem is the network effects. If enough people start hammering with the side to pull out nails, like 95%, there's a chance that could become known as "the right way". I think a lot of the "get shit done" crowd for instance sees using Github and not "futzing around with git" as the right way to do things for getting shit done.
    - palata 3y ago
      Sure, but because "the majority thinks it is the right way" does not mean it is. My point is that when the majority of people don't know how the most basic tool they use is meant to be used, then it is a problem. It would still be better to say "I know how a hammer is meant to be used, but I choose to use it this other way", but that is not the situation right now. The situation right now is that more and more devs don't know that git != GitHub. And that inequality is an objective fact, it has nothing to do with network effects. Everybody believing that the Earth is flat would not make it flat.

djha-skin 3y ago

This sounds like an excellent sales pitch to use email based good workflows such as those advocated for by Drew DeVault[1]. 1: https://git-send-email.io/ https://git-send-email.io/

heads 3y ago

To tack one additional problem onto your excellent list: the commit message is usually only the start of a conversation about why a change should be made. The rest of that discussion is whether it meets the bar and what needs to be adjusted before it can land on the collaborative trunk. Done well, that is valuable reading. Git was designed with the distributed viewpoint. A commit message, as written by the author, is necessarily correct: I’ve decided this is right, and it’s on you to decide if you want to merge it into your history too. In our current systems we usually have a URL in the commit message that links to the actual story behind the commit — the discussion on the pull request, merge request, or code review. I rarely see the results of these discussions being amended into the commit message. If the repo lives forever but the database behind the code review tool gets toasted then something just as important is lost forever. (I come from a background of one idea equals one amended, fast forwarded commit to master. It’s possible other people rely on branch history to reflect the evolution of ideas and how they go from a request for review to approved code. In my experience branch histories tend to have very low quality commit messages and even then they only show one side of the conversation — the author’s responses to their reviewer’s and their own critiques.)

phaedrus 3y ago

So then I am not wrong that I do all my git commit messages via the "-m" commandline option with a short phrase like "frob the baz"? (Initially I started using -m to avoid getting trapped in Vim. But even after I gained the option to use e.g. Notepad++ as the editor, I never saw the point in using anything more than "-m 'message'".)

kimixa 3y ago
Git respects the EDITOR environment variable and has done for decades (so likely before many here really used it) - you should probably be setting that (or equivalent on your platform) to the editor you want anyway. Weird workaround just to avoid basic configuration seems like more work in the long run.

colelyman 3y ago

One tool that I think promotes commit messages like the OP is magit in Emacs. Before using magit, I always used `git commit -m '...'` and didn't realize that commit messages could be longer than a line. I agree that this is a tooling problem, but magit is a breath of fresh air in many ways (including verbose commit messages).

nequo 3y ago
What I like about magit is that it shows me the diff of the would-be commit when I write the commit message. And also that I can pick which sections of the diff to a file I want to include in the commit. I used Vim + git CLI before and this was much less convenient. (I never tried fugitive though. It might be similarly great on these two features.)

lambda 3y ago

It's amazing, your experience with Git is so different than my own. I routinely open a file in my editor, hit "Ctrl-c v B" for Git Blame mode, go to the line I'm interested in, and hit "Enter". Bam, there's the full commit message. From there I can can continue to trace backwards, blaming lines and reading full commit messages. But, you know, not everyone uses Emacs and Magit, fair. How about just using "git gui blame file"? Click on a blame line, see the full commit message. This is a tool included with Git (available in a separate package in some installations). OK, rather use an IDE? Install GitLens in VSCode. Easily accessible blame in your editor, where you can hover or click in various places to see full commit messages. I mean, I agree in part; there are some tools which make good commit messages hard to write or find. The tiny little commit message edit box in VScode is not ideal. Lots of people use a workflow of "commit lots of crappy commits with one liner commit messages, let GitHub/GitLab squash them on merge." But as an expert Git user who has managed to convince some teams to have a good commit message culture, if you do get people used to writing good commit messages, they can be very easy to find and read later on, there are tons of tools that make them easy to browse.

kimixa 3y ago
I regularly use the git command line, and "git show (pasted SHA)" in my second terminal doesn't really feel like the road block to understanding the grandparent seems to make it out to be. It takes me many orders of magnitude more time understanding what is output rather than searching for it, and like you mentioned there are any number of UIs (third party, editor integration, or even shipped with git like gitk) that wire everything up into a nice UI. And I also disagree with the GP's complaint that "Most people only read the shortlog" being any kind of disadvantage. The commit message isn't for everyone, it's for the one time someone needs to figure out exactly what it did and why that commit was made, and why a change in X causes a behavior change in Y, and can save hours of work. It's like code comments, 99 times out of 100 you don't need them as you're just interacting with a documented API, but that 1 other time they are a godsend.

adityaathalye 3y ago

> 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. I completely agree that well-written git log messages are goldmines of information. I wish makers of popular git forges had made it easier to create and consume this information. Almost all my wiki pages start with piping git log messages into a text file. Git logs are the entry point to good project documentation. (edit: fix formatting)

Groxx 3y ago

I feel like this explains a lot about why GitHub is so consistently hostile towards showing or writing decent commit messages. Which has helped push people away from writing useful ones, on an unprecedented scale, which makes it a self-fulfilling prophecy. Great. Just great.

gloosx 3y ago

I use fugitive.vim, and blaming is very convenient there as well as every other git workflow. I can press a shortcut to see when every line in the current file was changed, and who changed it along with the commit hash. If I need more – I can expand every hash to see the full context, including full commit text and diff. Maybe cli git is not too easy to use since how complex it is, but there exists a git wrapper so awesome it should be illegal

schacon 3y ago

To be clear from reading some of the other comments, I don't work at GitHub anymore so while I may have partially caused the issues I'm complaining about, I don't have the ability to fix them anymore. Also, while most GUIs and editors have blame capability (as does GitHub actually), most of them don't ignore whitespace changes (-w), code movement or renames (the -C options) so they're often of limited use. Finally, I _would_ like people to write good commit messages, I just would like to see a tool that actually uses that work in a way that helps document your code in an easy and valuable way, and the Git/Hub tooling makes that process at best "tedious" as someone in the thread says. I am working on a new Git client called GitButler[1] and would like to address this at some point down the line, so maybe it ends up being me who helps fix this after all :) 1: https://gitbutler.com https://gitbutler.com

lawtalkinghuman 3y ago

The reason people (myself included) rather like good Git commit messages is evident when one compares them to the alternative. You're working in a commercial/closed source environment and want to find out why line 57 in src/blah/db/utils.py does that. Where do you look? - inline code comments. Usually non-existent. Often out-of-date, sometimes misleading, frequently tells you no more than you can discern from just reading the code itself (especially now type annotations are trendy again). Rarely explains why the code exists. There's a reason people caution against too many comments, and that translates into people probably not putting enough commentsin. - calling code? Helpful, but thanks to microservices and increased levels of abstraction (APIs, DI frameworks, messaging buses, config parsing) you've got to go check 900 different repos out to work out what is going on. - email? Give up. You'll find invitations to the company Christmas party and Q2 sales figures but actual tech explanations are in short supply. - Slack etc - same problems as email, plus developers who hide away all the interesting stuff in private team channels - Google Docs - you probably don't have access to the relevant doc, and there's no way to know that you don't - wiki/docs? Half baked, wrong etc. Or it'll be autogenerated JavaDoc type stuff that'll tell you what you already know or can reasonably infer from the code. Also, findability sucks. Or the developers just avoid the whole thing because the software is nasty and corporate and barely usuable. - bug tracker/ticketing system? You ask around and someone says "oh yeah, Dave made that change two years ago" and then you search for tickets that match related keywords only to find out that those tickets weren't brought over from Trello into JIRA, and now you need to go ask IT to give you access to the legacy Trello board which they don't want to do because then it'll put them over the five users per month limit or whatever. - Architecture Decision Records / decision logs / whatever you want to to call them - nice if they exist, I guess. - ask the person who wrote it? This assumes they still work there and can remember. Plus you gotta do the asking around routine which takes days and destroys all hope and joy in the world. By a process of elimination, commit messages are the closest you're going to get. They're right there - on your computer, neatly integrated into your editor, hopefully. You can search them fast in a terminal window rather than in some slow web-based monstrosity. If you're lucky, they're actually useful. Even if they aren't, they're at least contextually useful in helping you narrow down your search strategy for the inevitable plunge through email/slack/JIRA/Trello/internal wiki etc. Ideally what should happen is the really useful commit messages get copied into stable technical documentation like decision logs or a properly maintaned wiki. If people did that, great, but it's pretty rare. A culture of sharing weird interesting tech things in a Slack-type system can help because future devs can at least search but you do that at the cost of more interruptions for colleagues now. The broader issue is of all the bad options you can choose, it often tracks the wrong thing. In something like Trello/JIRA/whatever, if you're looking for the technical reasons, it'll have the business reasons without the technical stuff, or vice versa. You generally want both, and most systems only give you half the story.

lucioperca 3y ago

Of course Emacs has a mode for it: https://github.com/redguardtoo/vc-msg https://github.com/redguardtoo/vc-msg

deleted 3y ago

[deleted]

FrederickZh 3y ago

> 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. This was why I created gh-ph [1]. [1] https://github.com/Frederick888/gh-ph https://github.com/Frederick888/gh-ph