If you have access to any LangChain-supported LLMs, I’d really appreciate a quick test! Your feedback via GitHub Issues would be invaluable in improving the project.
Thanks in advance!
Needing a LLM to figure out what your staged work is doing is a real red flag.
> Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behavior.
• GOOD: “Fix app sending unnecessary requests"
• BAD: “Fixes app sending unnecessary requests”
> Another best practice to help you write good Git commit messages is to use imperative verb form. Using imperative verb form ensures that potential verbs used in your commit messages, like “fixed” or “updated” are written in the correct tense to “fix” and “updated”.
I insist on present tense, imperative mood in every codebase I work on. The Git log makes a whole lot more sense when it can be read this way.
https://git-scm.com/docs/SubmittingPatches#describe-changes
To be clear, the document does lead with:
> Please note that this information is only relevant to you if you plan on contributing to the Git project itself. It is in no shape or form required reading for regular Git users.
In spite of that qualifier, I think that the directions offered do apply extremely well as general guide, too.
> Your code may be clearly written with in-code comment to sufficiently explain how it works with the surrounding code, but those who need to fix or enhance your code in the future will need to know why your code does what it does. [...] You do not have to say "Currently"---the status quo in the problem statement is about the code without your change ...
I like to imagine myself writing an email to one of my colleagues about why we should be doing this change. I do not assume prior knowledge of my intention, but do assume contextual knowledge about the system.
Feature suggestions:
* Emit validated conventional commits. https://www.conventionalcommits.org/
* Create templated PR descriptions from multiple commits.
* Take the existing diff into account when you do a git amend.
Should you somehow find yourself in a situation where the above does not hold, and you really want the LLM description, it is still bad design to run the LLM on commit. LLMs will only get better over time. In that case you should not use commit messages but run the LLM on "git log" instead.
Just as it uses heuristics to show moved files it is also the more suitable place to summarize the diff, if that is all you place in the commit message field anyway. At that stage it has potential knowledge of the future as well, with that added context the summary might actually be useful ("this functionality is later replaced with ..").
But if it tamps down the holy wars of "pick a git comment style; be a dick about it" maybe there's value?
And as someone said, I often include the "why".
Some people might then say “use code comments”. But those inline comments won’t work when you have five years of source code change and those three lines deserve a cumulative seven comments.
But then this wouldn’t be a good application for a LLM so clearly that cannot be /s
But this reviews the commit message. Which might have merit.
There are projects where the commit messages are reviewed. And they may have guidelines written in prose for that somewhere. If the AI can be tuned on that then great, might save some human review time.
Git trailers are neat, but ultimately suffer from a UI issue: most people are using interfaces to git that don't use the plumbing, and they put all the important info in the first line (and sometimes have a frustrating cutoff of 50 characters) and git trailers are considered a remnant that gets no special handling (if you're lucky, the Co-Authored-By trailer has special handling, but that's about it).
If you're trying to quickly conceptualize why the history of a file is the way it is, then being somewhat consistent with scope labeling helps a lot.
In practice, the style will just be different depending on the project. A hobby project doesn't need a hypervigilant git history, given you're usually just using git as a special save button. A rebasing fork will probably want to structure it's commits more on a per-patch basis (since they should be kept on top of all other commits), so most conventional advice doesn't make sense (since the git commit in this situation also acts as the code comment for the patches; you're usually trying to keep patches as small as possible for ease of maintenance). It's when you get professional that you'll want a commit style.
It’s not git’s fault if you choose not to use git(1). Trailers work great with it. You can use other tools that claim some level of compliance with git, but you do so with the understanding that YMMV.
Ultimately git is a tool for version control and software collaboration, so what you end up doing should encompass the tools that people use. It's easier to find a compromise than to hardline on a position that requires a lot more upfront work (it's much harder to switch people off of software that they are familiar with than you might expect.)
The answer to "my tool doesn't render trailers" is not "let's waste the short message" it's "then don't use that crap tool"
- The kernel patch descriptions: https://kernelnewbies.org/PatchPhilosophy. Used by the repository that Git was created for (the Linux kernel) and Git itself;
- Gitmoji: https://gitmoji.dev/, similar to conventional commits but using emoji
Personally we may like them or not. But again, even though I don't like it, I would a history with "<bug emoji>: do foo in bar" instead of a history with a lot of commits only named "fix", "now it works" and things like that.
> Personally we may like them or not. But again, even though I don't like it, I would a history with "<bug emoji>: do foo in bar" instead of a history with a lot of commits only named "fix", "now it works" and things like that.
It is good to have standards which will disqualify low-quality commit messages.
So, it is not for you anyway, as the problem it solves is already solved for you.
Sure you could improve it by emphasizing the 'why' of the commit, but what I see is a great start.
Though for that I use the AI git message button in Cursor these days. But you don't need to be a noob vibe coder to find it useful.
The haters all have github repos where they've resorted to low quality commit messages at least from time to time.
It might be useful to decorate a repo that lacks commit messages with synthetic guesswork.