Contents

Command reference

Run commands from inside the repository or any of its worktrees. <agent> is the agent's name in gitta status, usually its branch name.

gitta --help lists every command on one screen. Every command also takes --help or -h. It prints the command's usage and options, exits with 0 and changes nothing. A command given an option it does not know stops before it does anything, names the option and exits with 2. Notes and reasons, as in gitta claim, are free text and may contain anything.

Setup

Command	What it does
`gitta init`	Watch this repository and add git hooks for merge, pull and push. Run it once.
`--gate "CMD"`	The test command that decides if combined work is good. gitta runs it on the combined code when you merge, pull or push to the protected branch. Without a gate, gitta still tells agents about clashes, but runs no tests.
`--onto BRANCH`	The branch to protect. The default is the current branch.
`--weakened-checks warn\|block`	What a merge does when it removes tests or weakens a security check. `warn` reports it and merges, `block` stops the merge. Local hooks use `warn` by default, CI and the pull request check use `block`. Written to `.gitta.toml`, which takes effect once committed. See Team policy.
`--team`	Write the team policy to `.gitta.toml`, so you can commit it and share the test command and rules with your team and the CI check. See Team policy.
`--notify on\|off`	Desktop notifications when something needs a person. Off by default.
`--no-claude`	Do not add Claude Code hooks.
`--no-cow`	On Linux, use ordinary worktrees instead of a shared checkout.
`--security PATTERN`	Treat this symbol or path as a security check in this checkout. Repeat for more. For the whole team, use a committed `.gitta-security` file. See Mark your own security checks.
`--security-block high\|medium\|none`	The security notes that count as weakened checks. The default is `high`. Saved as `"security_block"` in `.gitta/config.json`. See Security notes.
`--parallel N`	Run at most N combination checks at the same time.
`--server URL[,URL]`, `--token T`	Report to Gitta Enterprise team servers.
`gitta adopt [PATH...] [--all]`	Coordinate worktrees that another tool made, without automatic watching. `--onto BRANCH` and `--gate CMD` work as for `init`. Not needed after `gitta init`, which finds worktrees by itself.
`gitta adopt --reset <agent>`	Restart an agent whose start commit is no longer in the repository. Its changes are then counted from where its work meets the protected branch. See Troubleshooting.

Everyday

Command	What it does
`gitta status [--json]`	Agents, their changed files and all warnings. A worktree Gitta cannot read is skipped with one line that says why and how to fix it; the others are shown as usual. `--json` lists them under `skipped`.
`gitta watch [--once]`	A live terminal view. See Watching gitta work.
`gitta ui-status`	The current state as JSON, for your own scripts.
`gitta sync <agent> [--from main\|<agent>]`	Merge work from main, or another agent's current work, into this agent's copy.
`gitta check <agent> [--with <agent>] [--json]`	Run the gate on this agent's work combined with each other agent's work, or with one. Results are `PASSES`, `BREAKS` or `DOES_NOT_MERGE`.
`gitta claim <agent> <symbol or path> [note]`	Announce a change before it is made.
`gitta release <agent> <symbol or path>`	End a claim.

Watching gitta work

gitta watch fills the terminal and updates as events arrive.

Each agent, with what it is doing now.
The latest events, one plain line each.
Today's counts of changes checked, clashes caught and merges.
Anything a person must act on, with the exact command to run. When nothing waits, it says "Nothing needs you".

Press q to quit. The view follows the terminal size and has no colour when NO_COLOR is set. Without a terminal, for example in a pipe, it prints plain lines. gitta watch --once prints today's counts and the recent events, then exits.

The same events go to .gitta/gitta.log, one line each with the time and a plain sentence. Follow it with tail -f .gitta/gitta.log.

Merging

You merge with git merge, git pull or git push. The hooks that gitta init adds run the checks. See Merging. The commands below are optional.

