Contextual commits – An open standard for capturing the why in Git history
vidimitrov.substack.com
Contextual commits – An open standard for capturing the why in Git history
1–10 of 39 posts
Re: Contextual commits – An open standard for capturing the why in Git history
#2It continually amazes me how averse people are to just explaining why a commit exists in the body of the commit. Is all this tagging actually easier to read than written prose? You don’t even have to write it anymore if the sight of your editor opening upon `git commit` causes some instinctual revulsion.
Re: Contextual commits – An open standard for capturing the why in Git history
#3Would be curious to know if it works better than writing the Why as human-friendly paragraphs in the body of the commit message.
Re: Contextual commits – An open standard for capturing the why in Git history
#4Would be curious to know if it works better than writing the Why as human-friendly paragraphs in the body of the commit message.
A few examples are the ability to query historical data and using each action line as a signal for other tooling to build on top but there are many others… you can check what Conventional Commits did in the past and what they unlocked only by introducing structure to commit subjects
Re: Contextual commits – An open standard for capturing the why in Git history
#5> an open standard for capturing the WHY in git history
Agentic coding keeps reinventing coding.
That was my first thought.
> And then it hit me - the commit body has always been there. Completely underutilised.
Wait. What? This is the standard?
> Here is an example of how a Contextual Commit looks:
The format is key-value stuff. You can already use trailers for that. The syntax here doesn’t work with that stuff.
If you have already readh the “conventional commits” (pronounce with a sneer) specification you have already seen them. They’re called footers because they also didn’t know about trailers.
> No new tools. No infrastructure. Just better commits.
Okay, let’s cut right to the point..
Re: Contextual commits – An open standard for capturing the why in Git history
#6It continually amazes me how averse people are to just explaining why a commit exists in the body of the commit. Is all this tagging actually easier to read than written prose? You don’t even have to write it anymore if the sight of your editor opening upon `git commit` causes some instinctual revulsion.
The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more noise, since all they need is just the diff to reconstruct the WHAT.
I've never seen someone write decisions or the intent they started with in commit messages. Even the solutions today that auto-generate commit messages just summarise the diff.
This was helpful when humans were the only ones reading the history. But for agents its useless.
Re: Contextual commits – An open standard for capturing the why in Git history
#7> an open standard for capturing the WHY in git history Agentic coding keeps reinventing coding. That was my first thought. > And then it hit me - the commit body has always been there. Completely underutilised. Wait. What? This is the standard? > Here is an example of how a Contextual Commit looks: The format is key-value stuff. You can already use trailers for that. The syntax here doesn’t work with that stuff. If…
Trailers were not suitable for the use case.
The scope in parentheses is doing real work. `rejected(oauth-library)` lets you do `git log --grep="rejected(auth"` to find every rejected auth decision across history.
If you flatten it to a trailer token you either lose the scope or encode it awkwardly as `Rejected-auth-oauth-library: value`, which doesn't grep cleanly and doesn't parse naturally.
Re: Contextual commits – An open standard for capturing the why in Git history
#8> an open standard for capturing the WHY in git history Agentic coding keeps reinventing coding. That was my first thought. > And then it hit me - the commit body has always been there. Completely underutilised. Wait. What? This is the standard? > Here is an example of how a Contextual Commit looks: The format is key-value stuff. You can already use trailers for that. The syntax here doesn’t work with that stuff. If…
Trailers were not suitable for the use case. The scope in parentheses is doing real work. `rejected(oauth-library)` lets you do `git log --grep="rejected(auth"` to find every rejected auth decision across history. If you flatten it to a trailer token you either lose the scope or encode it awkwardly as `Rejected-auth-oauth-library: value`, which doesn't grep cleanly and doesn't parse naturally.
The format is optimised for agent querying and human readability in `git log`, not for `git interpret-trailers` compatibility. Those are different use cases.
Re: Contextual commits – An open standard for capturing the why in Git history
#9It continually amazes me how averse people are to just explaining why a commit exists in the body of the commit. Is all this tagging actually easier to read than written prose? You don’t even have to write it anymore if the sight of your editor opening upon `git commit` causes some instinctual revulsion.
The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more noise, since all they need is just the diff to reconstruct the WHAT. I've never seen someone write decisions or the intent they started with in commit messages. Even the solutions today that auto-generate commit messages just summarise the diff. This was helpf…
> I've never seen someone write decisions or the intent they started with in commit messages
You may not have seen enough good repos. The following is an example commit from freebsd
https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f903...
A proper email is like an email. You have the first line as the subject and it may be enough to explain the intent of the diff. But sometimes it’s not enough and you add more details in the body. I strongly believe that people who write the WHAT again don’t know that there’s a diff attached to the commit and think of them a separatete objects. GitHub and VSCode do not really help in that regard.
Re: Contextual commits – An open standard for capturing the why in Git history
#10> intent(auth): users need social login, starting with Google before GitHub and Apple
Your 'intent' is 'users need social login'? That does not make sense.
Your intent is 'Getting more users by lowering barriers to sign up', a business goal. That business goal might have hierarchical children – for example, Jira epics – such as 'offer social sign-in', or 'declutter landing page.'
Also, the commit mentions 'Google before GitHub', but how can a commit (a snapshot of the repository) know the future? What if your product manager decides Google is fine enough and GitHub/Apple aren't needed?
I wish our profession would stop trying to reinvent issue tracking in git every week.