THE GITHTML FIELD GUIDE
Map an unfamiliar documentation repository before reading
Start by identifying the repository, revision, documentation directories, and intended audience. Then build a small reading map around your immediate task. A repository tree tells you where files live, but a useful reading order comes from distinguishing introductions, procedures, reference material, and generated output before opening everything.
Name the question you came to answer
Write one sentence describing the outcome you need, such as understanding authentication or preparing an upgrade. This keeps a large file tree from becoming an undirected reading session. Also note the product version you actually use; an excellent guide for the next release can still be the wrong guide.
Find the repository’s introductory document and any documentation index. Read them for orientation, even when your eventual reading copy will be HTML. gitHtml indexes .html files, not Markdown sources.
Inventory without changing the checkout
From the repository root, run git ls-tree -r --name-only HEAD -- docs to list tracked paths under docs at the current commit. Replace docs with the actual documentation directory. This reads Git’s recorded tree; it does not include uncommitted files that exist only on your machine.
Group the results by apparent role: tutorials, operations, API reference, design decisions, and generated pages. Record surprising duplicates rather than assuming that the shortest path is authoritative.
git ls-tree -r --name-only HEAD -- docsCreate a three-stop reading route
Choose an orientation page, one task-specific page, and a reference page that answers likely follow-up questions. For an authentication review, the route might be overview.html, token-lifecycle.html, and error-codes.html. Explain why each belongs in the route using a sentence beside its path.
Keep a separate list of unanswered questions. A useful map exposes missing documentation instead of pretending every folder needs to be read. Ask the owner about unclear authority before relying on contradictory instructions.
Check the route in the destination reader
Open every chosen HTML file and inspect its title, version, headings, and essential examples. If an index links to neighboring files or remote diagrams, verify those destinations separately. A visible index is not proof that the entire linked collection has been saved.
Your finished map should contain the repository identity, commit or release, three starting paths, and the unresolved questions. Share that compact handoff with another reader and ask whether they can locate the same procedure without extra explanation.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.