# Tkersey Dotfiles Xit

> Xit (xit)

- Skill: `tomevault-io/tkersey-dotfiles-xit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/tkersey-dotfiles-xit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/tkersey-dotfiles-xit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/tkersey-dotfiles-xit

---


# 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`.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/tkersey) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->