5 ms·

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`, an

by 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".
- Dylan16807 3y ago
  > the whole commit message is just a blog entry in the wrong place. Right. All this wonderful information and detailed error messages need to be findable by someone searching the same error. Someone digging into the code is a very different use case and they need a tiny fraction of that information.
- tehnub 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. Well what about this example: I removed a few lines of code and explained in the commit message why I thought it was correct to do that. If somebody (possibly me) comes looking for that code and realizes it's not there, they'll be much happier to see some sort of explanation rather than a "removed lines" message. Regarding commenting in the code vs. in the commit message, sometimes I copy-paste my explanatory comment if there is one into my commit message.
  - neilkk 3y ago
    Right. You've given an example of exactly what I said was the only reasonable use case for detailed info in the commit message: someone in the future will need to know the history of that particular piece of code. It seems like the point of your specific example is to say 'in some cases you might want to know the history of a gap'. Fine. That seems like a nitpick to me. No one in the future will need to know the history of a particular ascii encoded blank space (among a whole file of ASCII encoded blank spaces). Anyone who needs the general info that the file needs to be ascii will be helped by it being somewhere else, as opposed to in a random commit message.
    - thfuran 3y ago
      But virtually every diff is one that someone in the future might want more information on. You can't know that they won't until you get to the end of the future and haven't needed it.
spacemankiller 3y ago
> 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. I don’t think this is proper way of reasoning. What is hard and easy is subjective. And you discuss it as it would be objective. Word against word. It would be wise to have some poll and see results. If one geek is writing and reading commit messages doesn’t mean it’s easily accessible by everyone. It’s hard to make something as a widespread standard if tooling doesn’t make it super easy to access. Allow people to leave kudos and emoji to other people commits messages and people will start making them better :D And later show heroic people with git —-stats
nox101 3y ago
I'm mixed on this. My project has a bug tracker. A commit is required to have a bug id. The bug tracker has entire discussions of what lead to the commit so it's not clear to me that a detailed commit message is a plus when the real detailed info is in the tracker. Yes it's indirect but there's no way I'm going to summarize the entire issue discussion. Maybe this is a job for machine learning. Read the code, read the commits, read the bug tracker, add a git super-blame that asks the LLM to summarize why every line is the way it is and what it's doing
- ghqst 3y ago
  This is why at work the only required rule for commit messages is that they include the story number, so we can very easily find at least the general reason for a change from git blame.
- u801e 3y ago
  > A commit is required to have a bug id. The bug tracker has entire discussions of what lead to the commit Companies do change bug trackers and ticketing systems and those links may no longer work years down the line. > The bug tracker has entire discussions of what lead to the commit so it's not clear to me that a detailed commit message is a plus when the real detailed info is in the tracker. Yes it's indirect but there's no way I'm going to summarize the entire issue discussion. But summarizing it can be one of the most valuable things you can do for a maintainer who has to make changes years after you've moved on. For one thing, the problem and discussion is fresh in your mind and you understand the context. In a few minutes, you could summarize the problem, the approach taken to fix it and alternatives that were considered but not used because the chosen solution clearly didn't have an issue/was more efficient, etc. Even if you didn't want to do that, you could just copy and paste the entire discussion text at the end of the commit message so that even if the bug tracker is no longer in use in the future, the discussion itself was preserved in the commit history and accessible via git log or blame.
  - Izkata 3y ago
    > > A commit is required to have a bug id. The bug tracker has entire discussions of what lead to the commit > Companies do change bug trackers and ticketing systems and those links may no longer work years down the line. I've experienced this twice, we switched from Bugzilla to FogBugz to Jira in my time. With one relatively small exception in the FogBugz to Jira transition, all past case information was lost.
corethree 3y ago
His credentials indicate that it may be possible that his arguments are based on data while your credentials and evidence indicate personal, anecdotal experience. Therefore I would trust his reasoning more. Additionally, I personally identify with it. I mean a git developer finds git easy to use? That's biased data. I love how both of you dropped your street cred before launching into your reasoning. It just shows how much more credentials convinces people rather then the argument itself. Normally that stuff logically doesn't matter and people are just doing it to grab some "authoritah" but in this case your backgrounds actually contributed to the arguments.
Izkata 3y ago
Definite agree there: Be it git or svn I spent a huge amount of my bugfixing and refactoring time in the history figuring out why things are the way they are. > 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. Assuming all those links in the chain still exist. Before Jira we had FogBugz, almost all those old cases are gone (some were imported). And we used Flowdock for 10 years, that's completely gone. Commit messages are the only thing we can rely on for this history. Use it. And try to avoid squashing commits, that erases this history - yes, even for a feature branch, changes from code review should be separate from the initial push, explain why it's being changed so we don't make the same mistake later.
munksbeer 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. I 100% agree with this. I do this all the time. I also agree with the rest of the post. The sentiment raging against these longer git commit messages smells very much like elitism to me.
elygre 3y ago
How does this work in the face of unrelated refactoring? Say you first fix a bug somewhere, with a great commit comment. Then some refactoring happens, and the affected function is moved to a new class in a new file. Are you still able to track the original git comment?
- js2 3y ago
  Say you found the current commit through `git blame`. You run `git show` on that commit. The diff shows that the function you're interested in was actually moved so from the diff output you can see the previous filename and you have the function name. You could use: git log -GsomeRandomFunction -- path/to/some/random/source.ext That will then find the commit where `someRandomFunction` was removed from `source.ext` and then the commit before that where it was added to `someRandomFunction`. Git log has a gazillion options and I've probably used them all at one time or another, but 99% of the time, the only ones I need are `-G` and following a particular file. https://git-scm.com/docs/git-log#Documentation/git-log.txt--Gltregexgt https://git-scm.com/docs/git-log#Documentation/git-log.txt--... I also have `diff.renames` set to "copies" and `diff.algorithm` to "patience" in my `.gitconfig`: https://git-scm.com/docs/git-config#Documentation/git-config.txt-diffrenames https://git-scm.com/docs/git-config#Documentation/git-config... https://git-scm.com/docs/git-config#Documentation/git-config.txt-diffalgorithm https://git-scm.com/docs/git-config#Documentation/git-config...
michaelcampbell 3y ago
> It's trivial to follow the history of a file. If the committer uses the "show history of a file" process model. These days, it's mostly "squash commits until I get a good/flattering 'story' of what I did", which removes typos, failed experiments, mid-thought commits, and any other blemishes of _what actually happened_. Commits CAN be used as great history, if history is allowed, but I've found that "modern" workflows tend to the rebase/squash side of things and also are mostly write-only.
- WorldMaker 3y ago
  I still wonder how much of rebase/squash-heavy workflows would disappear if UIs like GitHub and the CLI itself defaulted to `--first-parent` style views (with optional drilldown) and used the power of navigating a DAG for a little more good. All of this good commit metadata lost just because subway diagrams are pretty but also so many people find them confusing and messy. Or because GitHub shows commits as a flat confusing list with an order that only makes sense if you saw the subway diagram but GitHub's default view doesn't draw the subway diagram.

by js2 3y ago

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".

Dylan16807 3y ago
> the whole commit message is just a blog entry in the wrong place. Right. All this wonderful information and detailed error messages need to be findable by someone searching the same error. Someone digging into the code is a very different use case and they need a tiny fraction of that information.
tehnub 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. Well what about this example: I removed a few lines of code and explained in the commit message why I thought it was correct to do that. If somebody (possibly me) comes looking for that code and realizes it's not there, they'll be much happier to see some sort of explanation rather than a "removed lines" message. Regarding commenting in the code vs. in the commit message, sometimes I copy-paste my explanatory comment if there is one into my commit message.
- neilkk 3y ago
  Right. You've given an example of exactly what I said was the only reasonable use case for detailed info in the commit message: someone in the future will need to know the history of that particular piece of code. It seems like the point of your specific example is to say 'in some cases you might want to know the history of a gap'. Fine. That seems like a nitpick to me. No one in the future will need to know the history of a particular ascii encoded blank space (among a whole file of ASCII encoded blank spaces). Anyone who needs the general info that the file needs to be ascii will be helped by it being somewhere else, as opposed to in a random commit message.
  - thfuran 3y ago
    But virtually every diff is one that someone in the future might want more information on. You can't know that they won't until you get to the end of the future and haven't needed it.

spacemankiller 3y ago

> 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. I don’t think this is proper way of reasoning. What is hard and easy is subjective. And you discuss it as it would be objective. Word against word. It would be wise to have some poll and see results. If one geek is writing and reading commit messages doesn’t mean it’s easily accessible by everyone. It’s hard to make something as a widespread standard if tooling doesn’t make it super easy to access. Allow people to leave kudos and emoji to other people commits messages and people will start making them better :D And later show heroic people with git —-stats

nox101 3y ago

I'm mixed on this. My project has a bug tracker. A commit is required to have a bug id. The bug tracker has entire discussions of what lead to the commit so it's not clear to me that a detailed commit message is a plus when the real detailed info is in the tracker. Yes it's indirect but there's no way I'm going to summarize the entire issue discussion. Maybe this is a job for machine learning. Read the code, read the commits, read the bug tracker, add a git super-blame that asks the LLM to summarize why every line is the way it is and what it's doing

ghqst 3y ago
This is why at work the only required rule for commit messages is that they include the story number, so we can very easily find at least the general reason for a change from git blame.
u801e 3y ago
> A commit is required to have a bug id. The bug tracker has entire discussions of what lead to the commit Companies do change bug trackers and ticketing systems and those links may no longer work years down the line. > The bug tracker has entire discussions of what lead to the commit so it's not clear to me that a detailed commit message is a plus when the real detailed info is in the tracker. Yes it's indirect but there's no way I'm going to summarize the entire issue discussion. But summarizing it can be one of the most valuable things you can do for a maintainer who has to make changes years after you've moved on. For one thing, the problem and discussion is fresh in your mind and you understand the context. In a few minutes, you could summarize the problem, the approach taken to fix it and alternatives that were considered but not used because the chosen solution clearly didn't have an issue/was more efficient, etc. Even if you didn't want to do that, you could just copy and paste the entire discussion text at the end of the commit message so that even if the bug tracker is no longer in use in the future, the discussion itself was preserved in the commit history and accessible via git log or blame.
- Izkata 3y ago
  > > A commit is required to have a bug id. The bug tracker has entire discussions of what lead to the commit > Companies do change bug trackers and ticketing systems and those links may no longer work years down the line. I've experienced this twice, we switched from Bugzilla to FogBugz to Jira in my time. With one relatively small exception in the FogBugz to Jira transition, all past case information was lost.

corethree 3y ago

His credentials indicate that it may be possible that his arguments are based on data while your credentials and evidence indicate personal, anecdotal experience. Therefore I would trust his reasoning more. Additionally, I personally identify with it. I mean a git developer finds git easy to use? That's biased data. I love how both of you dropped your street cred before launching into your reasoning. It just shows how much more credentials convinces people rather then the argument itself. Normally that stuff logically doesn't matter and people are just doing it to grab some "authoritah" but in this case your backgrounds actually contributed to the arguments.

Izkata 3y ago

Definite agree there: Be it git or svn I spent a huge amount of my bugfixing and refactoring time in the history figuring out why things are the way they are. > 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. Assuming all those links in the chain still exist. Before Jira we had FogBugz, almost all those old cases are gone (some were imported). And we used Flowdock for 10 years, that's completely gone. Commit messages are the only thing we can rely on for this history. Use it. And try to avoid squashing commits, that erases this history - yes, even for a feature branch, changes from code review should be separate from the initial push, explain why it's being changed so we don't make the same mistake later.

munksbeer 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. I 100% agree with this. I do this all the time. I also agree with the rest of the post. The sentiment raging against these longer git commit messages smells very much like elitism to me.

elygre 3y ago

How does this work in the face of unrelated refactoring? Say you first fix a bug somewhere, with a great commit comment. Then some refactoring happens, and the affected function is moved to a new class in a new file. Are you still able to track the original git comment?

js2 3y ago
Say you found the current commit through `git blame`. You run `git show` on that commit. The diff shows that the function you're interested in was actually moved so from the diff output you can see the previous filename and you have the function name. You could use: git log -GsomeRandomFunction -- path/to/some/random/source.ext That will then find the commit where `someRandomFunction` was removed from `source.ext` and then the commit before that where it was added to `someRandomFunction`. Git log has a gazillion options and I've probably used them all at one time or another, but 99% of the time, the only ones I need are `-G` and following a particular file. https://git-scm.com/docs/git-log#Documentation/git-log.txt--Gltregexgt https://git-scm.com/docs/git-log#Documentation/git-log.txt--... I also have `diff.renames` set to "copies" and `diff.algorithm` to "patience" in my `.gitconfig`: https://git-scm.com/docs/git-config#Documentation/git-config.txt-diffrenames https://git-scm.com/docs/git-config#Documentation/git-config... https://git-scm.com/docs/git-config#Documentation/git-config.txt-diffalgorithm https://git-scm.com/docs/git-config#Documentation/git-config...

michaelcampbell 3y ago

> It's trivial to follow the history of a file. If the committer uses the "show history of a file" process model. These days, it's mostly "squash commits until I get a good/flattering 'story' of what I did", which removes typos, failed experiments, mid-thought commits, and any other blemishes of _what actually happened_. Commits CAN be used as great history, if history is allowed, but I've found that "modern" workflows tend to the rebase/squash side of things and also are mostly write-only.

WorldMaker 3y ago
I still wonder how much of rebase/squash-heavy workflows would disappear if UIs like GitHub and the CLI itself defaulted to `--first-parent` style views (with optional drilldown) and used the power of navigating a DAG for a little more good. All of this good commit metadata lost just because subway diagrams are pretty but also so many people find them confusing and messy. Or because GitHub shows commits as a flat confusing list with an order that only makes sense if you saw the subway diagram but GitHub's default view doesn't draw the subway diagram.