A centralized version control system built for binary-heavy projects (game development, 3D assets, rich media) and large team monorepos.
Nipa combines the strengths of Git (lightweight branches, release tags, merge requests, client-side three-way merges), Perforce (exclusive file locking, high-throughput binary streaming) and SVN (path-based access control, one central source of truth), so teams can track large assets at scale without giving up developer autonomy.
- Tech stack: Go, gRPC/Protobuf, SQLite (
modernc.org/sqlite), FastCDC content-defined chunking, BLAKE3, zstd - Model: client-server monorepo: the
nipaCLI, a local client daemon (nipa serve) for GUI and engine integrations, and thenipadserver (SQLite + local chunk storage), which serves gRPC, the REST API and the embedded web UI on a single port (default6745).
make web-install # first time only (npm dependencies)
make build # web UI + bin/nipad + bin/nipa
cp config.yaml.sample config.yaml
./bin/nipad # applies SQLite migrations at startup
# clone a repository (tries your SSH key, then prompts for a password)
nipa clone http://localhost:6745/org/project ./work
cd work
# edit files, then stage and commit them on the server
nipa add path/to/file
nipa status
nipa push -m "my change message"The working copy tracks the branch chosen at clone time. Files are split into content-addressed chunks and rehydrated from a local chunk cache, so updates and branch switches only transfer what actually changed.
docs/SERVER_GUIDE.md: building, configuring and running the server, including first-user and project bootstrapping.docs/DOCKER.md: theghcr.io/nipalab/nipad/docker.io/nipalab/nipadimage of the free server.docs/CLIENT_GUIDE.md: a task-oriented walkthrough of every client command.
- Binary streaming. Content-aware chunk sizes (64 KB for text and edit-in-place formats, 4 MB for packed textures, audio, video and models), per-file zstd compression for text, presigned direct HTTP transfers with adaptive concurrency, retries and cross-project deduplication.
- Exclusive file locks. Modifying or removing a tracked binary requires a lock, either per file or per directory. Locks on the default branch apply to the whole project, and merge requests hold locks for the binaries they change.
- Branches, tags and merges. Lightweight branches, immutable release tags with detached checkouts, fast-forward and three-way merges with diff3 text merging, and forward-only reverts.
- Merge requests. Drafts, reviews with inline threads, required approvals
and reviewers, status checks, assignees, and
ff/merge/squash/rebasestrategies. - Path-based access control. PBAC rules per user or group on directory
prefixes (
read,write,lock,admin). Clones, manifests and diffs only show what the caller can read. - Sparse checkouts. Materialize only selected directories; pushes still apply as deltas against the full server tree.
- Large repositories. Stat-cached
status/diff, incremental local tree saves and batched server writes keep 10k+ file repositories fast. - Operations. Webhooks, email notifications, an audit log, rate limiting, Prometheus metrics and OpenTelemetry tracing/logs.
- SSH key login. A challenge-response login over the same gRPC transport;
the private key never leaves the client (
docs/SSH.md).
Run nipa <command> --help for full details, or see
docs/CLIENT_GUIDE.md for examples of every command
and flag.
| Command | Description |
|---|---|
nipa login |
Sign in to a server. Tries an SSH key first (--ssh-key, NIPA_SSH_KEY, config sshKeyPath, ssh-agent, then ~/.ssh keys), then falls back to a password (--username). Every command logs in implicitly when needed. |
nipa clone <url> <target> |
Clone a repository. -b <name> selects the starting branch (default: the project's default branch), --sparse a,b limits the checkout to directory prefixes. |
nipa branch |
Show the current branch. -a lists all server branches, -c <name> creates a branch and switches to it, -d <name> deletes one. |
nipa switch <branch> |
Fetch the branch, materialize its tree and repoint the working copy at it. --tag <name> checks out a release tag instead, detaching HEAD. Not allowed while changes are staged. |
nipa tag |
List release tags. -c <name> [-m <message>] creates an immutable tag at the checked-out commit (or --branch <b> / --commit <id|hash>), -d <name> deletes one. |
nipa add <path> [...] |
Stage files (or everything inside directories) for the next push. Ignored files are skipped; -f stages them anyway. |
nipa remove <path> [...] |
Unstage files. -a unstages everything. |
nipa restore <path> [...] |
Discard unpushed changes, restoring files from the last synced tree (offline). Refused for staged paths. |
nipa status |
Show the working copy: A staged, M modified, ? untracked, ! missing, C conflict. |
nipa push -m "<message>" |
Upload staged changes and commit them on the configured branch. --dry-run reports the changes and upload estimate without contacting the server. --generate drafts the message with a configured OpenAI-compatible LLM (local or cloud) and asks for confirmation (--yes skips it); see docs/AI.md. |
nipa update |
Fetch and apply the latest changes of the configured branch (or re-sync the checked-out tag while detached). |
nipa sparse-checkout |
list, set, add, remove or disable the sparse directory prefixes, then update the working copy. |
nipa merge <branch> |
Merge another branch into the current one. Fast-forwards when possible; --no-ff, --ff-only, --abort, -m and --dry-run are supported. |
nipa revert <commit> |
Create new commits that undo a commit or a range (<from>..<to>, up to 16 commits) without rewriting history. --mainline 1|2, --no-commit, --continue/--skip/--abort and --dry-run are supported. |
nipa log |
Show the commit history, scrollable in a terminal. -n limits, --oneline prints one line per commit. |
nipa diff [<rev1> [<rev2>]] |
Show changes as a unified patch: working tree vs the last synced snapshot (offline), a revision vs the working tree, or two revisions. Revisions are branch names, tag names, base36 commit IDs or HEAD/@; <a>..<b> and <a>...<b> (merge base) are supported. Renames are detected; --staged, --stat, --name-only, --name-status, -w/-b, --ext-diff and -- <path> are supported. |
nipa blame <path> |
Show the commit, author and date that last changed each line of a text file (up to 2 MiB, the last 500 commits). Lines that are not pushed yet are marked; -r <rev> blames a branch, tag, commit ID or HEAD instead of the working file, --json prints machine-readable output. |
nipa assets check [<rev1> [<rev2>]] |
Check changed files against the root .nipaassets.yml asset budgets (texture size, power of two, triangles, vertices, audio length/peak, file size, naming). --staged, --json and -- <path> are supported; exits 2 on violations. See docs/AI.md. |
nipa lock <path> [--branch] |
Lock a binary file or a directory prefix. nipa lock list shows active locks. |
nipa unlock <path> [--branch] |
Release a lock you hold. |
nipa mr ... |
Merge requests: create [--draft] [--generate], list, view, update, ready, assign, review --approve|--request-changes, comment, reply, resolve, request-review, timeline, diff, check/checks, merge --strategy <ff|merge|squash|rebase> [--delete-source], close, reopen. |
nipa acl ... |
Manage path-based permission rules (grant, revoke, list, my, and permission list|set|remove for project path permissions). |
nipa group ... |
Manage groups and their members (create, list, add-member, remove-member). |
nipa serve |
Run the local daemon that GUI clients and engine plugins connect to. See docs/DAEMON.md. |
nipa mcp [--repo <dir>] [--allow <caps>] [--allow-write] [--no-agent-trailer] |
Serve the working copy to AI agents as a Model Context Protocol server over stdio: read and asset-aware tools plus the generation prompts always, write tools per capability (stage, push, sync, branch, lock, mr, merge) with --allow or all with --allow-write. See docs/AI.md. |
nipa version [--server] [url] |
Print the client version and, with --server, the server's version. |
Branch creation (nipa branch -c <name>) forks from the exact commit the
working copy is pinned to (clone, update, switch and push record it locally),
so it works offline and never picks up commits you have not seen.
Release tags are immutable named pointers to one commit, with an optional
annotation message (nipa tag -c v1.0.0 -m "first release"). nipa switch --tag v1.0.0 checks the tagged tree out in a detached state: nipa update
re-syncs the tag, status/log/diff follow the pinned commit, and
push/merge/revert refuse until nipa switch <branch> returns to a branch.
Files matching the root .nipaignore (versioned, shared with the team) or the
clone-local .nipa/ignore (never tracked) are hidden from nipa status and
skipped by nipa add; nipa add -f stages an ignored file anyway, after which
it stays tracked. The syntax is a gitignore subset: # comments, ! negation,
*/?, **, a leading or embedded / anchoring to the root and a trailing
/ matching directories only; the last matching rule wins. Sparse checkouts
always include the root .nipaignore.
A revert moves history forward: each reverted commit produces a new commit
applying its inverse on top of the branch head. A conflicted revert stops with
C files; resolve them and run nipa revert --continue (for a single pending
commit a plain nipa push also finishes it), skip the commit with --skip,
or discard the whole operation with --abort.
Without revisions, nipa diff is fully offline: the snapshot records each
file's chunk hashes, so the old side is rebuilt from the local object cache,
and unchanged files are skipped through the stat cache. With revisions, missing
chunks are downloaded first. Renames (at least 50% similarity) render git's
rename from/rename to headers. --ext-diff runs an external tool per file
with git's seven-argument contract, configured through NIPA_EXTERNAL_DIFF or
diffExternal in ~/.config/nipa/config.json.
nipa push refuses to land a modified or removed tracked binary unless you
hold a lock covering it. Brand-new files only conflict with someone else's
covering lock. Locks on the default branch are project-wide, while locks on any
other branch are scoped to that branch. Your exact-path locks are released once
the push they guarded lands; directory locks stay until you nipa unlock them.
See docs/LOCKING.md.
GUI surfaces contain no VCS logic. They connect to the local nipa serve
daemon (loopback gRPC with a capability token, plus a JSON/NDJSON HTTP bridge
for engines that cannot speak gRPC) and use the same operations as the CLI.
nipa serve # publishes its endpoint and token in ~/.config/nipa/daemon.json- Desktop app (
desktop/, Wails v3 + React): changes, history, branches and tags, merge requests with inline reviews, conflict resolution, file locks, team activity notifications and in-app updates. Visual diffs cover images (including TGA, DDS, KTX2, EXR, HDR and PSD), 3D models (glTF/GLB/OBJ), audio waveforms and loudness, CSV/TSV cells, and Unity/Godot scene structure. Build withmake desktop(needs thewails3CLI); design indocs/DESKTOP.md. - Unity plugin (
plugins/unity/com.nipalab.nipa): a version control provider with overlays, locks, history, conflicts and a project setup checker. Install from a git URL or tarball (make unity-pack); seedocs/UNITY_PLUGIN.md. - Godot plugin (
plugins/godot, Godot 4.4+): a nativeEditorVCSInterface, the Nipa dock, auto-locking, conflicts with structural.tscn/.tresmerges, history, image diffs and a setup checker. Ships asnipa-godot-vX.Y.Z.zipon releases taggedgodot-v*; seedocs/GODOT_PLUGIN.md. - Web UI (
web/, Vite + React + Primer): repository browsing, commit history and diffs, branches, tags, merge requests, locks, settings and administration. It is embedded in the server binary; seedocs/WEB_UI.md.
Nipa can be driven by scripts and AI agents as well as by people. Everything runs client-side; the server never calls an LLM.
- MCP server —
nipa mcpserves a clone over stdio (Model Context Protocol) for Claude Code, Cursor and other MCP clients, e.g.claude mcp add nipa -- nipa mcp --allow mr,lock. Read tools (status, diff, log, branches, tags, locks, conflicts, merge requests with their diff, threads, commits and timeline) and asset tools (structured diffs of Unity/Godot scenes, images, models, audio and tables with GUIDs resolved, per-file change summaries,.nipaassets.ymlchecks,.meta/.importsidecar warnings) are always on. Write tools are enabled per capability with--allow stage,push,sync,branch,lock,mr,merge(or--allow-write). Results are capped (max_bytes,limit), text written through MCP gets aNipa-Agent: <client>/<version>trailer (--no-agent-trailerdisables it), and the promptsnipa_commit_message,nipa_mr_descriptionandnipa_review_mrhand the agent ready-made context. Log in from a terminal first:nipa mcpnever prompts. - Generation —
nipa push --generateandnipa mr create --generatedraft the commit message or merge request text with an OpenAI-compatible endpoint you configure (NIPA_LLM_ENDPOINT/NIPA_LLM_MODEL, e.g. a local Ollama). Only paths, text hunks and structured asset summaries are sent, never binary contents; without configuration nothing is sent. - Asset budgets — a versioned
.nipaassets.ymlsets per-path texture, mesh, audio, size and naming limits;nipa assets check [--json](exit 2 on violations),nipa push --dry-runandnipa_asset_checkreport breaches. - Machine-readable output —
--jsononstatus,diff,log,branch,tag,lock list,mr list|view|diff|comments|timeline|checksandassets check(NIPA_OUTPUT=jsonenables it globally). Failures are a single{"error":{"code","message","hint","action"}}envelope on stderr, and exit codes are stable:0success,1generic failure,2locked/precondition,127not found. - Dry runs —
nipa push|merge|revert --dry-run [--json]report changes, conflicts, the upload estimate andasset_violationswithout touching the working copy or the server. - REST API — OpenAPI at
/docs/api.json(Swagger UI at/docs/).
The full agent-facing reference lives in docs/AI.md.
- Server (
internal/):domain(entities and errors),usecase(business logic over repository interfaces),repository/sqlite(sqlc),grpc(protobuf service and handlers),http(REST API) andserverapp(shared wiring and the single-port HTTP/gRPC/SPA lifecycle). - Client (
internal/client/):cli(cobra commands),usecase(clone, push, update, merge, revert, diff and more),grpc(transport and chunk transfers),localrepo(.nipa/metadata in SQLite plus a loose object cache),merge(three-way tree merge and diff3),daemon(nipa serve),mcp(nipa mcp),aiprompt/aicontext(generation prompts and their repository context) andllm(OpenAI-compatible client behind--generate). - Shared pure packages:
internal/diff(Myers diff, tree comparison, rename detection, rendering; also used for server-side merge-request diffs),internal/preview(asset decoders and visual diffs) andinternal/godotres(Godot resource parser and three-way merge). - Storage model: content is stored as chunks addressed by BLAKE3 hash; a
tree is a recursive manifest of directories, files and their chunk lists. A
clone keeps a JSON
config, a SQLite database (tree snapshot, staged files, stat cache, pending merge/revert state) and a content cache in.nipa/.
AGENTS.md is the agent quick reference; docs/internals/ has a detailed walkthrough of every flow.
make build # web UI + bin/nipad + bin/nipa
make test # go test ./...
make test-client # black-box CLI suite against a real nipad
make lint # golangci-lint
make web-dev # Vite dev server proxying the API
make sqlc proto mock # regenerate sqlc, protobuf and gomock code
make desktop-test unity-test godot-test # client integrationsBenchmarks and load tests (make bench-upload, bench-download,
bench-scale, load-test) are described in
docs/PERFORMANCE.md.
This project is dual-licensed:
- Community open source license: Apache License 2.0. The main project code is covered by the current LICENSE.
- Commercial enterprise license: all files and folders under the
eedirectory are licensed separately under the enterprise license in ee/LICENSE.
The Apache 2.0 license applies to the community OSS edition. The commercial enterprise license applies only to code under the ee directory.