7 ms·

OR you could just write Replace invalid ASCII char. Fixes rake error 'invalid byte sequence in US-ASCII'. I don't want your entire life story in my commit log

OR you could just write Replace invalid ASCII char. Fixes rake error 'invalid byte sequence in US-ASCII'. I don't want your entire life story in my commit log.

vanderZwan 7y ago
“I didn't have time to write a short commit message, so I wrote a long one instead.”
- V-2 7y ago
  Pascal! My favorite language
konsnos 7y ago
This is true when you can reference the commit to an issue. Then, seeing the simple commit message you can select if you want to dig up what happened by reading up the comments at the issue. On the other hand it really gets into my nerves when people don't use the task/issue/whatever manager system appropriately. Recently, I lost a couple of days trying to figure out how to compile a c++ framework because the other guy didn't document his pipeline. In general I'm really disappointed by the majority of my colleagues for the lack of comments inside and outside of our codebase and this is a persistent issue, at all the companies I worked for. Me along with other similarly irritated people, always ask for documentation if it is not given.
- dmortin 7y ago
  > Recently, I lost a couple of days trying to figure out how to compile a c++ framework because the other guy didn't document his pipeline Some people do it for job safety. The logic is if you don't document things and the knowledge is only in your head then you are more valuable, they can't get rid of you easily. If you document everything meticulously, then you are easier to replace.
  - throw0101a 7y ago
    > Some people do it for job safety. The logic is ... Has anyone actually seen this logic work out well for the person that invokes it? Generally the type of person that uses it is one that you probably don't want on your team.
    - thiefmeister 7y ago
      I have! Company promoted the guy and raised his salary because he had plan to leave the company
      - vidarh 7y ago
        I know in instances like that, though, my next step would be to start working on contingency plans, as if someone has proven themselves to be indispensable, then that very fact is a risk that needs to be managed.
        beart 7y ago
        Like having a new guy learn the material, taught by the old guy who doesn't want anyone else knowing it!
- mlang23 7y ago
  Talented coworkers dont need documentation very often... If someone cant figure out how to compile something, its likely they are missing knowledge about the language in general...
- com2kid 7y ago
  > Recently, I lost a couple of days trying to figure out how to compile a c++ framework because the other guy didn't document his pipeline. This is assuming documenting the pipeline would have been helping! You may have spent a few days instead figuring out why your seemingly identical setup couldn't reproduce the build... Not that I'm bitter about build systems or anything.
leejo 7y ago
> I don't want your entire life story in my commit log. I[1] want enough debug information in the commit log to be able to reproduce the issue without having to go on web hunts to understand the problem. Especially when the change appears to be trivial on the surface, because these are the ones that can turn out to be rabbit holes. I don't want to have to interrupt you to get this information because you didn't write a good enough commit message, and you probably don't remember anyway. I don't want go look at an external issue tracker that i may not have access to, or may not even exist anymore. [1] Where "I" is: me, your future self, a future maintainer, a junior dev, an open source contributor.
- afiori 7y ago
  > I don't want go look at an external issue tracker Related question: are there projects that use git itself as issue tracker?
  - johnday 7y ago
    I can imagine that working to a degree: Make a fork of a commit at an issue, then merge that fork back in with master at point of fix. Bit of a mess in the tree though.
  - _TwoFinger 7y ago
    https://news.ycombinator.com/item?id=13732598 https://news.ycombinator.com/item?id=13732598
  - cipherboy 7y ago
    Pagure [0], Fedora's git forge, hosts code, issues, docs, and pull requests as four separate git repositories under the hood [1]. However, only project administrators can clone most of those repos. [0]: https://pagure.io/pagure https://pagure.io/pagure [1]: https://docs.pagure.org/pagure/usage.html https://docs.pagure.org/pagure/usage.html
  - BlueTemplar 7y ago
    https://github.com/MichaelMure/git-bug https://github.com/MichaelMure/git-bug
