zev and Git

"Git already exists, so why zev?" Because zev does what Git leaves to you or to extra tools: one `zev undo` for any mistake, conflicts you can commit and settle later, stacked reviews, storage for large files, signatures on commits, proof that the server still holds your work, and output made for scripts and AI agents. The longer answer is in [Why zev](/docs/en/why-zev). If you know Git, you already know how to use zev. The daily commands have the same names and do the same things. ```diagram type: cards title: What stays the same --- 🌿 | Branches, merges, rebases | branch, switch, merge, rebase, cherry-pick, stash and tag work the way you expect 📜 | A history of commits | every commit names its parent and the tree of files it saved 🔁 | Push, pull, clone | one command each, to and from Zaryn or any zev server ``` ## What zev adds | | Git | zev | |---|---|---| | **Large files** | Every version is a whole new object; big files need Git LFS and its separate server | Files are cut into chunks by content, so an edit sends only the chunks around it, on push and on pull. [Chunking](/docs/en/chunking) | | **Signed commits** | Off by default; GPG or SSH keys to set up per machine | Every new commit is signed on your computer with no setup. Add the key once and Zaryn shows the commit as **Verified**. [Signed commits](/docs/en/signed-commits) | | **Proof the server kept your work** | You trust the host | `zev verify-storage` checks that the server really holds your last push, and daily signed receipts cover every object. [Verified storage](/docs/en/verified-storage) | | **Encryption** | None: the host can read everything | Encrypted repositories are sealed on your computer; the server stores what it can't read. [Encrypted repositories](/docs/en/encrypted-repositories) | | **Undo** | A reflog per branch, and a different `git reset` recipe for each mistake; the wrong one discards work | `zev undo` takes back the last commit, merge, rebase, deleted branch or add, and never overwrites work that isn't saved anywhere. `zev op log` lists every change. [Undo anything](/docs/en/undo) | | **Edits you threw away** | `git checkout -- file` or `git reset --hard` deletes them for good | zev keeps a copy first; `zev recover` brings them back, and never overwrites newer work. [Undo anything](/docs/en/undo) | | **Merge conflicts** | They block you: no commit, switch or stash until every file is settled; two sides shown, the base only if you configure it | Each conflict shown with yours, the base and theirs; `zev resolve` picks a side per file or per conflict; `--keep-conflicts` commits now to resolve later, and Zaryn won't merge it until then. [Merge conflicts](/docs/en/conflicts) | | **Another repository inside yours** | Submodules: forget `--recursive` and the folder is empty, the code inside sits on a detached HEAD, and reviews don't show the version | Subrepositories: the pin is a readable file, clone, checkout and pull fetch and update them, and work inside one is never moved over. [Subrepositories](/docs/en/subrepos) | | **Stacked changes** | Branches that build on each other are yours to track; each is rebased by hand (`--onto`, or commits get duplicated) and each pull request retargeted after a merge | `zev stack` knows the chain: restack moves every branch at once and correctly, push opens one pull request each onto the branch below, sync cleans up after merges. [Stacked changes](/docs/en/stacked-changes) | | **Staging part of a file** | `git add -p`, interactive only; a script has to build a patch | `zev add -p` for people, and `zev add <file> --hunk 2` for scripts and agents, numbered as `zev diff --brief` shows them. [Commands](/docs/en/commands#zev-add) | | **Searching code** | `git grep`: matching lines | `zev grep` says which function, class or heading each match is in, searches any commit with `--at`, and answers as `--json` or `--brief`. [Commands](/docs/en/commands#zev-grep) | | **Output for scripts and AI agents** | `--porcelain` for status, format strings for log | `--json` and `--brief` on status, log, diff, show and branch, or `ZEV_OUTPUT` once. [Scripting and AI agents](/docs/en/automation-and-agents) | | **Getting oriented** | `ls`, `cat README`, `git log`, `git status`, one by one | `zev brief` gives the project, your changes, recent commits, layout, hot files and branches in one call, within a token budget. `zev diff --summary` names the functions each change touched. [Scripting and AI agents](/docs/en/automation-and-agents) | | **AI agents** | Third-party tools | `zev mcp` gives an agent your repositories, history, issues and CI in compact answers. [Scripting and AI agents](/docs/en/automation-and-agents) | | **What changed in code** | Lines added and removed | `zev sdiff` reports functions added, removed, renamed, or with a changed signature or body (Zig today). [Semantic diff](/docs/en/semantic-diff) | | **Model and data history** | Commits only | Metrics per commit, evals that block a pull request when a score drops, datasets and lineage. [Evals and lineage](/docs/en/evals-and-lineage) | | **Known-bad commits** | Nothing built in | Advisories mark commits as compromised and find everything built on them. [Advisories](/docs/en/advisories) | | **Open addressing** | Objects live in one repository's `.git` | Commits are IPFS objects anyone can resolve and check, on Zaryn or anywhere else. [IPLD provenance](/docs/en/ipld-provenance) | ## Built for people and for AI agents zev is made to be read by two kinds of users. People get sentences, colours and the next command to run. When something goes wrong, the message says what to do, not just the error code. AI agents and scripts get the same facts as data: `--json` for exact parsing, `--brief` for the fewest tokens. The data always goes to stdout and the text for people to stderr, so the two never mix. ```bash zev status # for you: what changed, and what to run next zev status --brief # for an agent: "# main", then " M f.txt" ZEV_OUTPUT=json zev log # for a script: one JSON document ``` ## Your Git commands in zev | You'd type in Git | In zev | |---|---| | `git init` | `zev init` | | an existing Git repository | `zev import-git`: every branch and tag, in place ([Moving from Git](/docs/en/from-git)) | | `git clone <url>` | `zev clone owner/name` | | `git lfs track` / `git lfs pull` | nothing: large files are chunked and stored by zev itself | | `git commit --amend` | `zev undo`, then commit again | | `git status` / `git status --porcelain` | `zev status` / `zev status --brief` | | `git add <file>` / `git add .` | `zev add <file>` / `zev add .` | | `git commit -m "…"` | `zev commit -m "…"` (signed automatically) | | `git log --oneline` | `zev log --oneline` or `zev log --brief` | | `git diff` / `git diff --staged` | `zev diff` / `zev diff --staged` | | `git show <commit>` | `zev show <commit>` | | `git branch` / `git branch <name>` / `git branch -d <name>` | `zev branch` / `zev branch <name>` / `zev branch -d <name>` | | `git switch <name>` / `git switch -c <name>` | `zev switch <name>` / `zev switch -c <name>` | | `git merge <branch>` | `zev merge <branch>` | | `git rebase <branch>` | `zev rebase <branch>` | | `git rebase --onto <new> <old>` | `zev rebase <new> --since <old>`, or for a chain of branches `zev stack restack` | | `git diff --name-only --diff-filter=U` | `zev conflicts` (with every conflict's sides) | | `git checkout --ours <file>` / `--theirs` | `zev resolve <file> --ours` / `--theirs` (or `--hunk N` for one conflict) | | `git add -p` | `zev add -p`, or `zev add <file> --hunk 1,3` with no questions | | `git mv <from> <to>` | `zev mv <from> <to>` | | `git grep <pattern>` | `zev grep <pattern>`, with the function each match is in | | `git submodule add <url> <path>` | `zev sub add <address> <folder>` | | `git submodule update --init --recursive` | nothing: clone, checkout and pull do it (`zev sub update` by hand) | | `git cherry-pick <commit>` | `zev cherry-pick <commit>` | | `git stash` / `git stash pop` | `zev stash` / `zev stash pop` | | `git tag <name>` | `zev tag <name>` | | `git restore <file>` / `git restore --staged <file>` | `zev restore <file>` / `zev restore --staged <file>` | | `git rm <file>` | `zev rm <file>` | | `git blame <file>` | `zev blame <file>` | | `git bisect` | `zev bisect` | | `git remote add origin <url>` | `zev remote add origin <url>` | | `git push` / `git pull` | `zev push` / `zev pull` | | `git verify-commit <commit>` | `zev verify <commit>` | | `git diff --stat` | `zev diff --summary` (with the functions touched) | | `git reset --soft HEAD~1` | `zev undo` | | `git reflog` | `zev op log` | | `git reset --hard HEAD@{n}` | `zev op restore <n>` | Not in the table? Type it with `zev` in front: `zev git <your git command>` says the zev form and runs it (`-n` only says it). [Keep typing Git](/docs/en/from-git#keep-typing-git). Commits and branches are referred to the same way: a hash or a prefix of one, a branch or tag name, `HEAD`, `HEAD~2`, `main^`. ## What Git has that zev doesn't (yet) A fair comparison runs both ways. | Git | In zev | |---|---| | Merge commits with two parents | History stays linear: `zev merge` replays your commits on top, like `git pull --rebase` | | `git worktree`, sparse and shallow checkouts | Not yet | | Every host and tool in the world speaks it | zev speaks to Zaryn and any zev server; `zev import-git` brings a Git repository over | ## When Git is still the right tool zev isn't trying to win every case. If your project lives on a host that only speaks Git or has tools wired to `.git`, or if nothing in the tables above matters to you, Git will serve you well. zev is for teams that want undo, conflicts that don't block, stacked reviews, large files, signatures and AI agents to work without assembling them from extra tools. ## Moving over `zev import-git` brings a Git repository's whole history into zev in the same folder, and `.git` stays as it was, so you can use both while you switch. [Moving from Git](/docs/en/from-git). Next: [Moving from Git](/docs/en/from-git), [Your first repository](/docs/en/first-repository), or [Version control in pictures](/docs/en/version-control-in-pictures) if branches and merges are new to you.