THE GITHTML FIELD GUIDE
Choose branch, tag, or commit references for documentation
Use a branch reference for an evolving body of work, a release tag for a named milestone, and a full commit identifier for an exact snapshot. Record which meaning you intend. These are source-reference choices, not a promise that a reading app provides a branch-switching interface or imports every revision.
Start with the reader’s time horizon
A new teammate setting up the current development environment probably needs maintained instructions. Someone investigating a two-year-old incident needs the contemporaneous document. Write that time horizon before selecting a convenient link from the repository’s default view.
The wrong reference can produce misleading confidence: the page may be accurate and well written, yet describe a system that did not exist at the time being discussed. Documentation freshness must be judged against its intended target.
Understand the reference labels
A branch is a named reference that commonly advances as work lands. A tag gives a name to a chosen point, often a release. For strict traceability, record the resolved commit as well, because a friendly label alone is weaker evidence of the exact content reviewed.
Use git rev-parse HEAD to see the current commit, or git rev-parse 'v2.4.0^{commit}' to resolve an existing release tag to its commit. Substitute a tag that actually exists in your repository.
git rev-parse HEAD
git rev-parse 'v2.4.0^{commit}'
git ls-tree -r --name-only v2.4.0 -- docsKeep version selection separate from file selection
A correct revision is only half the address. You also need the documentation path at that revision. A guide may have moved between releases, and a current path may not exist in an older tree.
Inspect the relevant tree with git ls-tree -r --name-only v2.4.0 -- docs. This is a read-only inquiry. You do not need to switch branches, replace local files, or discard work to identify an older document’s location.
Write a reference policy people can follow
For your team, a short policy might say: onboarding links follow the maintained branch; release checklists name the release tag and resolved commit; investigation notes use commit-specific links. Add an owner for deciding exceptions.
When distributing HTML copies, put the source revision and supported product version inside the document. Readers may encounter the file without its original folder or message. Embedded provenance is more durable than a filename such as latest.html.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.