mschwaig 7y ago
Generally speaking sure, there's no need to make things more complicated than they are, but the author even found some evidence in the history that indicates other people found this message useful. The powerful thing about this is having everyone put this kind of info in the same place IF they think it might be useful to the next person.
CGamesPlay 7y ago
Still, you've left out the details that you've confirmed that there's no other instances of this in our codebase. I'm also firmly in the "all commit messages should include a test plan" camp, so you should at least say how you found the error ("bundle exec rake was run before and after"). I get you're being terse for demonstrative purposes, but even eschewing verbosity we should still convey all the pertinent information.
EliRivers 7y ago
That's great for you. You don't want that. However, if you code in a team, doing everything for your own wants rather than considering the needs of the team (present and future) is just bad software engineering.
Cthulhu_ 7y ago
For critical applications, I for one would like to know the story behind a commit, preferably in the commit itself and not a reference to an external system like idk, Jira. My favorite examples of commit messages are the Linux kernel, where you can tell that they're being specifically crafted instead of just used as a work log to be ignored. This means that ten years down the line, people can still see when a change was made and why, who was involved, who signed off on it, etc. Have a look at the commits at https://github.com/torvalds/linux/commits/master https://github.com/torvalds/linux/commits/master
m_sahaf 7y ago
On the other end of the spectrum you get ImageMagick useless commit messages[0]. That extreme aside, I'd rather have commit messages that delve into the why-and-how the commit alters the behavior to the better rather than cryptic message as 'Replace invalid ASCII char'. Now we have documented reasoning and thought process that can aid future debugging. They can also be beneficial for new devs hacking on the project, or students learning how to implement and improve systems. Personally, I enjoy reading these. The Go commits often have commit messages like these, and they are shared on HN often for a reason. They're learning material. They can't go on a wiki because they're tied to particular set of changes in a particular point in history. They also can't be comments on the code because they're tied to particular lines in different files, and code comments can only cover a set of consecutive lines in one file. One recent example I could find is this[1]. Yeah, it fixes ^Z, but why didn't the old approach work? Why did it work for some time then didn't? How did it change? Why is this commit optimal, if it is? All of this along with scenarios to reproduce the issue. Give me your life story anytime over cryptic message. [0] https://github.com/ImageMagick/ImageMagick/commits/master https://github.com/ImageMagick/ImageMagick/commits/master [1] https://github.com/golang/go/commit/610d522189ed3fcf0d298609a248a3283bde62cd https://github.com/golang/go/commit/610d522189ed3fcf0d298609...
- graton 7y ago
  Agreed. When at some point the website that they are pointing to changes in the future they will lose all context on why a change was made. I believe in the "plane flying across the ocean without WiFi test" or basically anywhere without Internet access. If I am on a plane flying across the ocean without WiFi, do I have the information in the git commit to understand what happened. A git message that consists entirely of a link to a website is useless in that case.
DJHenk 7y ago
That's why most guidelines for commit messages prescribe a short description and an optional long description. The message in the article does not have a short description, which would have been easy to include. For that reason, it's not "My favorite Git commit message" either.
gwd 7y ago
> I don't want your entire life story in my commit log. I agree with this, but I think yours is too short. Scientific papers typically introduce enough information such that a person familiar with the field but not an expert in that particular area can understand generally what's going on. That's my ideal for a commit message as well: someone generally familiar with the codebase but who hasn't looked at this specific code (or perhaps not in a few months) should be able to understand what's going on; then the job of the reviewer is basically just verification. My "template" is normally something like: 1) What's the current situation 2) Why that's a problem 3) How this patch fixes it. So in this case, it might look something like this: --- Convert template to US-ASCII to fix error $functions use `.with_content(//)` matchers to do X. These matchers require ASCII content. The $foo template contains a non-ASCII space; this results in the following error: ArgumentError: invalid byte sequence in US-ASCII Fix this by replacing the non-ASCII space with an ASCII space. --- No need for a life story, but still searchable, and has enough information for even a casual contributor to do a useful review.
- munk-a 7y ago
  I really like that commit message - though it'd be nice to link to any sort of issue/task tracking ID that's relevant to that piece of work.
celticninja 7y ago
That belies the effort that went into the fix
nailer 7y ago
This is good, I'd add: > Replace invalid ASCII char. Fixes rake error 'invalid byte sequence in US-ASCII'. See #123 So people can get the life story if they want it.
- acdha 7y ago
  One downside to that approach: it requires your issue tracker to be stable for long periods of time. I've worked in a number of places where that's not true and you end up needing to figure out that the #123 linked by the system you're using now was actually #123 in the old system and was migrated as #456 in the current one. There's a balance here and I especially like that this commit message has enough information to make searches really easy should you need to do something like that.
