My rule for any developer doc is: don't tell me what, tell me WHY
My favourite Git commit (2019)
141–150 of 406 posts
Re: My favourite Git commit (2019)
#142Earlier quoted context omitted.
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.
Hard disagree. There's little reason to search the text of commit messages to find out what changed. There are many git tools to find out which commits affected parts of the code you're interested in. Whereas, trying to find that in commit messages is really inefficient and relies on reading, rather than such automated tools. The purpose of the commit message is to help our fellow humans get a higher level understand…
Totally agree with you.
We already know what changed: it's the diff! We need to know why you're making the what.
The message should address why the diff is necessary. Was it a bug fix? Ok, what's the bug you're fixing? What's the evidence that you think they diff addresses it? Is it a new feature? What's the requirement? I can already tell what you did by the diff, but I can't tell from the diff alone if it actually matches the requirement!
Re: My favourite Git commit (2019)
#143For 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…
I was mind blown reading this also - are we not programmers for the sake of laziness in the face of these kinds of "problems"? I have to hail Tim Pope for Fugitive.vim also. HAIL TIM POPE!
Re: My favourite Git commit (2019)
#144Just an aside: is there a vim syntax command to highlight weird unicode whitespace as an error? Something like: syn match unicodeWhitespace /[list of unicode whitespace]/ hi def link unicodeWhitespace Error
For non-breaking spaces specifically, there is :help 'list'.
Re: My favourite Git commit (2019)
#145Just an aside: is there a vim syntax command to highlight weird unicode whitespace as an error? Something like: syn match unicodeWhitespace /[list of unicode whitespace]/ hi def link unicodeWhitespace Error
I wouldn't know about the Vim equivalent, but I wrote this in my Emacs config long ago: (defun find-non-ascii () "Find and show all of the non-ascii characters." (interactive) (occur "[[:nonascii:]]")) It has proved quite useful on occasion. (Yes, I could just invoke Occur directly, but I can never quite remember the regexp character class and syntax here.)
No worries. I managed to whip something up:
autocmd BufWinEnter * match ErrorMsg /[\xa0\u1680\u2000-\u200a\u202f\u205f\u3000]/Re: My favourite Git commit (2019)
#146For 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 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…
This is the problem with any kind of documentation; while you can write the highest quality, meticulous, most obvious and clearest prose, it's moot if nobody reads it.
And nobody reads it because there's so much of it and there's no clear starting point. People just want the summary of what they're looking for.
I started to learn Java almost 20 years ago, we had a text book and everything. After the first two chapters, I learned how to google and instead of reading everything, just find what I need. I never went in-depth with reading because... it's mostly useless knowledge that quickly becomes outdated.
Re: My favourite Git commit (2019)
#147Earlier quoted context omitted.
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...)
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 blo…
Is it possible that you’ve been hit by
?
git log | less
/whatever
Re: My favourite Git commit (2019)
#148For 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 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).
Re: My favourite Git commit (2019)
#149Earlier quoted context omitted.
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.
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.
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. :)
Re: My favourite Git commit (2019)
#150Earlier quoted context omitted.
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.
Hard disagree. There's little reason to search the text of commit messages to find out what changed. There are many git tools to find out which commits affected parts of the code you're interested in. Whereas, trying to find that in commit messages is really inefficient and relies on reading, rather than such automated tools. The purpose of the commit message is to help our fellow humans get a higher level understand…
I've never thought about it this way.
I've always used it as a summary, so I can understand what has been done when browsing the history. It allows me to find changes that I want to cherry-pick or revert. OTOH I can see benefit of describing why a change was done as the summary, as then git blame on the line is a lot more effective.