Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

My favourite Git commit (2019)

dhwthompson.com

Post reply on HN
Print view View original

101–110 of 406 posts

Re: My favourite Git commit (2019)

#101

Post by Sohcahtoa82 »

fusslo wrote: post #25

great commits are great. This is fantastic As an aside, I'm tired of documenting: - in code - in commits - in jira - in confluence - in daily standups - in release notes

- in Sharepoint

- in some random Google Doc owned by one person that has to give permission to each individual who needs to read it, even though it's something the entire Engineering department should have access to.

- in a GitHub Wiki that nobody even realizes exists

- in a separate git repo that exists for just documentation, but nobody has checked anything into for 2 years

Re: My favourite Git commit (2019)

#102

Post by goku12 »

adrianmsmith wrote: post #24

I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. (I mean you could obviously with "rebase" but are you really going to alter something written one year ago, already merged to "main", and cause a bunch of pain with everyone's feature branch etc.?) Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleag…

Commit messages aren't a replacement for source documentation. The latter contains information relevant to the tree. Commit messages are transient information (historical info as someone put it). For example, an update caused by outdated dependency. Or the tests done to diagnose a bug.

Re: My favourite Git commit (2019)

#103

Post by DarkNova6 »

herrkanin wrote: post #74
ep103 wrote: post #69

Earlier quoted context omitted.

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…

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?

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.

Re: My favourite Git commit (2019)

#104

Post by [deleted] »

schacon wrote: post #71
codemac wrote: post #65

Earlier quoted context omitted.

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 late…

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 ev…

[deleted]

Re: My favourite Git commit (2019)

#105

Post by hatsix »

gumby wrote: post #64

That first line of the commit message is most important so that `git log` can address chesterton's fence. And IMHO in this case the committer whiffed. The key is not to put what you did in that first line, but why . Anyone interested in what can just look at the code, perhaps via a diff. So something like "nginx .conf files must be in us-ascii" Then "changed blahblah.erb to remove nonbreaking space character" Then th…

Nah, first line needs to be a summary of what you changed, so that you can find the offending commit in the first place.

A news article doesn't explain WHY in the headline, it explains what.

In this case, the OP's first line is spot on... if you're reading through git log, you can see that this commit likely didn't change anything functional about a test, and you should move on.

Re: My favourite Git commit (2019)

#106

Post by boolemancer »

WalterBright wrote: post #36

At the DLF, our pull requests are usually accompanied by a link to the bugzilla entry, which usually have a detailed explanation. P.S. Having multiple Unicode values that exhibit identically when displayed are a huge veer-into-the-ditch mistake. I.e. the notion that code points should have semantic value is simply wrong.

> P.S. Having multiple Unicode values that exhibit identically when displayed are a huge veer-into-the-ditch mistake. I.e. the notion that code points should have semantic value is simply wrong.

Should a cyrillic `а` and a latin `a` have the same code point?

If they did then there's no consistent way to group those two alphabets, one or the other would end up with letters outside it's main grouping.

And what happens if the shapes of those two characters divege over time? Do you have a breaking change to introduce a new code point for one of the languages, or do you just make it impossible to have a font that can be used for both latin and cyrillic at the same time?

This isn't just a theoretical problem, by the way. There are characters in Chinese and Japanese that share a code point but the shapes of the characters aren't the same in the two languages.

Re: My favourite Git commit (2019)

#107

Post by js2 »

schacon wrote: post #61

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" pro…

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.

Re: My favourite Git commit (2019)

#108

Post by zaptheimpaler »

schacon wrote: post #61

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" pro…

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

Re: My favourite Git commit (2019)

#109

Post by bradjohnson »

brabel wrote: post #92
schacon wrote: post #61

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" pro…

> 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 feel…

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.

Re: My favourite Git commit (2019)

#110

Post by goku12 »

schacon wrote: post #61

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" pro…

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.
Post reply on HN