marvin 7y ago
You can write the brief summary in the first 80 characters, like OP did. Then write details in the body below, in case someone needs the context. Most tools display only the first 80 characters unless you expand the body. This case is probably longer than necessary, but I've saved a day of debugging on multiple occasions due to someone (also myself) leaving some lines of context, reasons and reasoning after the high-level description.
JeffRosenberg 7y ago
Then use `git log --oneline` and you don't have to see the lengthy details, until the inevitable day when you find you need them.
- AlexCoventry 7y ago
  How do you surface them when you need them, though? git grep?
  - esotericn 7y ago
    Sure? Or 'git log', then use the pager to search, or pipe into something with better fuzzy search, etc?
  - JeffRosenberg 7y ago
    Git greps work if you're trying to search all the logs. I would think this detailed documentation would be most important when you're trying to understand a specific file or line of code. In that case, it's: - git blame (who wrote this?) - git show (look at the commit surfaced by blame)
jordigh 7y ago
> I don't want your entire life story in my commit log. Why not? Where else do you want it? Is something forcing you to read the full commit log? There's no length limit on commit messages and commit messages are mostly out of the way. Most VCSes have a way to only show you the first line. So if you want summaries, that's what the first line is for. If you want the full story, that's what the body is for. Combined with annotate/blame, commit messages can be very helpful source-level documentation. Nobody has ever complained about too much documentation, and commit messages are the perfect time to document what happened because it's one of the few times where our tools actually force us to write something in order to proceed. As long as we're being forced to write something, write something good and informative.
- jmilloy 7y ago
  I think the problem isn't the length or content of the commit message, but its organization. It needs to have the most important information first. It reads as an "entire life story" because it is written in a narrative, sequential form. Better organization would make it skimmable, and later coders could only read as far as they need to.
  - YourMatt 7y ago
    If I'm searching commits, I'm trying to find record of what changed and when. I only want clues, and quick skimming is paramount. I want no personality. I want concise descriptive commit messages. That said, we reference an ID from our project management software with every commit, so once I find the commit I'm looking for, I can reference it back to external documentation. I still discourage personality there as well because it can get out of hand and clutter the comments, but it's more forgivable than being on the commit itself.
- mattacular 7y ago
  The pull request is a good place to put such a large amount of information. That would also be a good way to make sure it is seen by the broader team instead of burying it in commit history. You could make the argument that then it would not be part of the git history and therefore could be lost if you change hosts.
lazyant 7y ago
do you think a junior developer, or maybe somebody not vary familiar with Linux would not learn anything or benefit from reading those comments? Obvious point is that commit messages can be used besides what was done as a form of documentation and teaching tool (why, how).
EugeneOZ 7y ago
> I don't want Who cares. Hope you enjoy this tone - your was the same.
Supermancho 7y ago
I, too, would rate this a substandard git comment. Dave basically vomited a bug ticket of information, which is highly contextual and irrelevant ... like the lines he was faced with, which tell us nothing in the future nor anything we could not see in the change. The error is known, from the ticket being addressed. Documenting what error a bundler throws in the application deployment, within git seems...silly, since it will likely not apply to all points in time. That's why we have separate issue tracking. There was a whitespace encoding issue AND the developer didn't really understand the issue, since they ended with "One hour of my life I won't get back.". Over my 20 years, I've seen this EXACT scenario multiple times across multiple companies. Some jr engineer gets stuck with some troublesome weird error in a corner-case that ends up being a non-standard whitespace. It's a learning opportunity and he lamented it because it was different and nobody told him "we could stop this from happening again, generate a new issue". There are salient improvements that the git commit would benefit from both comment changes and additional code: 1. Include a (new) feature ticket that is linked to this issue - to create a process that doesn't allow for this again (eg fix a linter) 2. Include the name of the bug ticket (Convert template to US-ASCII to fix error) in the commit title, that was being addressed. 3. Create a test to specifically enforce the us-ascii encoding or add necessary rules to a linter.
nickm12 7y ago
I agree with the sentiment; this message is quite long for an invalid character in a file. House style in the companies I've worked for is to include a link to a bug report and or code review that provides more context for those who want it. Even without that added context, I'd rather know

