Xit (xit)
Rule (when to trigger)
Use xit instead of git when either is true:
- A
.xit/directory exists in this repo (including in a parent directory). - The user explicitly asks for xit (e.g. “use xit”, “.xit repo”, “xit status”).
If the repo is not a xit repo and the user didn’t ask for xit, do not force this skill.
Non-interactive defaults
- Never run bare
xit(it launches the TUI). - Always use
--cliforstatus,diff,diff-added, andlog(their default is TUI). - Avoid TUI entrypoints (e.g.
xit config); usexit config list|add|rm...instead. - Prefer
--cliwhenever it’s available; checkxit <cmd> --helpif unsure.
Preflight
- Confirm
xitis available:command -v xit.
- If missing, ask the user to install/provide xit. - If they decline, do not attempt to “fake it” with git; ask how they want to proceed.
- Confirm you’re in a xit repo:
- Prefer: xit status --cli (it should discover .xit/ from subdirectories).
Top mapping (git-like intent → xit)
| Intent | xit | Notes |
|---|---|---|
| status | xit status --cli | Text output for agents. |
| diff (working tree) | xit diff --cli | Changes not added to index. |
| diff --cached | xit diff-added --cli | Index vs last commit. |
| add / stage | xit add <path> | Stage file contents. |
| unstage | xit unadd <path> | Like git reset HEAD <path>. |
| restore (work dir) | xit restore <path> | Discard local changes for a path. |
| rm --cached | xit untrack <path> | Stop tracking but keep the file. |
| rm | xit rm <path> | Stop tracking and delete the file. |
| commit | xit commit -m "msg" | Use a quoted message. |
| log | xit log --cli | Text output for agents. |
| branch list / create / delete | xit branch list / xit branch add <name> / xit branch rm <name> | |
| switch / checkout | xit switch <name-or-oid> | Updates index + working dir. |
| merge | xit merge <branch-or-oid> | Patch-based merge by default. |
| cherry-pick | xit cherry-pick <oid> | Apply an existing commit. |
For a more complete mapping and workflows, see references/cli.md.
Common workflows
Inspect changes
xit status --clixit diff --clixit diff-added --cli
Commit cycle
xit status --clixit diff --clixit add <paths...>xit diff-added --clixit commit -m "<message>"
Merge / cherry-pick (conflicts)
- Start:
xit merge <branch-or-oid>orxit cherry-pick <oid>. - Inspect:
xit status --cliandxit diff --cli. - If conflicts:
- Resolve conflicts in the working tree. - Stage resolutions: xit add <resolved-paths...> then xit diff-added --cli. - Continue: xit merge --continue or xit cherry-pick --continue.
- To abandon the operation:
xit merge --abortorxit cherry-pick --abort.
Reset semantics (git reset equivalents)
- Move branch pointer, index only:
xit reset <ref-or-oid>(likegit reset --mixed). - Move branch pointer + working dir:
xit reset-dir <ref-or-oid>(likegit reset --hard). - Move branch pointer only:
xit reset-add <ref-or-oid>(likegit reset --soft).
Remotes (pull is not implemented)
- Manage remotes:
xit remote add|rm|list... - Pull equivalent:
- xit fetch <remote> - xit merge refs/remotes/<remote>/<branch> (choose <branch> by inspecting refs or xit log --cli after fetch)
- Push:
- xit push <remote> <branch>
Guardrails
- Require explicit user confirmation before running:
xit rm <path>(deletes file),xit restore <path>/xit reset-dir <ref-or-oid>(discard local changes), orxit push... -f/xit push <remote>:<branch>(force push / delete remote branch). - Prefer
xit untrack <path>when the user wants to stop tracking but keep the file. - Do not run
gitinside a.xitrepo unless the user explicitly requests git.
If a command seems missing
- Check
xit --helpandxit <cmd> --help. - If it isn’t available, explain the limitation and ask for direction.
Notes
- Patch-based merge controls:
xit patch on|off|all.