TerminusDB brings git-style version control to your data — branch, merge, diff, and time-travel just like you would with code. Every write creates an immutable commit. This page is the single reference for all version control operations.
Git for Data
TerminusDB is a git for data database. Every write creates an immutable commit. You can branch, merge, diff, and time-travel your data just like code in Git.
Example database
Connect to TerminusDB first.
TerminusDB as Git for Data
If you know Git, you already know how TerminusDB version control works. The concepts map directly:
| Git concept | TerminusDB equivalent |
|---|---|
git branch | Create a branch — isolated workspace for changes |
git commit | Every write is a commit — with author and message |
git merge | Merge branches — apply changes with conflict detection |
git diff | Diff — structural field-level comparison of any two states |
git checkout <commit> | Time-travel — query the database at any historical commit |
git reset | Reset — move a branch pointer back to a previous commit |
git clone | Clone — replicate a database between instances |
The difference: Git operates on text files with line-based diffs. TerminusDB operates on structured JSON documents with field-level semantic diffs — it knows that a price changed from 9.99 to 14.99, not just that "line 3 was modified".
Prerequisites
- TerminusDB running on
localhost:6363or use the public server atdata.terminusdb.org. - A database to work with. The examples below use
admin/tdb-example-mydb. Create one with:curl -u admin:root -X POST http://localhost:6363/api/db/admin/tdb-example-mydb -d '{"label":"My Database"}'
Create a branch
Create a new branch from an existing branch. Branches are cheap — they share history until they diverge.
Loading…Expected output:
{
"@type": "api:BranchResponse",
"api:status": "api:success"
}List branches
List all branches in a database.
Loading…Expected response: an array of Branch documents, each with name and head (commit ID).
Switch branch (query a branch)
There is no "checkout" — you simply query or write to the branch path you want:
- main:
/api/document/admin/tdb-example-mydb/local/branch/main - feature:
/api/document/admin/tdb-example-mydb/local/branch/feature
Every API path that includes /local/branch/{name} targets that branch.
Commit (write with message)
Every write is a commit. Add author and message query parameters to record who changed what and why:
Loading…Expected output:
[ "terminusdb:///data/Product/Widget" ]
Get commit history
View the commit log for a branch:
Loading…Expected response: an array of commit objects with author, message, timestamp, and identifier (commit ID).
Diff (compare branches or commits)
Compare two branches to see exactly what changed — field-level structural diff, not line diff:
Loading…Expected output:
[
{
"@id": "terminusdb:///data/Product/Widget",
"price": {
"@op": "SwapValue",
"@before": 9.99,
"@after": 12.5
}
}
]The diff shows typed operations: SwapValue (field changed), Insert (added), Delete (removed). No other fields changed.
Merge a branch
Apply changes from one branch onto another:
Loading…Expected output:
{
"@type": "api:ApplyResponse",
"api:status": "api:success"
}If there are conflicts (both branches modified the same field), the merge fails with a conflict report — no silent overwrites.
Squash commits
Collapse all commits on a branch into a single commit — useful for cleaning up history before merging:
Loading…Expected output:
{
"@type": "api:SquashResponse",
"api:status": "api:success",
"api:commit": "*"
}Time-travel (query at a previous commit)
Query the database as it was at any previous point in time. Use a commit path instead of a branch path:
Loading…Replace abc123def456 with an actual commit identifier from the log. The response shows the database state at that exact commit — you did not modify anything, you are simply looking at a snapshot.
Reset a branch
Move a branch pointer back to a previous commit, discarding subsequent commits:
Loading…Expected output:
{
"@type": "api:ResetResponse",
"api:status": "api:success"
}Reset is destructive — commits after the target become unreachable (though the immutable commit graph still stores them). Use with care.
Delete a branch
Remove a branch. The commits remain in the database graph but this branch name no longer reaches them:
Loading…Expected output:
{
"@type": "api:BranchResponse",
"api:status": "api:success"
}Patch (apply a diff)
Apply a previously obtained diff to a document. Useful for conflict resolution or programmatic updates:
Loading…Expected output:
{
"@type": "api:PatchResponse",
"api:status": "api:success"
}Summary
| Operation | Method | Path pattern |
|---|---|---|
| Create branch | POST | /api/branch/{org}/{db}/local/branch/{name} |
| Delete branch | DELETE | /api/branch/{org}/{db}/local/branch/{name} |
| Merge (apply) | POST | /api/apply/{org}/{db}/local/branch/{target} |
| Squash | POST | /api/squash/{org}/{db}/local/branch/{name} |
| Diff | POST | /api/diff/{org}/{db} |
| Patch | POST | /api/patch/{org}/{db}/local/branch/{name} |
| Reset | POST | /api/reset/{org}/{db}/local/branch/{name} |
| Commit log | GET | /api/log/{org}/{db}/local/branch/{name} |
| Time-travel | GET | /api/document/{org}/{db}/local/commit/{id} |
Every operation is an HTTP call. Every write is a commit. Every commit is immutable. This is git for data.
Next steps
You've seen the full version control API. To go deeper:
- Diff and patch with the JS Client — compute and apply diffs programmatically in TypeScript
- Clone a project — replicate databases between TerminusDB instances
- Set commit messages — write effective audit-trail messages on every write