OR you could just write Replace invalid ASCII char. Fixes rake error 'invalid byte sequence in US-ASCII'. I don't want your entire life story in my commit log.

vanderZwan 7y ago

“I didn't have time to write a short commit message, so I wrote a long one instead.”

V-2 7y ago
Pascal! My favorite language

konsnos 7y ago

This is true when you can reference the commit to an issue. Then, seeing the simple commit message you can select if you want to dig up what happened by reading up the comments at the issue. On the other hand it really gets into my nerves when people don't use the task/issue/whatever manager system appropriately. Recently, I lost a couple of days trying to figure out how to compile a c++ framework because the other guy didn't document his pipeline. In general I'm really disappointed by the majority of my colleagues for the lack of comments inside and outside of our codebase and this is a persistent issue, at all the companies I worked for. Me along with other similarly irritated people, always ask for documentation if it is not given.

dmortin 7y ago
> Recently, I lost a couple of days trying to figure out how to compile a c++ framework because the other guy didn't document his pipeline Some people do it for job safety. The logic is if you don't document things and the knowledge is only in your head then you are more valuable, they can't get rid of you easily. If you document everything meticulously, then you are easier to replace.
- throw0101a 7y ago
  > Some people do it for job safety. The logic is ... Has anyone actually seen this logic work out well for the person that invokes it? Generally the type of person that uses it is one that you probably don't want on your team.
  - thiefmeister 7y ago
    I have! Company promoted the guy and raised his salary because he had plan to leave the company
    - vidarh 7y ago
      I know in instances like that, though, my next step would be to start working on contingency plans, as if someone has proven themselves to be indispensable, then that very fact is a risk that needs to be managed.
      - beart 7y ago
        Like having a new guy learn the material, taught by the old guy who doesn't want anyone else knowing it!
mlang23 7y ago
Talented coworkers dont need documentation very often... If someone cant figure out how to compile something, its likely they are missing knowledge about the language in general...
com2kid 7y ago
> Recently, I lost a couple of days trying to figure out how to compile a c++ framework because the other guy didn't document his pipeline. This is assuming documenting the pipeline would have been helping! You may have spent a few days instead figuring out why your seemingly identical setup couldn't reproduce the build... Not that I'm bitter about build systems or anything.

leejo 7y ago

> I don't want your entire life story in my commit log. I[1] want enough debug information in the commit log to be able to reproduce the issue without having to go on web hunts to understand the problem. Especially when the change appears to be trivial on the surface, because these are the ones that can turn out to be rabbit holes. I don't want to have to interrupt you to get this information because you didn't write a good enough commit message, and you probably don't remember anyway. I don't want go look at an external issue tracker that i may not have access to, or may not even exist anymore. [1] Where "I" is: me, your future self, a future maintainer, a junior dev, an open source contributor.

afiori 7y ago
> I don't want go look at an external issue tracker Related question: are there projects that use git itself as issue tracker?
- johnday 7y ago
  I can imagine that working to a degree: Make a fork of a commit at an issue, then merge that fork back in with master at point of fix. Bit of a mess in the tree though.
- _TwoFinger 7y ago
  https://news.ycombinator.com/item?id=13732598 https://news.ycombinator.com/item?id=13732598
- cipherboy 7y ago
  Pagure [0], Fedora's git forge, hosts code, issues, docs, and pull requests as four separate git repositories under the hood [1]. However, only project administrators can clone most of those repos. [0]: https://pagure.io/pagure https://pagure.io/pagure [1]: https://docs.pagure.org/pagure/usage.html https://docs.pagure.org/pagure/usage.html
- BlueTemplar 7y ago
  https://github.com/MichaelMure/git-bug https://github.com/MichaelMure/git-bug

mschwaig 7y ago

Generally speaking sure, there's no need to make things more complicated than they are, but the author even found some evidence in the history that indicates other people found this message useful. The powerful thing about this is having everyone put this kind of info in the same place IF they think it might be useful to the next person.

CGamesPlay 7y ago

