← Back to all postsGit Notes as a Tool for Thought
Published ....
Last modified ....
Share this post on BlueskySee discussion on Bluesky
While flying back out to the west coast for a week and a half "workation" - I stumbled across a brief tweet talking about git-notes. For those that don't know (and don't care to read through Git docs), git notes is a way to track additional free form content associated with commits, without editing/amending the underlying commit. From what I can tell - these are tracked separately from commits, but Git knows how to connect them behind the scenes.
While there's been other great blog posts about git notes (like this one that I recommend checking out), I wanted to write a bit about a failed idea to use this little used feature as a way to store a daily journal of sorts.
The rough idea was:
- Create a single commit for each day (formatted nicely)
- Append notes to that commit through out the day (as you see fit)
- Each of the appended notes stashes the time at which the note was added, e.g.
9:15AM ET
And that's it! Plain and simple!
I was able to stub out a quick and very dirty Bun-flavored JavaScript snippet that could expose a simple CLI to manage these notes:
// bun note.ts "something"
// bun note.ts show
import
{
readableStreamToText
}
from
"
bun
"
;
// git notes append --separator="\n---\n ### ${timestamp nicely formatted}"
// commit each day
// check if there is a commit for today or not
// if not, create a commit
// parse params
let params = Bun.argv.slice(2);
if (params.includes("show")) {
let { stdout } = Bun.spawn(["git", "notes", "show"]);
let text = await readableStreamToText(stdout);
console.log(text);
process.exit(0);
}
let message = params.join(" ");
let dayFormatter = new Intl.DateTimeFormat("en-US", {
year: "numeric",
month: "2-digit",
day: "2-digit",
}).format;
let timeFormatter = new Intl.DateTimeFormat("en-US", {
hour: "2-digit",
minute: "2-digit",
}).format;
let day = dayFormatter(new Date());
// check if current commit message matches the current date
let res = Bun.spawnSync(["git", "log", "-1", "--pretty=%B"]);
let commitMessage = res.stdout.toString();
if (!commitMessage || !commitMessage.includes(day)) {
Bun.spawn(["git", "commit", "--allow-empty", "-m", day]);
Bun.spawn(["git", "notes", "add", `\# ${day}`]);
}
Bun.spawn([
"git",
"notes",
"append",
`--separator=\n\n---\n\n \#\#\# ${timeFormatter(new Date())}`,
"-m",
JSON.stringify(message),
]);
I've also pushed this script up to a repo here
if you want to mess around with the concept more!
This is very naive - and probably has a number of issues - but seemed to work alright in some of my testing.
I called this a failed experiment because git notes feels incredibly "underbaked" compared to other git features. Maybe underbaked isn't the right phrase, but it's seen such low adoption that most tools don't support it, and it seems to break in some cases.
- Notably - GitHub doesn't offer a way to see notes associated with commits in the web ui
- You need to manually push and fetch these notes (kind of like tags) if you're sharing them with others
- (probably a me problem) The version of Git by default on my mac (AppleGit) somehow didn't support most of the features - I had to
brew install git to get the latest version with support for git notes append!
- Amending a commit (even if not editing the message), will blow away all your notes!?
Anyway - it was an interesting little adventure to try out, but I think I'll be sticking with Obsidian for the time being, plus there have been quite a few useful git-backed note taking solutions out there that would work better.
Tags:
Related Posts
Development
I've once again updated my personal website, this time powered by my own RSC framework and a custom CMS solution as well!
Are we reinventing the wheel when it comes to onboarding new AI agents to a codebase, when we already have primitives available for onboarding humans?
A quick tip for creating roundup or summary notes based on other notes in Obsidian using the Dataview plugin!
Have you ever found the need to change the image you render on a web page based on the current preferred color scheme of your theme?
I recently launched a rewrite and redesign of this personal website, I figured I'd talk a bit about the changes and new features that I added along the way!
A quick tip outlining how to provide specific TypeScript type definitions for a local module!
Slicing software: why vertical is better than horizontal.
What if you could author an entire web application in a single file?
Is it a good or a bad thing to offload writing code to AI agents and Large Language Models?
A brief look at Import Maps and package.json#imports to support isomorphic JavaScript applications!
A collection of tech talks that I regularly re-watch and also recommend to everyone!
Some features and functionality that I'd like within a React Server Component compatible framework.
A (running) collection of Bluesky tips, tools, packages, and other misc things!
How to generate a custom Ghostty theme based on any iterm2 theme!
A rough mental model for how you should be leveraging AI as a tool for your own growth
Even more thoughts on dogfooding!
The secret to excellent product teams is using your own product, and often!
A quick look at the applications and tools that I (generally) use day to day for web development!
There's a common gotcha when creating Web Request and Response instances with Headers!
Feature toggles are often underused by most software development teams, and yet offer so much value during not only feature development but also refactors
A quick introduction to my new side project, hohoro. An incremental JS/TS library build tool!
webpack, and tools built on it like Next.js, don't support true dynamic imports, but I found a way to trick the system!
I've been using a variety of AI tools as of late, I figured I'd document the ones I'm primarily using!
I've started to use Cloudflare to manage my domains for several side projects, have had to jump through the same hooks multiple times that I figured I should document them here!
Revising my previous blog post on React Error Boundaries and my preferred go-to implementation!
Two neat tricks for enhancing your site's favicon!
The various risks and pitfalls of open source software run by corporations.
A monorepo template for managing a library and documentation together.
How we solved an almost show-stopping production bug, and how you can avoid it in your own projects.
When did semver major changes become so scary?
No I don't mean those Milano cookies you keep taking from the office snack wall either (although you should probably stop snacking on those as often as well).
Pair programming can be good sometimes - but not all the time
A few quick thoughts on burn out and taking a break
Git