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 --cli for status, diff, diff-added, and log (their default is TUI).
• Avoid TUI entrypoints (e.g. xit config); use xit config list|add|rm ... instead.
• Prefer --cli whenever it’s available; check xit <cmd> --help if unsure.

Preflight

1. Confirm xit is 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.
2. 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 --cli
• xit diff --cli
• xit diff-added --cli

Commit cycle

• xit status --cli
• xit diff --cli
• xit add <paths...>
• xit diff-added --cli
• xit commit -m "<message>"

Merge / cherry-pick (conflicts)

• Start: xit merge <branch-or-oid> or xit cherry-pick <oid>.
• Inspect: xit status --cli and xit 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 --abort or xit cherry-pick --abort.

Reset semantics (git reset equivalents)

• Move branch pointer, index only: xit reset <ref-or-oid> (like git reset --mixed).
• Move branch pointer + working dir: xit reset-dir <ref-or-oid> (like git reset --hard).
• Move branch pointer only: xit reset-add <ref-or-oid> (like git 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), or xit 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 git inside a .xit repo unless the user explicitly requests git.

If a command seems missing

• Check xit --help and xit <cmd> --help.
• If it isn’t available, explain the limitation and ask for direction.

Notes

• Patch-based merge controls: xit patch on|off|all.