3 ms·

I do feel like Git commit descriptions are severely under-utilised for sure, but I believe there is a reason for that which until fixed, will prevent rich and c

I do feel like Git commit descriptions are severely under-utilised for sure, but I believe there is a reason for that which until fixed, will prevent rich and contentful commit descriptions for flourishing. In the article order: the screenshot is from a commit detail page. How often do you land on this page? You need to specifically click through. If you are in a commit list, the only thing that sets title-only commits and commits with description apart is an ellipsis link which practically blends in with the background. It is not very well integrated nor discoverable. Also I don't believe the commit descriptions render as MarkDown (unlike issues) which is also a shame as it feels like less a doc then. But I might be wrong on this. But even outside of GitHub, how many other UI/IDE plugins and other kinds of Git tools restrict commit display to just the title and put the description on the sideline? Most of them. I think this further leads to the currently low value of the commit message being searchable. Since it is exceedingly rare for good commit messages to exist, no one thinks to search them. People default to Google, when their own project's codebase/knowledge base could hold the answer to their query. I don't have much of an opinion on the commit message telling a story / having a human touch. I mean, it doesn't hurt I guess, but until _full_ commit messages become more "mainstream" (for a lack of a better word), they can be as human as they can, but they will live in solitude.

Darkstryder 7y ago
In the same vein, I wish there would be a standard workflow for putting code inside commit logs. The typical use case would be database migration scripts : IMO they are always a pain to version properly because fundamentally Git and all the other software versioning tools let you describe the "nodes" (in the graph theory sense of the word) of a codebase ("at commit A the code was in this state, at commit B it was in the other state"), but severely lack when it comes to describe the edges between nodes ("in order to go from state A to state B, you need to execute this code") I think the temporal dimension of software engineering is still poorly understood, and severely undertooled.
- codegladiator 7y ago
  > when it comes to describe the edges between nodes ("in order to go from state A to state B, you need to execute this code") Isn't that what a patch file gives ?
  - esotericn 7y ago
    The patch file gives the output of the execution of the code. A basic example would be - run 'find -name '*.py' -execdir sed -i 's/foo/bar/g' +' on a repo, and commit the result. For those not familiar with POSIX shell stuff, that will find and replace 'foo' with 'bar' across the repo. The command is far more understandable at a glance than the patch (commit) and is far more likely to be reviewed properly.
  - Darkstryder 7y ago
    Sometimes no. For instance a database migration script is not equivalent to the diff between two database creation scripts. While it should be possible to take a database creation script (state A) and a database migration script (edge A->B) and infer the new resulting database creation script (state B), the reverse is not true. This is the tables vs events duality described in this great article : https://engineering.linkedin.com/distributed-systems/log-what-every-software-engineer-should-know-about-real-time-datas-unifying https://engineering.linkedin.com/distributed-systems/log-wha...
- esotericn 7y ago
  Strongly agree. I run into this a lot with stuff like style commits. You want to ensure that a change hasn't slipped under the radar. I tend to go for something like: This commit was generated. <shell script here> It would be super awesome to have a tool that easily verifies that A->B can actually be reproducibly accomplished by performing the actions in the commit message.
- kps 7y ago
  A few version control systems are change-based rather than snapshot-based — darcs¹ and pijul² that I know of. ¹ http://darcs.net/ http://darcs.net/ ² https://pijul.org/ https://pijul.org/
- shrimpx 7y ago
  How do DB migrations relate to the source control graph? It seems you're implying the codebase changed as a result of a script that itself is not source controlled. I can think of style commits falling in this category, like one of the children of this comment mentions, but DB migrations don't seem to be related.
ryukafalz 7y ago
Where they're really valuable, IMO, is when you're tracking down when/why a change was made with `git blame`. When you're looking for the reasoning behind a change, it's extremely helpful if there's a detailed commit message going along with it.
jmiserez 7y ago
If only important/tricky commits have long messages it's fine. Most IDEs will show you the full text if you hover over the line, so when working on something it's easy enough to check them. I'm huge fan of the timemachine-like "Show Git History for Selection" view that IntelliJ has, so usually there's no reason to go to a Github/Gitlab commit page.

Darkstryder 7y ago

In the same vein, I wish there would be a standard workflow for putting code inside commit logs. The typical use case would be database migration scripts : IMO they are always a pain to version properly because fundamentally Git and all the other software versioning tools let you describe the "nodes" (in the graph theory sense of the word) of a codebase ("at commit A the code was in this state, at commit B it was in the other state"), but severely lack when it comes to describe the edges between nodes ("in order to go from state A to state B, you need to execute this code") I think the temporal dimension of software engineering is still poorly understood, and severely undertooled.

codegladiator 7y ago
> when it comes to describe the edges between nodes ("in order to go from state A to state B, you need to execute this code") Isn't that what a patch file gives ?
- esotericn 7y ago
  The patch file gives the output of the execution of the code. A basic example would be - run 'find -name '*.py' -execdir sed -i 's/foo/bar/g' +' on a repo, and commit the result. For those not familiar with POSIX shell stuff, that will find and replace 'foo' with 'bar' across the repo. The command is far more understandable at a glance than the patch (commit) and is far more likely to be reviewed properly.
- Darkstryder 7y ago
  Sometimes no. For instance a database migration script is not equivalent to the diff between two database creation scripts. While it should be possible to take a database creation script (state A) and a database migration script (edge A->B) and infer the new resulting database creation script (state B), the reverse is not true. This is the tables vs events duality described in this great article : https://engineering.linkedin.com/distributed-systems/log-what-every-software-engineer-should-know-about-real-time-datas-unifying https://engineering.linkedin.com/distributed-systems/log-wha...
esotericn 7y ago
Strongly agree. I run into this a lot with stuff like style commits. You want to ensure that a change hasn't slipped under the radar. I tend to go for something like: This commit was generated. <shell script here> It would be super awesome to have a tool that easily verifies that A->B can actually be reproducibly accomplished by performing the actions in the commit message.
kps 7y ago
A few version control systems are change-based rather than snapshot-based — darcs¹ and pijul² that I know of. ¹ http://darcs.net/ http://darcs.net/ ² https://pijul.org/ https://pijul.org/
shrimpx 7y ago
How do DB migrations relate to the source control graph? It seems you're implying the codebase changed as a result of a script that itself is not source controlled. I can think of style commits falling in this category, like one of the children of this comment mentions, but DB migrations don't seem to be related.

ryukafalz 7y ago

Where they're really valuable, IMO, is when you're tracking down when/why a change was made with `git blame`. When you're looking for the reasoning behind a change, it's extremely helpful if there's a detailed commit message going along with it.

jmiserez 7y ago

If only important/tricky commits have long messages it's fine. Most IDEs will show you the full text if you hover over the line, so when working on something it's easy enough to check them. I'm huge fan of the timemachine-like "Show Git History for Selection" view that IntelliJ has, so usually there's no reason to go to a Github/Gitlab commit page.