Source Permalinks

Source Permalink Reference

Golden Rule

Always use revision-pinned URLs in analysis documents. Never use trunk/tip/HEAD URLs.

When to Link

• Source files and functions (Firefox, Chromium, any open-source project)
• Specification sections (WHATWG, W3C, TC39, IETF, etc.)
• Bug reports (Bugzilla, GitHub Issues, Chromium Issue Tracker)
• Documentation pages
• Any other web-accessible resource

Anchor Text Rules

• Use function name, identifier, or short description as anchor text — not raw URL
• If citing a line range, use the starting line
• If no specific line known, link to file root
• Apply in all contexts: prose, tables, code snippets, plans

Searchfox (Firefox, WebKit)

URL Format

https://searchfox.org/{repo}/rev/{hash}/{path}#{line}
https://searchfox.org/{repo}/rev/{hash}/{path}#{start}-{end}

Repository Table

Revision Resolution Strategy

1. Get the local revision, then walk past any local-only commit. Checkouts that have an agent overlay installed carry an Install <X> overlay commit at the tip which adds only .claude/ / .codex/ and .gitignore and is never pushed upstream. Pinning to it makes every link dead. Because it touches no source file, the tree is byte-identical at its parent, so line anchors are unaffected:

   REV=$(git rev-parse HEAD)
   while git log -1 --format=%s "$REV" | grep -q '^Install .* overlay$'; do
     REV=$(git rev-parse "$REV^")
   done
   

2. Validate on searchfox using WebFetch, never curl: WebFetch https://searchfox.org/firefox-main/rev/{hash}/moz.configure
   • Renders source: use this hash for all links in the session
   • HTTP 500: searchfox does not know this revision — it is either local-only or not yet indexed. Fetch https://searchfox.org/firefox-main/source/moz.configure and extract the indexed revision from the page content.
3. Cache the validated revision for the entire session ($SHERLOCK_REV)
4. For ESR/beta branches: repeat with the appropriate repo ID

Never validate a permalink by HTTP status

A bare GET of any searchfox URL returns 200 carrying an anti-bot "Client Challenge" page, and searchfox returns 500 for a revision it does not know. So curl -o /dev/null -w '%{http_code}' reports 200 for a good revision and a dead one alike — it cannot tell them apart, and neither can any audit built on it.

This is not hypothetical. It let a nine-iteration RCA (bug 2054288) certify an analysis pinned to a local-only overlay commit, in which every code link rendered "Bad Revision", past five link-audit lanes and three citation-review passes. Two of those lanes reached opposite verdicts on the same three URLs and were never reconciled, so the bad citations survived as well.

Verifying permalinks

Resolve source citations against a local clone, not over HTTP. git show <rev>:<path> plus a line-range bound check validates the revision, the path and the line anchor in one step:

.claude/skills/source-permalinks/verify-permalinks \
  --repo <local-clone> [--repo <another-clone> ...] \
  [--expect-rev "$REV"] [--strict-rev] doc.md teams/*.md

--expect-rev refuses an overlay pin and reports citations on another revision as advisories, because history and archaeology docs legitimately pin to the commit they discuss — flagging those as errors is how a checker teaches its readers to ignore it. Add --strict-rev for a document that should be entirely on-pin, such as the analysis doc itself.

It covers searchfox, googlesource, GitHub, GitLab and Codeberg citations; falls back to HTTP only for non-source hosts (bugzilla, phabricator, spec sites), which do not bot-challenge; flags a Git SHA placed on a Mercurial host; and refuses an Install <X> overlay pin outright.

A rate-limited or unreachable non-source host (HTTP 429, 5xx, DNS failure) is retried and then reported as UNVERIFIED, never as a defect — it says nothing about whether the link is good, and counting it as broken teaches readers to discount real findings. Re-run those rather than editing the citation.

It checks transport and anchors, not meaning. A link that resolves to the wrong lines is still a defect, so follow the mechanical pass with a manual read confirming the cited lines support the citing sentence. Never report a citation audit as passing on transport alone.

Mercurial Hash Compatibility

https://searchfox.org/{repo}/hgrev/{hg-hash}/{path}#{line}

Automatically converts Mercurial hashes to Git revisions.

GitHub

https://github.com/{owner}/{repo}/blob/{hash}/{path}#L{line}
https://github.com/{owner}/{repo}/blob/{hash}/{path}#L{start}-L{end}

GitLab

https://{host}/{owner}/{repo}/-/blob/{hash}/{path}#L{line}

Known hosts: gitlab.xiph.org, code.videolan.org

googlesource.com

https://{host}/{repo}/+/{hash}/{path}#{line}

Known hosts: chromium.googlesource.com, aomedia.googlesource.com, webrtc.googlesource.com

Codeberg

https://codeberg.org/{owner}/{repo}/src/commit/{hash}/{path}#L{line}

Chromium Code Search

https://source.chromium.org/chromium/chromium/src/+/main:{path};l={line}

Note: source.chromium.org does NOT support revision pinning in URLs. For pinned Chromium links, use the googlesource.com mirror:

https://chromium.googlesource.com/chromium/src/+/{hash}/{path}#{line}

FFmpeg (via GitHub mirror)

https://github.com/FFmpeg/FFmpeg/blob/{hash}/{path}#L{line}

The Firefox moz.yaml revision maps to a git commit on this mirror.

Bugzilla

https://bugzilla.mozilla.org/show_bug.cgi?id={id}

Anchor text: [Bug {id}](URL)

Specifications

Trusted spec domains:

• html.spec.whatwg.org — WHATWG HTML Standard
• w3c.github.io — W3C specs (WebCodecs, MSE, EME, etc.)
• webaudio.github.io — Web Audio API
• tc39.es — ECMAScript
• datatracker.ietf.org — IETF RFCs
• www.rfc-editor.org — RFC editor
• itu.int — ITU-T codec specs (H.264, H.265)

Format: [Section Name](full URL with anchor)

Examples

Searchfox (revision-pinned): MediaDecoder::Shutdown

Searchfox (WebKit): MediaPlayer::pause

GitHub: nestegg_read_packet

GitLab: dav1d_decode

googlesource.com: vpx_codec_decode

Chromium (pinned via googlesource): MediaFoundationCdm::OnHardwareContextReset

Codeberg: SoundTouch::processRemainingFrames

FFmpeg: avcodec_send_packet

Spec: HTML Standard §8.5 — The media element

Bug: Bug 1234567