THE GITHTML FIELD GUIDE
Share a GitHub document at an exact revision
Use GitHub’s permanent-link feature when a discussion must refer to the exact text you reviewed. A branch URL can change as new commits arrive; a commit-based URL identifies a recorded version. Include the repository path and purpose beside the link so the recipient understands both the evidence and its scope.
Decide whether the link is evidence or a doorway
A link labeled current setup guide should normally lead readers toward maintained instructions. A link supporting a review finding should identify the precise historical text. Those jobs are different, and a single unlabeled URL often serves neither well.
Before copying a link, decide whether the reader needs the latest instructions or the version behind a particular decision. For long-lived notes, provide both, clearly labeled as reviewed snapshot and maintained guide.
Capture the immutable reference
Open the file on GitHub and use the permanent-link mechanism documented by GitHub. The resulting URL uses a commit identifier in place of a moving branch reference. If you highlight lines, verify that the selected range contains the full condition or warning you intend to discuss.
After copying the URL, open it in a new tab. Check the filename, displayed revision, and surrounding text. This small check catches links copied from a different branch or neighboring file.
- Open the intended file and revision on GitHub.
- Copy its permanent link and reopen the copied URL.
- Label the link as a reviewed snapshot and state what it supports.
Add enough context for the next reader
A useful review note says what the linked passage establishes. For example: the reviewed snapshot describes a thirty-minute token lifetime; the proposed implementation uses a different value. Keep the reasoning in your own words rather than expecting a line link to communicate the entire issue.
Also include the product or release context. A permanent source link preserves a document revision, but it does not independently establish which released software version that document accurately describes.
Remember the access boundary
A permanent link does not make a private repository public and does not grant the recipient access. Ask a colleague to confirm access before making the link the sole evidence in a handoff. Never solve an access issue by casually changing repository visibility.
For an offline packet, store a permitted reading copy and retain the permanent source link as provenance. The link is useful when connectivity returns, but it is not a substitute for the actual document being available locally.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.