Command	What it does
`gitta land <agent>`	Optional. Check, merge, run the gate, and move main forward by one commit, in one command.
`gitta land --all`	Optional. Land every agent, in dependency order.
`gitta land <agent> --pr [--remote origin]`	Push the checked result to `gitta/pr/<agent>` and open a pull request.
`gitta approve <agent> <reason>`	Optional. A recorded override for a repository that sets `weakened_checks` to `block`. A person accepts this agent's current weakened checks, security findings and code page findings, and the reason goes into the audit trail. It runs only at a person's terminal, outside agent sessions and workspaces, and covers only these exact findings.
`gitta pr-check --pr REF --other REF[=NAME]...`	Compare one branch with others, as the CI check does. `--name N` names this pull request, `--base REF` sets the target branch, `--gate CMD` runs your tests on each pair, `--json` prints the results for scripts. It also lists removed tests and weakened checks in the branch, and exits with 3 when `weakened_checks` is `block`. See Pull requests and CI.
`gitta encoding`	With gitta Enterprise, show the code pages of the mainframe files, from `.gitattributes` and `.gitta-encoding`, and the code page risks gitta sees. This command is in the Enterprise build, not in the free `gitta`. See Set the code page for each folder.
`gitta scan [DIR...]`	Search dependency folders (`node_modules`, `.venv`, `venv`, `vendor`, or the folders you name) for agent instruction files that a package planted, and for prompt injection phrases in them.

Agents in batches

Command	What it does
`gitta run --task T [--task T...]`	Make one worktree per task and start one agent in each.
`--agent claude\|codex`, `--cmd 'TEMPLATE {task}'`	Which agent to start.
`--gate CMD`, `--link DIR`	The gate, and folders to link into each workspace, for example a dependency folder.
`--tasks FILE`	Read tasks from a file, one per line.
`--land`	Optional. Land every agent when all are done.
`--sandbox`	On Linux, start each agent in the sandbox. Add `--net-port P` to allow outgoing TCP to that port only.
`gitta up -n N [--gate CMD] [--link DIR]`	Make N agent workspaces, each on its own branch `gitta/aN`. After `gitta init` they branch off your main branch and join the existing setup.
`--backend worktree\|overlay\|fuse`, `--deny-read PATTERN`	On Linux, make copy-on-write workspaces over one shared checkout instead of worktrees, and leave files that match the pattern out of them. See Linux workspaces.
`gitta down`	Remove the workspaces that Gitta made.

Agent tools

Command	What it does
`gitta install claude\|cursor\|codex`	Connect one agent tool in every workspace.
`gitta hook claude\|claude-stop`	Run by Claude Code after each step and when it stops. It reads the event on stdin. You do not run it yourself.
`gitta hook worktree-create\|worktree-remove\|worktree-setup`	Run by the coding tools when they make or remove a worktree, so it can share one checkout on Linux.
`gitta mcp`	The MCP server for Cursor and Codex, on stdin and stdout. It gives the tools `gitta_status`, `gitta_sync`, `gitta_check`, `gitta_claim` and `gitta_release`.

Audit

Command	What it does
`gitta audit`	Show the audit trail as a table. See Audit trail.
`--since DATE`, `--agent A`, `--event E`	Filter.
`--csv`, `--json`	Export.
`--team`	With Enterprise, read the whole team's trail from the team servers.
`gitta audit verify [--team]`	Check that no event was changed, removed or reordered.
`gitta report [--period day\|week\|month\|all] [--by agent\|person\|repo] [--csv\|--json] [--team]`	Agents run, changes, clashes found, merges stopped and broken mains prevented. See Usage report.

Gitta Enterprise

Command	What it does
`gitta login [--server URL[,URL]]`	Sign in with your company account and get your own token.
`gitta team whoami`	Show who the team servers think you are.
`gitta team token create --name N [--email E] [--runner] [--days D]`	Make a personal token for a person or a CI runner. Needs an admin token.
`gitta team token list`	List tokens and their state. Needs an admin token.
`gitta team token revoke <id>`	Revoke a token on every server. Needs an admin token.
`gitta server`	Run a team server. This command is in the Enterprise server build, not in the free `gitta`. See Team server.

Update

Command	What it does
`gitta update`	Install the latest release over this `gitta`. Gitta verifies the checksum first and then renames the new files over the old ones. If Homebrew or cargo installed Gitta, it prints the command to use instead. See Update.
`gitta update --check`	Show if a newer release exists. Changes nothing.

Remove

Command	What it does
`gitta uninstall`	Remove Gitta from this repository.
`gitta uninstall --everywhere`	Also remove the hooks and MCP entries from your user settings.

Team policy in .gitta.toml

gitta init --team writes a .gitta.toml at the root of the repository. --weakened-checks writes it too. Commit it. gitta reads it from the protected branch, so only a reviewed commit changes the policy, and the CI check reads the same file. A copy you edit but do not commit changes nothing.

Terminal