Still, you've left out the details that you've confirmed that there's no other instances of this in our codebase. I'm also firmly in the "all commit messages should include a test plan" camp, so you should at least say how you found the error ("bundle exec rake was run before and after"). I get you're being terse for demonstrative purposes, but even eschewing verbosity we should still convey all the pertinent information.

EliRivers 7y ago

That's great for you. You don't want that. However, if you code in a team, doing everything for your own wants rather than considering the needs of the team (present and future) is just bad software engineering.

Cthulhu_ 7y ago

For critical applications, I for one would like to know the story behind a commit, preferably in the commit itself and not a reference to an external system like idk, Jira. My favorite examples of commit messages are the Linux kernel, where you can tell that they're being specifically crafted instead of just used as a work log to be ignored. This means that ten years down the line, people can still see when a change was made and why, who was involved, who signed off on it, etc. Have a look at the commits at https://github.com/torvalds/linux/commits/master https://github.com/torvalds/linux/commits/master

m_sahaf 7y ago

On the other end of the spectrum you get ImageMagick useless commit messages[0]. That extreme aside, I'd rather have commit messages that delve into the why-and-how the commit alters the behavior to the better rather than cryptic message as 'Replace invalid ASCII char'. Now we have documented reasoning and thought process that can aid future debugging. They can also be beneficial for new devs hacking on the project, or students learning how to implement and improve systems. Personally, I enjoy reading these. The Go commits often have commit messages like these, and they are shared on HN often for a reason. They're learning material. They can't go on a wiki because they're tied to particular set of changes in a particular point in history. They also can't be comments on the code because they're tied to particular lines in different files, and code comments can only cover a set of consecutive lines in one file. One recent example I could find is this[1]. Yeah, it fixes ^Z, but why didn't the old approach work? Why did it work for some time then didn't? How did it change? Why is this commit optimal, if it is? All of this along with scenarios to reproduce the issue. Give me your life story anytime over cryptic message. [0] https://github.com/ImageMagick/ImageMagick/commits/master https://github.com/ImageMagick/ImageMagick/commits/master [1] https://github.com/golang/go/commit/610d522189ed3fcf0d298609a248a3283bde62cd https://github.com/golang/go/commit/610d522189ed3fcf0d298609...

graton 7y ago
Agreed. When at some point the website that they are pointing to changes in the future they will lose all context on why a change was made. I believe in the "plane flying across the ocean without WiFi test" or basically anywhere without Internet access. If I am on a plane flying across the ocean without WiFi, do I have the information in the git commit to understand what happened. A git message that consists entirely of a link to a website is useless in that case.

DJHenk 7y ago

That's why most guidelines for commit messages prescribe a short description and an optional long description. The message in the article does not have a short description, which would have been easy to include. For that reason, it's not "My favorite Git commit message" either.

gwd 7y ago

> I don't want your entire life story in my commit log. I agree with this, but I think yours is too short. Scientific papers typically introduce enough information such that a person familiar with the field but not an expert in that particular area can understand generally what's going on. That's my ideal for a commit message as well: someone generally familiar with the codebase but who hasn't looked at this specific code (or perhaps not in a few months) should be able to understand what's going on; then the job of the reviewer is basically just verification. My "template" is normally something like: 1) What's the current situation 2) Why that's a problem 3) How this patch fixes it. So in this case, it might look something like this: --- Convert template to US-ASCII to fix error $functions use `.with_content(//)` matchers to do X. These matchers require ASCII content. The $foo template contains a non-ASCII space; this results in the following error: ArgumentError: invalid byte sequence in US-ASCII Fix this by replacing the non-ASCII space with an ASCII space. --- No need for a life story, but still searchable, and has enough information for even a casual contributor to do a useful review.

munk-a 7y ago
I really like that commit message - though it'd be nice to link to any sort of issue/task tracking ID that's relevant to that piece of work.

celticninja 7y ago

That belies the effort that went into the fix

nailer 7y ago

This is good, I'd add: > Replace invalid ASCII char. Fixes rake error 'invalid byte sequence in US-ASCII'. See #123 So people can get the life story if they want it.

acdha 7y ago
One downside to that approach: it requires your issue tracker to be stable for long periods of time. I've worked in a number of places where that's not true and you end up needing to figure out that the #123 linked by the system you're using now was actually #123 in the old system and was migrated as #456 in the current one. There's a balance here and I especially like that this commit message has enough information to make searches really easy should you need to do something like that.

