# Command Reference

## Global Flags

- `-v` / `--verbose` — Increase verbosity (up to `-vvv`).
- `--version` — Show version.
- `--help` / `help` — Show help.

## Core

### `arc init [path]`

Initialize a new arc repository. Creates the `.arc/` directory structure including `commits/`, `bookmarks/`, `tags/`, `stashes/`, `config.yml`, and `HEAD`. The default bookmark is `main`.

### `arc commit <message>`

Commit all current changes. No staging area is needed — changes are detected automatically by comparing the worktree to the last commit. Creates a ZSTD-compressed bincode commit object in `.arc/commits/`. If a signing key is configured (`user.key`), the commit is signed with SSH.

### `arc status`

Show added, modified, and deleted files since the last commit.

### `arc diff [start..end]`

Show a unified diff of changes. Without arguments, shows uncommitted changes. With a range, shows the diff between two commits.

### `arc log [start..end]`

Show commit history. Without arguments, shows all commits. Supports ranges like `start..end` (inclusive, either side optional). Each entry shows commit ID, timestamp, author, message, and a `[signed]` tag if applicable.

### `arc show <mark|tag|commit>`

Show full details of a commit including author, date, parent(s), signature verification status, and the diff it introduced. Resolves bookmarks, tags, commit IDs, and commit prefixes.

### `arc history <file> [start..end]`

Show per-line blame/annotation for a file, showing which commit last modified each line. Uses the Myers diff algorithm.

## Branching (Bookmarks)

### `arc mark add <name> [commit]`

Create a bookmark at the given commit. Defaults to HEAD if no commit is specified.

### `arc mark rm <name>`

Remove a bookmark. Cannot remove the active bookmark.

### `arc mark list`

List all bookmarks, marking the active one.

### `arc mark rename <name> <new>`

Rename a bookmark. Updates HEAD if the active bookmark is renamed.

## Tags

### `arc tag add <name> [commit]`

Create an immutable tag at the given commit. Defaults to HEAD if no commit is specified. Tags cannot be overwritten.

### `arc tag rm <name>`

Remove a tag.

### `arc tag list`

List all tags with their commit IDs.

## Navigation

### `arc switch <mark|tag>`

Switch the worktree to a bookmark or tag. Switching to a bookmark attaches HEAD. Switching to a tag or raw commit detaches HEAD. Requires a clean worktree.

### `arc merge <mark|tag>`

Three-way merge from a bookmark or tag into the current worktree. Creates a merge commit with two parents. Reports conflicts with `<<<<<<< ours / ======= / >>>>>>> theirs` markers.

## Undo & Modification

### `arc revert <commit|start..end>`

Create a new commit that reverses the changes from a commit or range. Uses three-way merge.

### `arc reset [file...]`

Reset the worktree to match the last commit. Without arguments, resets all files. With file arguments, resets only those files.

### `arc graft <target> --onto <bookmark|commit>`

Cherry-pick/rebase commit(s) onto a target. Uses three-way merge. If the target is a bookmark, updates the bookmark pointer.

## Stash

### `arc stash create <name>`

Create a named stash and set it as active.

### `arc stash use <name>`

Switch the active stash.

### `arc stash push`

Push dirty changes onto the active stash and reset the worktree.

### `arc stash pop`

Pop the most recent entry from the active stash and apply it to the worktree. Requires a clean worktree and matching HEAD.

### `arc stash rm <name>`

Remove a named stash.

### `arc stash list`

List all named stashes with entry counts.

## Configuration

### `arc config set [-g] <key> <value>`

Set a config value. Use `-g` for global config. Keys use `section.field` format (e.g. `user.name`, `default.bookmark`, `aliases.c`).

### `arc config get [-g] <key>`

Get a config value. Without `-g`, resolves local first, then falls back to global.

### `arc config show [-g]`

Show full configuration as YAML. Without `-g`, shows effective (merged) config.

### `arc config unset [-g] <key>`

Remove a config key.

### Valid Config Fields

- `user.name` — Author name.
- `user.email` — Author email.
- `user.key` — SSH key path for commit signing.
- `default.bookmark` — Default bookmark name (default: `main`).
- `default.remote` — Default remote name (default: `origin`).
- `aliases.<name>` — Command aliases, expanded at the CLI level.

## Git Bridge & Remotes

### `arc remote add <name> <url>`

Add a remote. Stored in `.arc/remotes.yml`.

### `arc remote rm <name>`

Remove a remote.

### `arc remote list`

List all configured remotes.

### `arc push [-r remote]`

Push to a git remote. Converts arc commits to git commits via a shadow git repo (`.arc/git/`), with the mapping stored in `.arc/git-map.yml`.

### `arc pull [-r remote]`

Pull from a git remote. Converts git commits to arc commits. Fast-forward only.

### `arc clone [-b branch] <url> [path]`

Clone a git remote and convert it to an arc repository.

### `arc migrate`

Convert an existing git repository to an arc repository. Imports all branches as bookmarks and all tags. Preserves commit history.

### `arc sync [-p]`

Sync all bookmarks and tags to the shadow git repo. With `-p`, also pushes to the default remote.