$ gitta init --team --weakened-checks block
$ cat .gitta.toml
# gitta team policy. Commit this file: merges, pushes and the CI check read it from main.
# The test command gitta runs on the combined code before a merge.
gate = "PYTHONPATH=src python3 -m unittest -q"
# Removed tests or weakened security checks: "warn" lets the merge go ahead and records it, "block" stops it.
# Without this line, local merges warn and the CI check blocks.
# weakened_checks = "warn"
weakened_checks = "block"

Key	Use
`gate`	The test command for the combined code. A local `--gate` setting comes first on that machine. CI runners use this one when they get no `GATE`.
`weakened_checks`	`warn` or `block`. Without it, local merges warn and the CI check blocks. The `GITTA_WEAKENED_CHECKS` environment variable comes first.

Files in the repository

File	Use
`.gitta/`	Settings (`config.json`), the audit trail (`audit.jsonl`), caches and check checkouts. Hidden from Git, per checkout.
`.gitta.toml`	Committed. The team policy. See Team policy.
`.gitta-security`	Committed. Your own security checks, the `[allow]` section and the mainframe sections. See Warnings and Security checks on mainframe code.
`.gitta-copybooks`	Committed, for gitta Enterprise. Directories whose files are COBOL copybooks. See Copybook directories.
`.gitta-include`	Committed. C and C++ include directories, how to read `.h` files, and macros that open a namespace. See C and C++.

What gitta keeps in .gitta/

Everything stays in the repository's own .gitta/ folder. Git ignores it, and nothing in it leaves the machine.

Path	Contents
`config.json`	The settings below.
`audit.jsonl`, `audit-main`	The hash-chained audit trail, and the last main commit it recorded. See Audit trail.
`gitta.log`	One readable line per event, with the time and a plain sentence. Follow it with `tail -f .gitta/gitta.log`. It is rotated at 1 MB.
`activity.jsonl`	The same account of what gitta did and why, as JSON.
`agents/`	The workspaces of agents started in a batch. See Agents in batches.
`events/`, `logs/`	Recent events for `gitta watch`, and the output of each agent that `gitta run` started.
`approvals.json`, `claims.json`	Overrides people recorded with `gitta approve`, and changes agents announced with `gitta claim`.
`base/`, `cache/parse/`	The base each agent started from, and parsed files, so warnings stay fast.
`shared/`, `cow/`	Shared and copy-on-write workspaces on Linux. See Linux workspaces.

To remove gitta, use gitta uninstall. It keeps the work in every agent workspace.

Settings in .gitta/config.json

Key	Use
`"gate"`	The gate command, set with `--gate`
`"auto_sync"`	`false` turns automatic sync of the workspaces that gitta made off
`"parallel"`	How many combination checks run at once, set with `--parallel`
`"security"`	Patterns from `--security`
`"security_block"`	`high`, `medium` or `none`, set with `--security-block`
`"notify"`	`true` turns desktop notifications on, set with `--notify on`

Environment variables

Variable	Use
`GITTA_SERVER`, `GITTA_SERVER_TOKEN`	Team servers and token, for CI runners and cloud agents. Overrides the repository setting.
`GITTA_SERVER_CA`	A PEM file with your own certificate authority, for team servers with private certificates.
`GITTA_ADMIN_TOKEN`	An admin token for `gitta team` commands.
`GITTA_NO_UPDATE_CHECK`	`1` turns the daily update notice off. The daily check sends only the gitta version, the operating system and the processor type to gitta.io. The notice is also off when `CI` is set. To turn it off for good, put `{"update_check": false}` in `~/.config/gitta/config.json`.
`GITTA_MACHINE`	The machine name shown to others. The default is the host name.
`GITTA_AGENT`	Set it in the environment of an agent tool that gitta doesn't recognise. gitta then treats that process as an agent, so it can't run `gitta approve`. Claude Code, Cursor and Codex are recognised on their own.
`GITTA_WEAKENED_CHECKS`	`warn` or `block`. Comes before `.gitta.toml`, for one run or one CI job.
`GITTA_SKIP`	`1` skips gitta's check for one cherry-pick, rebase, reset or update-ref of the protected branch. The skip is recorded in the audit trail.
`GITTA_NO_NOTIFY`	Set it to keep desktop notifications off for one process.
`GITTA_SANDBOX`, `GITTA_FS`	Paths to the `gitta-sandbox` and `gitta-fs` programs on Linux, when they aren't on the `PATH`. See Linux workspaces.
`GITTA_PROFILE`	`1` prints the time of each step to standard error, for measuring performance.