A data model document for Git

Working on Git's documentation this past fall, I noticed that terms like "object," "reference," and "index" appear throughout the man pages without ever being properly defined. There's no single place that explains what these concepts mean or how they relate to things like commits and branches.

With help from Marie, we wrote a new "data model" document that fills that gap. At about 1,600 words, it's a concise explanation of how Git organizes commit and branch data. The document is available now in the Git repository and should make its way to the Git website after the next release.

Getting the details right turned out to be harder than expected. While I knew the basics of Git's data model, the review process surfaced several subtleties I had wrong. For example, I had to revise my explanation of how merge conflicts are stored in the staging area.

Evidence-based documentation improvements

Updating the man pages for git add, git checkout, git push, and git pull required a different approach. Expert users arguing about whether an explanation is clear isn't productive—people who know a tool well are often poor judges of what newcomers will find confusing. Instead, I wanted something more evidence-based.

I asked for test readers on Mastodon to review the current documentation and report what they found confusing. Around 80 people responded with detailed feedback. Their comments covered unfamiliar terminology (what is a pathspec? does "upstream" have a specific meaning?), specific sentences that were hard to parse, and inconsistencies where one section implied a default that contradicted another.

Most respondents had been using Git for five to ten years. That turned out to be an advantage: when experienced users find a sentence or term impossible to understand, it's easy to argue the documentation needs fixing.

This pattern of getting users to comment on existing documentation and then addressing their findings worked well and is something I'd try again.

What changed in the man pages

Four man pages got updated:

  • git add
  • git checkout
  • git push
  • git pull

The git push and git pull changes went beyond the introductions. We also added a section explaining what "upstream branch" means, a term that previously wasn't defined anywhere, and cleaned up the description of what a "push refspec" is.

Writing documentation that is both clear and accurate is a constant negotiation. Sometimes clarity requires sweeping complexity under the rug. For instance, "git push may fail if you haven't set an upstream for the current branch, depending on what push.default is set to" is deliberately vague—the specifics of that "depending" are complicated enough to warrant their own project.

Git's development workflow took some time to figure out. A few things that helped:

  • The Discord server has a "my first contribution" channel where people were welcoming and helpful.
  • GitGitGadget translated my GitHub pull requests into the email-based patch system Git developers use, so I never had to learn to send patches by email.
  • I used my regular email client to reply to mailing list messages, wrapping text at 80 characters per the list's conventions.

The mailing list archives on lore.kernel.org were hard to navigate, so I built my own viewer for long threads. Thanks are due to Emily Shaffer, Johannes Schindelin, Patrick Steinhardt, Ben Knoble, Junio Hamano, and others who helped with the review process.