Git-backed documentation, explained.
The phrase gets used loosely. Some tools mean their content lives in a Git repository. Others mean they can push a copy to one. The difference is not cosmetic — it decides who holds the canonical version of what your organisation knows. This page defines the term precisely, sets out what the model actually buys you, and is straight about the cases where it is the wrong choice.
The repository is the store, not a copy of it.
Git-backed documentation is documentation whose canonical storage is a Git repository of plain files. Every page is a file. The repository is the source of truth. There is no database behind it holding the real version, and no sync process reconciling two copies. Clone the repository and you have the documentation — all of it, in exactly the form the tool itself reads and writes.
The word doing the work in that definition is canonical. A great many tools touch Git in some way, and most of them are not Git-backed by this definition. There are three distinct arrangements, and they behave very differently the day something goes wrong or you decide to leave.
| Model | Canonical copy | What Git holds | What leaving costs |
|---|---|---|---|
| Database-backed Confluence, Notion, BookStack | Rows in the tool's database | Nothing, unless you build an export job yourself | An export project. You discover the fidelity afterwards |
| Git-synced Wiki.js with Git storage, GitBook with Git Sync | The database or the hosted platform | A mirror, written by a sync process | Better than an export — but the copy is a reflection, and reflections drift |
| Git-backed A plain repo, MkDocs, Docusaurus, DocuCommit | The Git repository itself | Everything. The pages are the repository | git clone. There is nothing to convert |
The middle row is the one that gets miscategorised. A Git-synced tool keeps the authoritative content in its own store and mirrors it into a repository, so the repository is a derivative artefact. That is a perfectly reasonable design — Wiki.js can use Git as a storage target while the database stays authoritative, and GitBook offers Git Sync between its platform and a repo while authoring remains on the platform. Both give you something a purely database-backed tool does not.
But a mirror has a failure mode a source of truth does not: drift. Somebody edits in the UI while the repository also moved; a sync pauses on an auth change and nobody notices for a fortnight. Neither is dramatic — both are reconciliation work, and someone has to own it. In a Git-backed tool the question cannot arise, because there is only one copy.
None of this makes Git-backed automatically better. It is a different set of tradeoffs, and the rest of this page is those tradeoffs.
Properties you get structurally, not as features.
-
Revision history is the commit log
Every change carries an author, a timestamp, a message, and a real diff.
git blamegives you per-line authorship on prose the same way it does on code, and there is no retention window to negotiate, because history is not a stored feature with a tier limit — it is the storage format. The honest caveat is that history is only as good as commit discipline: one monthly commit called "update docs" tells you about as much as a database revision would. -
Backup and DR is
git cloneEvery clone is a complete copy including history, so a scheduled
git clone --mirrorto a second host is a genuine disaster recovery plan rather than a restore procedure you hope works. Be honest about the boundary, though: this covers content. Anything a tool keeps outside the repository — user accounts, comments, notification state — needs its own backup, and that is as true of Git-backed tools as of any other. DocuCommit is no exception; its server keeps comments and accounts in its own working directory, not in your repo. -
Portability is a property, not a promise
The files are Markdown. Any editor opens them,
grepsearches them,pandocconverts them, and any static site generator builds them. Leaving costs a clone rather than an export project, and the content arrives in the same shape it was written in. Arriving is the harder direction: reshaping a database-backed space into files is real, mostly manual work — the Confluence migration guide is candid about how much. -
The same tooling as your code
Documentation on the same infrastructure as code inherits everything already built there: CI that checks links and spelling on every change, review before merge, branch protection, signed commits, mirrors, access control you already administer. None of it has to be procured or operated separately. The leverage is real only if that infrastructure exists and the people writing docs can reach it — the constraint the next two sections are about.
-
Agents can read it without an API
A retrieval pipeline wants plain text with stable identifiers. A Git-backed repository is already that: a clone hands an agent the whole corpus, file paths work as stable identifiers, and the commit log says what changed since the last index, so updates can be incremental. No API to authenticate against, no rate limit, no HTML-to-text cleanup step. Be precise about what this does not do: it removes the access problem, not the content problem. A repository full of stale pages retrieves stale answers, faithfully.
This page is deliberately neutral. For the argument rather than the definition, see why your docs belong in Git — the opinionated case for the same model.
The tradeoff nobody advertises.
Git's collaboration model is asynchronous by construction, and no interface hides that completely. Four consequences follow, and they are worth knowing before you commit to the model rather than after:
- There is no real-time co-editing. Two cursors in one paragraph is not something Git does. If your team's mental model of documentation is a shared document with five people typing in it, this is the adjustment.
- Concurrent edits meet as a merge. Each person works on their own copy; the changes are combined when the second one integrates. Git does this without asking whenever the edits sit in different parts of the file.
- Merge conflicts exist, and a human resolves them. When two people change the same lines, Git stops and asks. Someone reads both versions and decides. There is no algorithm that knows which sentence was meant.
- Binary files do not merge. An image, a PDF, an Office attachment: Git stores every version, but it cannot combine two of them. One side wins whole.
Why this is usually acceptable for documentation is a question of collision rate. Prose edits cluster by ownership — people edit the pages they own — and a page-per-file layout makes the unit of conflict a single document rather than a workspace, so two people working on different pages never interact at all. Git was designed for far higher contention than a documentation repository will ever produce.
Where it stops being acceptable is when the interface leaks. Conflict markers in a terminal are a perfectly good format for people who have seen them a hundred times and a wall to everyone else. For non-developers to work in a Git-backed system, the tooling has to supply three things: conflict detection at save time — the file on disk can change under an open editor, and that is both more common and more confusing than a merge conflict; a merge interface that shows two versions and a result you assemble, rather than markers you edit around; and ordinary button names, so that "commit" and "push" do not have to be learned as vocabulary before someone can fix a typo.
As one example of that shape: DocuCommit records the file's hash when a document opens and, if it no longer matches on save, shows both versions and asks what should happen. Conflicts arriving from a pull go to a three-pane screen — your version, their version, and an editable final version you build one clash at a time. The mechanics are written up in resolve conflicts.
When Git-backed documentation is the wrong answer.
These are not edge cases. Each one is a normal situation in which a database-backed or hosted tool is the better engineering decision, and choosing one is not a failure of nerve.
- Real-time multiplayer editing is the primary workflow. Workshop notes, live meeting minutes, a document four people draft together in one sitting. Git's unit of collaboration is a finished change, not a keystroke. Use the tool built for simultaneous editing and move the result into the docs once it has settled.
- The content is binary-heavy. Video, PSDs, large design exports, big PDF sets. Git stores every version of every binary, history grows monotonically, and clones get slow for everyone forever. Git LFS exists in the ecosystem to move large objects out of the main store, but not every Git-backed tool supports it — DocuCommit does not — and it brings infrastructure of its own. If your documentation is mostly large binaries, something with object storage behind it is the right shape.
- You want zero infrastructure. A hosted wiki is genuinely simpler to operate: no repository hosting, no server, no backup job, no upgrade window. Git-backed means you own a repository and usually something that publishes it. If the team is five people and nobody wants to run anything, that is a real argument and this page will not try to talk you out of it.
- The content is structured data, not prose. Asset registers, inventories, anything that gets filtered, sorted, aggregated, or entered through a form. Markdown files make a poor database and a worse query engine. Keep the data in a database and document the data in Markdown.
- Nobody can operate Git and no tool hides it. Plain Git with Markdown, or a static site generator, asks every contributor to work roughly like a developer. If the people who own the knowledge will not do that, the pages simply stop being updated — which is worse than any storage model. Either adopt a tool that puts an ordinary editing surface in front of Git, or accept that only a few people will ever write.
- You need a record nobody can rewrite. Git history is not immutable by default. A force push, a rebase, or a history rewrite can remove a commit and leave the repository looking perfectly consistent. Server-side branch protection and signed commits close this, but they are configuration you have to apply deliberately — do not sell Git history to an auditor as tamper-proof on its own.
Four shapes the same idea takes.
"Git-backed" describes storage, not a product category. Very different tools satisfy the definition, and they ask very different things of the people using them.
| Shape | Canonical store | Authoring | Publishing |
|---|---|---|---|
| Plain repo and a convention | The repository | Any text editor; Git on the command line or a forge's web editor | Read it on the forge, or do not publish it at all |
| Static site generator | The repository | Text editor plus a local preview server; developer-oriented, and some add their own syntax | A build step and a deploy target — CI, Pages, a bucket |
| Git-synced wiki | The database or hosted platform; Git holds a mirror | Browser editors, nothing to install | Served by the application itself |
| Git-backed with an editor layer | The repository | An application that reads and writes the files directly and performs Git actions on request | A server that pulls the repository and renders it |
The first shape is a folder of Markdown and a naming convention — often enough for a small technical team, at the cost of whatever navigation and search the forge happens to give you. The second adds a generator: MkDocs and Docusaurus turn the same repository into a proper site, at the price of a configuration file, a build step, and a deployment pipeline to keep working. Both are unambiguously Git-backed.
The third shape — Wiki.js, GitBook and tools in that category generally — is the one that is often described as Git-backed but sits in the Git-synced row of the first table. What you gain is a browser editor and nothing to install; what you accept is that the repository is a mirror. The fourth shape keeps the repository canonical and puts an editing application in front of it, so the files stay the source of truth while the person writing does not have to think about Git at all. That is the category DocuCommit is in, and it is the subject of the one product section on this page.
How DocuCommit implements this.
A repository is a library. Top-level folders are projects, subfolders are
sections, and every document is a .md file with a little YAML
frontmatter for title, slug, tags, and sort order — the full layout is in
repository layout. The
desktop editor writes the file when you save; Git actions are separate and
user-initiated, with the real button names doing the explaining:
Save a snapshot is a commit, Publish is a
push, Get updates is a pull. Clashes from a pull go to the
guided three-pane merge.
The read-only server pulls the same repository and renders it for readers,
and never writes to it. Comments and accounts live in the server's working
directory, outside the repo. Everything else is just the files.
The documentation is the accurate description of what it does and does not do, including the limits. A 14-day trial is the accurate test.
Further reading: for how other tools stack up against this model, see all eight tool comparisons. For the mechanics underneath two of the claims made above, see how concurrent Markdown edits actually merge and the complete outbound-network inventory.
See whether the model fits your team.
The documentation describes the whole product, limitations included. The 14-day trial runs on your own repository and needs no card.