Git Links is an unbelievably simple format for permalinks in the code. Imagine a file in your repo refers to mydoc.md:32. You specified the line because files can be large. But an edit to mydoc.md can ruin your link; it becomes misleading. GitHub links, in particular, have always had that problem. Git Links adds a hashlet to the line number, e.g. mydoc.md:32:eZ. That is a prefix of the git blob hash of that particular version of the file, in Base64. Now, any program can double-check whether the file has changed and what the link pointed at.
permalinks in code comments
The most basic implementation of Git Links can just parse git output. Some basic string matching and regexes can get you 80% there. To make things snappy in bigger repos, an implementation has to level up. Beagle Bee employs libdog and search indexes to cross-link arbitrary repos.
Either way, line-precise links become usable and useful.
FAQ
So :eZ is two symbols? Is that enough of a hash prefix?
Surprisingly, yes. That is 12 bits, which is enough to disambiguate revisions for most files. There is no birthday paradox: we pick the earliest match in the file's history. If 2 is not enough, use more symbols, 3 or 4.
Which tools support it?
Today, bee. Such links are clickable there, lead to the correct line. Tomorrow, who knows?
Would it work with jj?
Sure, if someone implements it. jj is git-compatible.
Can it reference a file in a different repo?
bee does that, just index that other repo.
LLMs will have infinite context, there is no need to point at a line.
We have 1M context window LLMs, but practitioners suggest using <250K. Everything above is what they call the "dumb zone". The more stuff you have in the context, the less control you have over it, the more unpredictable the outcome is. In any case, it is useful to know which part of the file we refer to.
Why don't we use section numbers? That works.
Sections get reordered and renumbered, same as lines.
We can use small Markdown files for everything, no need to mention the line.
In my experience, even Claude-generated ticket files are pretty long. Once all the context is in, they have tons of claims, facts and requirements. Those may contradict or mislead if the context is wrong. So, it makes sense to be more specific. That makes the outcomes less random.
Obsidian/OKF/Markdown-base solves that somehow.
Once you have a big dir of Markdown files, it gets even worse. Suppose you changed some decision and now you have contradictory claims in your knowledge base. Which one an LLMs sides with is random, every time. Links help to expose such broken connections.
Should I write these two symbols each time?
Nope. bee installs a git hook to perma-safe all new links.
