Git Overhauls Documentation with New Data Model and User-Tested Revisions
Git introduces new data model document clarifying core concepts, and updates man pages based on feedback from 80 test readers.
Breaking: Git Documentation Gets Major Overhaul with New Data Model
Git’s official documentation has been updated with a new “data model” document that clarifies how core concepts like objects, references, and the index relate to commits and branches. The changes were driven by contributions from Julia Evans and Marie, and incorporate input from 80 volunteer test readers who identified confusing terminology and unclear explanations.
“Understanding how Git organizes its commit and branch data has really helped me reason about how Git works over the years,” said Julia Evans, a contributor to the Git documentation. “Now there’s a short, 1600-word version of the data model that’s accurate and accessible.”
The new data model document defines terms like “object,” “reference,” and “index” in plain language, directly addressing a gap Evans noticed while working on the documentation. She added that getting the accuracy right was challenging—especially regarding how merge conflicts are stored in the staging area—but the final version is now available for public review.
In addition to the data model, the team revised the introductory pages for git push, git pull, and other core man pages. Rather than relying on subjective judgments by expert users, Evans recruited test readers via Mastodon to identify real-world pain points. “Expert users of a piece of software are notoriously bad at judging whether an explanation will be clear to non-experts,” she explained. “So I needed an evidence-based approach.”
Background
The documentation project began in fall 2024 when Evans decided to contribute directly to Git’s official docs instead of just writing blog posts or zines. Early work revealed that while Git documentation frequently uses terms like “object,” “reference,” and “index,” it lacked a clear, cohesive explanation of their meanings and relationships.
Evans and Marie collaborated to write the data model document from scratch. During the review process, they discovered subtle details—such as how the staging area stores merge conflicts—that required revisions to ensure accuracy. The document is currently hosted on a separate site but is expected to appear on the official Git website after the next release.
Test readers provided feedback on everything from unclear pathspec definitions to the specific meaning of “upstream” in Git. The team used this data to refine man pages, replacing arguments between experts with concrete evidence of what users actually found confusing.
What This Means
For Git users, this overhaul means better, more approachable documentation that explains foundational concepts before diving into commands. The data model document gives both beginners and experienced developers a concise reference for how Git stores commits, branches, and other objects internally. The user-tested revisions to man pages should reduce confusion around common operations like pushing and pulling.
Open-source documentation often suffers from a gap between what experts think is clear and what newcomers need. By combining technical accuracy with real-world reader testing, this update sets a new standard for how projects can improve their guides. As Evans noted, “It’s important to have a short version of the data model that’s accurate.”
For more background on the changes, see the Background section above. To read the full data model document, visit the temporary hosting page until it’s integrated into the official Git site.