marvin 7y ago

You can write the brief summary in the first 80 characters, like OP did. Then write details in the body below, in case someone needs the context. Most tools display only the first 80 characters unless you expand the body. This case is probably longer than necessary, but I've saved a day of debugging on multiple occasions due to someone (also myself) leaving some lines of context, reasons and reasoning after the high-level description.

JeffRosenberg 7y ago

Then use `git log --oneline` and you don't have to see the lengthy details, until the inevitable day when you find you need them.

AlexCoventry 7y ago
How do you surface them when you need them, though? git grep?
- esotericn 7y ago
  Sure? Or 'git log', then use the pager to search, or pipe into something with better fuzzy search, etc?
- JeffRosenberg 7y ago
  Git greps work if you're trying to search all the logs. I would think this detailed documentation would be most important when you're trying to understand a specific file or line of code. In that case, it's: - git blame (who wrote this?) - git show (look at the commit surfaced by blame)

jordigh 7y ago

> I don't want your entire life story in my commit log. Why not? Where else do you want it? Is something forcing you to read the full commit log? There's no length limit on commit messages and commit messages are mostly out of the way. Most VCSes have a way to only show you the first line. So if you want summaries, that's what the first line is for. If you want the full story, that's what the body is for. Combined with annotate/blame, commit messages can be very helpful source-level documentation. Nobody has ever complained about too much documentation, and commit messages are the perfect time to document what happened because it's one of the few times where our tools actually force us to write something in order to proceed. As long as we're being forced to write something, write something good and informative.

jmilloy 7y ago
I think the problem isn't the length or content of the commit message, but its organization. It needs to have the most important information first. It reads as an "entire life story" because it is written in a narrative, sequential form. Better organization would make it skimmable, and later coders could only read as far as they need to.
- YourMatt 7y ago
  If I'm searching commits, I'm trying to find record of what changed and when. I only want clues, and quick skimming is paramount. I want no personality. I want concise descriptive commit messages. That said, we reference an ID from our project management software with every commit, so once I find the commit I'm looking for, I can reference it back to external documentation. I still discourage personality there as well because it can get out of hand and clutter the comments, but it's more forgivable than being on the commit itself.
mattacular 7y ago
The pull request is a good place to put such a large amount of information. That would also be a good way to make sure it is seen by the broader team instead of burying it in commit history. You could make the argument that then it would not be part of the git history and therefore could be lost if you change hosts.

lazyant 7y ago

do you think a junior developer, or maybe somebody not vary familiar with Linux would not learn anything or benefit from reading those comments? Obvious point is that commit messages can be used besides what was done as a form of documentation and teaching tool (why, how).

EugeneOZ 7y ago

> I don't want Who cares. Hope you enjoy this tone - your was the same.

Supermancho 7y ago

I, too, would rate this a substandard git comment. Dave basically vomited a bug ticket of information, which is highly contextual and irrelevant ... like the lines he was faced with, which tell us nothing in the future nor anything we could not see in the change. The error is known, from the ticket being addressed. Documenting what error a bundler throws in the application deployment, within git seems...silly, since it will likely not apply to all points in time. That's why we have separate issue tracking. There was a whitespace encoding issue AND the developer didn't really understand the issue, since they ended with "One hour of my life I won't get back.". Over my 20 years, I've seen this EXACT scenario multiple times across multiple companies. Some jr engineer gets stuck with some troublesome weird error in a corner-case that ends up being a non-standard whitespace. It's a learning opportunity and he lamented it because it was different and nobody told him "we could stop this from happening again, generate a new issue". There are salient improvements that the git commit would benefit from both comment changes and additional code: 1. Include a (new) feature ticket that is linked to this issue - to create a process that doesn't allow for this again (eg fix a linter) 2. Include the name of the bug ticket (Convert template to US-ASCII to fix error) in the commit title, that was being addressed. 3. Create a test to specifically enforce the us-ascii encoding or add necessary rules to a linter.

nickm12 7y ago

I agree with the sentiment; this message is quite long for an invalid character in a file. House style in the companies I've worked for is to include a link to a bug report and or code review that provides more context for those who want it. Even without that added context, I'd rather know