> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Reference

> Quick reference for all Git-Semantic version control commands

## Command Overview

All commands are available in two modes:

* **CLI**: `brv vc <command> [args] [flags]`
* **TUI (REPL)**: `/vc <command> [args] [flags]`

Both modes accept the same arguments and flags. The examples below use the CLI format — replace `brv vc` with `/vc` for TUI usage.

***

## Setup Commands

### vc init

Initialize version control for the current space.

```bash theme={null}
brv vc init
```

|                   |                                                  |
| ----------------- | ------------------------------------------------ |
| **Arguments**     | None                                             |
| **Flags**         | None                                             |
| **Returns**       | Git directory path, whether it was reinitialized |
| **Prerequisites** | A ByteRover space must exist (`.brv/` directory) |

Safe to re-run — reports "reinitialized" without losing history.

**Errors:** `ALREADY_INITIALIZED`

***

### vc config

Get or set commit author identity. Configuration is **local to the current space** — each space maintains its own author identity.

```bash theme={null}
brv vc config <key> [value]
```

| Argument | Required | Description                                  |
| -------- | -------- | -------------------------------------------- |
| `key`    | Yes      | `user.name` or `user.email`                  |
| `value`  | No       | Value to set. Omit to read the current value |

**Set a value:**

```bash theme={null}
brv vc config user.name "Alice Chen"
brv vc config user.email "alice@example.com"
```

**Read a value:**

```bash theme={null}
brv vc config user.name
# Output: Alice Chen

brv vc config user.email
# Output: alice@example.com
```

**Errors:** `INVALID_CONFIG_KEY`, `CONFIG_KEY_NOT_SET`, `GIT_NOT_INITIALIZED`

***

### vc clone

Clone a remote space from ByteRover cloud.

```bash theme={null}
brv vc clone <url>
```

| Argument | Required              | Description                                |
| -------- | --------------------- | ------------------------------------------ |
| `url`    | Yes (optional in TUI) | `https://byterover.dev/<team>/<space>.git` |

|              |                                              |
| ------------ | -------------------------------------------- |
| **Returns**  | Git directory, team name, space name         |
| **Timeout**  | 120 seconds                                  |
| **TUI only** | Omit URL to open an interactive space picker |

```bash theme={null}
brv vc clone https://byterover.dev/acme/project.git
```

**Errors:** `CLONE_FAILED`, `AUTH_FAILED`, `INVALID_REMOTE_URL`

***

## Staging & History Commands

### vc add

Stage files for the next commit.

```bash theme={null}
brv vc add [files...]
```

| Argument | Required | Description                                                    |
| -------- | -------- | -------------------------------------------------------------- |
| `files`  | No       | File or directory paths to stage. Defaults to `.` (everything) |

Accepts zero or more paths. Paths are relative to the context tree root.

```bash theme={null}
brv vc add .                                  # stage everything
brv vc add notes.md                           # stage one file
brv vc add design/architecture.md docs/       # stage multiple paths
brv vc add authentication/                    # stage an entire directory
```

**Errors:** `GIT_NOT_INITIALIZED`, `FILE_NOT_FOUND`

***

### vc commit

Save staged changes as a commit.

```bash theme={null}
brv vc commit -m "<message>"
```

| Flag              | Required | Description                         |
| ----------------- | -------- | ----------------------------------- |
| `-m`, `--message` | Yes      | Commit message (no auto-generation) |

|                   |                                                                   |
| ----------------- | ----------------------------------------------------------------- |
| **Returns**       | Short SHA (7 characters) and commit message                       |
| **Prerequisites** | `user.name` and `user.email` configured, at least one file staged |

```bash theme={null}
brv vc commit -m "add JWT token rotation patterns"
brv vc commit -m "reorganize database domain into separate topics"
```

**Errors:** `USER_NOT_CONFIGURED`, `NOTHING_STAGED`, `GIT_NOT_INITIALIZED`

***

### vc status

Show working tree status.

```bash theme={null}
brv vc status
```

|               |      |
| ------------- | ---- |
| **Arguments** | None |
| **Flags**     | None |

**Returns:**

| Field            | Description                                    |
| ---------------- | ---------------------------------------------- |
| Current branch   | The branch you are on                          |
| Tracking info    | Ahead/behind upstream count                    |
| Merge state      | Whether a merge is in progress                 |
| Staged changes   | Files ready to commit                          |
| Unstaged changes | Modified files not yet staged                  |
| Untracked files  | New files not being tracked                    |
| Unmerged paths   | Files with conflicts during a merge            |
| Conflict markers | Files containing `<<<<<<<`/`=======`/`>>>>>>>` |

***

### vc diff

Show changes between commits, the index, or the working tree.

```bash theme={null}
brv vc diff [ref] [--staged]
```

| Argument | Required | Description                                                                                  |
| -------- | -------- | -------------------------------------------------------------------------------------------- |
| `ref`    | No       | A commit, branch, or `<ref1>..<ref2>` range. Omit to diff the working tree against the index |

| Flag       | Default | Description                                             |
| ---------- | ------- | ------------------------------------------------------- |
| `--staged` | `false` | Show staged changes (HEAD vs index) instead of unstaged |

The `ref` argument decides what is being compared:

| Form                         | Compared                                                    |
| ---------------------------- | ----------------------------------------------------------- |
| `brv vc diff`                | Working tree vs index (unstaged changes)                    |
| `brv vc diff --staged`       | Index vs HEAD (staged changes)                              |
| `brv vc diff <commit>`       | Working tree vs `<commit>`                                  |
| `brv vc diff <ref1>..<ref2>` | `<ref1>` vs `<ref2>` (commit-to-commit or branch-to-branch) |

```bash theme={null}
brv vc diff                          # unstaged changes vs HEAD
brv vc diff --staged                 # staged changes vs HEAD
brv vc diff HEAD~1                   # working tree vs the previous commit
brv vc diff main                     # working tree vs the main branch
brv vc diff main..feature/x          # compare two branches
```

Also available in the TUI as `/vc diff` with the same arguments and flags.

**Errors:** `INVALID_REF`, `GIT_NOT_INITIALIZED`

***

### vc log

Show commit history.

```bash theme={null}
brv vc log [branch] [--all] [--limit N]
```

| Argument | Required | Description                        |
| -------- | -------- | ---------------------------------- |
| `branch` | No       | Show history for a specific branch |

| Flag          | Default | Description                          |
| ------------- | ------- | ------------------------------------ |
| `--all`, `-a` | `false` | Show commits from all branches       |
| `--limit`     | `10`    | Maximum number of commits to display |

Each log entry includes: SHA, message, author (name + email), timestamp.

```bash theme={null}
brv vc log                        # last 10 commits on current branch
brv vc log --limit 20             # last 20 commits
brv vc log feature/auth           # history of a specific branch
brv vc log --all                  # all branches
brv vc log --all --limit 50       # combine flags
```

**Errors:** `NO_COMMITS`, `BRANCH_NOT_FOUND`, `GIT_NOT_INITIALIZED`

***

### vc reset

Unstage files or undo commits.

```bash theme={null}
brv vc reset [files...]           # unstage files
brv vc reset --soft [ref]         # undo commits, keep staged (ref defaults to HEAD)
brv vc reset --hard [ref]         # reset working tree & staging (ref defaults to HEAD)
```

| Argument | Required | Description               |
| -------- | -------- | ------------------------- |
| `files`  | No       | Specific files to unstage |

| Flag     | Description                                       |
| -------- | ------------------------------------------------- |
| `--soft` | Move HEAD back, keep changes in staging area      |
| `--hard` | Move HEAD back, discard all changes (destructive) |

`--soft` and `--hard` are mutually exclusive.

| Mode     | HEAD       | Staging   | Working Tree |
| -------- | ---------- | --------- | ------------ |
| No flags | Unchanged  | Cleared   | Unchanged    |
| `--soft` | Moved back | Preserved | Unchanged    |
| `--hard` | Moved back | Cleared   | Cleared      |

```bash theme={null}
brv vc reset                       # unstage all files
brv vc reset notes.md              # unstage specific file
brv vc reset --soft HEAD~1         # undo last commit, keep staged
brv vc reset --soft HEAD~3         # undo last 3 commits, keep staged
brv vc reset --hard                # discard all uncommitted changes
brv vc reset --hard HEAD~1         # undo last commit, discard changes
```

**Errors:** `INVALID_REF`, `NOTHING_TO_RESET`, `GIT_NOT_INITIALIZED`

***

## Branching Commands

### vc branch

List, create, or delete branches.

```bash theme={null}
brv vc branch [name] [flags]
```

| Argument | Required | Description           |
| -------- | -------- | --------------------- |
| `name`   | No       | Branch name to create |

| Flag                | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `-a`, `--all`       | List all branches including remote-tracking                    |
| `-d`, `--delete`    | Delete a branch by name                                        |
| `--set-upstream-to` | Set upstream tracking for current branch (e.g., `origin/main`) |

**List branches:**

```bash theme={null}
brv vc branch                                # local branches (* = current)
brv vc branch -a                             # all branches including remote
```

**Create a branch:**

```bash theme={null}
brv vc branch feature/new                    # create (doesn't switch to it)
```

**Delete a branch:**

```bash theme={null}
brv vc branch -d feature/old                 # delete (can't delete current)
```

**Set upstream:**

```bash theme={null}
brv vc branch --set-upstream-to origin/main  # link to remote branch
```

**Errors:** `BRANCH_ALREADY_EXISTS`, `BRANCH_NOT_FOUND`, `BRANCH_NOT_MERGED`, `CANNOT_DELETE_CURRENT_BRANCH`, `INVALID_BRANCH_NAME`

***

### vc checkout

Switch to an existing branch, or create and switch in one step.

```bash theme={null}
brv vc checkout <branch> [-b] [--force]
```

| Argument | Required | Description                               |
| -------- | -------- | ----------------------------------------- |
| `branch` | Yes      | Branch to switch to (or create with `-b`) |

| Flag             | Default | Description                                  |
| ---------------- | ------- | -------------------------------------------- |
| `-b`, `--create` | `false` | Create the branch before switching           |
| `--force`        | `false` | Discard uncommitted changes and force switch |

```bash theme={null}
brv vc checkout main                         # switch to main
brv vc checkout -b feature/new-branch        # create and switch
brv vc checkout --force main                 # discard changes and switch
```

**Errors:** `BRANCH_NOT_FOUND`, `UNCOMMITTED_CHANGES`, `BRANCH_ALREADY_EXISTS` (with `-b`)

***

### vc merge

Merge a branch into the current branch.

```bash theme={null}
brv vc merge [branch] [-m "message"] [--abort] [--continue] [--allow-unrelated-histories]
```

| Argument | Required | Description                                              |
| -------- | -------- | -------------------------------------------------------- |
| `branch` | No       | Branch to merge (not needed with `--abort`/`--continue`) |

| Flag                          | Description                                      |
| ----------------------------- | ------------------------------------------------ |
| `-m`, `--message`             | Custom merge commit message                      |
| `--abort`                     | Cancel current merge and restore pre-merge state |
| `--continue`                  | Complete merge after resolving conflicts         |
| `--allow-unrelated-histories` | Allow merging branches with no common ancestor   |

`--abort` and `--continue` are mutually exclusive.

**Start a merge:**

```bash theme={null}
brv vc merge feature/auth                     # merge with default message
brv vc merge -m "merge auth" feature/auth     # custom commit message
```

**Handle conflicts:**

```bash theme={null}
brv vc merge --continue                       # opens editor for message
brv vc merge --continue -m "resolve conflicts" # inline message
brv vc merge --abort                          # cancel the merge
```

**Unrelated histories:**

```bash theme={null}
brv vc merge --allow-unrelated-histories imported/legacy
```

**Errors:** `MERGE_CONFLICT`, `MERGE_IN_PROGRESS`, `NO_MERGE_IN_PROGRESS`, `CONFLICT_MARKERS_PRESENT`, `ALLOW_UNRELATED_HISTORIES`

***

## Remote Commands

### vc remote

Show, add, update, or remove the remote connection.

```bash theme={null}
brv vc remote                           # show current remote
brv vc remote add <name> <url>          # add a new remote
brv vc remote set-url <name> <url>      # update existing remote URL
brv vc remote remove <name>             # delete the remote
```

Only `origin` is supported as a remote name. URLs must match: `https://byterover.dev/<team>/<space>.git`

**Show:**

```bash theme={null}
brv vc remote
# Output: https://byterover.dev/acme/project.git
```

**Add:**

```bash theme={null}
brv vc remote add origin https://byterover.dev/acme/project.git
```

**Update:**

```bash theme={null}
brv vc remote set-url origin https://byterover.dev/acme/new-project.git
```

**Remove:**

```bash theme={null}
brv vc remote remove origin
# Output: Remote 'origin' removed.
```

After removing the remote, `brv vc push`, `brv vc pull`, and `brv vc fetch` will fail with `NO_REMOTE` until you add it again.

**Errors:** `REMOTE_ALREADY_EXISTS`, `INVALID_REMOTE_URL`, `NO_REMOTE`

***

### vc fetch

Fetch refs from ByteRover cloud without modifying local branches.

```bash theme={null}
brv vc fetch [remote] [branch]
```

| Argument | Required | Description                                        |
| -------- | -------- | -------------------------------------------------- |
| `remote` | No       | Remote name (`origin` only). Defaults to `origin`  |
| `branch` | No       | Specific branch to fetch. Defaults to all branches |

|             |                                                               |
| ----------- | ------------------------------------------------------------- |
| **Timeout** | 120 seconds                                                   |
| **Effect**  | Updates remote-tracking branches only; working tree unchanged |

```bash theme={null}
brv vc fetch                     # fetch all branches
brv vc fetch origin              # same as above (origin is default)
brv vc fetch origin main         # fetch only the main branch
```

**Errors:** `FETCH_FAILED`, `NO_REMOTE`, `AUTH_FAILED`

***

### vc pull

Pull commits from ByteRover cloud (fetch + merge).

```bash theme={null}
brv vc pull [remote] [branch] [--allow-unrelated-histories]
```

| Argument | Required | Description                                            |
| -------- | -------- | ------------------------------------------------------ |
| `remote` | No       | Remote name (`origin` only). Defaults to `origin`      |
| `branch` | No       | Branch to pull. Defaults to upstream of current branch |

| Flag                          | Default | Description                       |
| ----------------------------- | ------- | --------------------------------- |
| `--allow-unrelated-histories` | `false` | Allow merging unrelated histories |

|             |                                        |
| ----------- | -------------------------------------- |
| **Timeout** | 120 seconds                            |
| **Effect**  | Fetches and merges into current branch |

```bash theme={null}
brv vc pull                                              # pull from upstream
brv vc pull origin main                                  # pull specific branch
brv vc pull --allow-unrelated-histories origin main      # merge unrelated
```

**Errors:** `PULL_FAILED`, `NO_REMOTE`, `NO_UPSTREAM`, `MERGE_CONFLICT`, `AUTH_FAILED`

***

### vc push

Push commits to ByteRover cloud.

```bash theme={null}
brv vc push [remote] [branch] [-u]
```

| Argument | Required | Description                                       |
| -------- | -------- | ------------------------------------------------- |
| `remote` | No       | Remote name (`origin` only). Defaults to `origin` |
| `branch` | No       | Branch to push. Defaults to current branch        |

| Flag                   | Default | Description                            |
| ---------------------- | ------- | -------------------------------------- |
| `-u`, `--set-upstream` | `false` | Set remote branch as upstream tracking |

|             |                                                     |
| ----------- | --------------------------------------------------- |
| **Timeout** | 120 seconds                                         |
| **Returns** | Branch name, up-to-date status, upstream-set status |

**Push semantics:**

```bash theme={null}
brv vc push                          # current branch → upstream
brv vc push -u origin main            # push main and set upstream tracking
brv vc push origin                   # current branch → origin
brv vc push origin feat/x            # feat/x → origin
brv vc push feat/x                   # ERROR: "feat/x" is not a valid remote
```

**Errors:** `PUSH_FAILED`, `NON_FAST_FORWARD`, `NOTHING_TO_PUSH`, `NO_REMOTE`, `NO_UPSTREAM`, `AUTH_FAILED`

***

## Error Code Reference

Complete list of error codes across all commands:

### Initialization Errors

| Error Code            | Description        | Solution       |
| --------------------- | ------------------ | -------------- |
| `ALREADY_INITIALIZED` | VC already set up  | Safe to ignore |
| `GIT_NOT_INITIALIZED` | VC not initialized | Run `vc init`  |

### Configuration Errors

| Error Code            | Description                            | Solution                                          |
| --------------------- | -------------------------------------- | ------------------------------------------------- |
| `USER_NOT_CONFIGURED` | Author identity not set                | Set `user.name` and `user.email` with `vc config` |
| `CONFIG_KEY_NOT_SET`  | Requested key has no value             | Set it with `vc config <key> <value>`             |
| `INVALID_CONFIG_KEY`  | Key is not `user.name` or `user.email` | Use a supported key                               |

### Staging & Commit Errors

| Error Code         | Description                  | Solution                  |
| ------------------ | ---------------------------- | ------------------------- |
| `NOTHING_STAGED`   | No files in staging area     | Stage files with `vc add` |
| `NOTHING_TO_RESET` | No changes to unstage        | Working tree is clean     |
| `FILE_NOT_FOUND`   | Specified file doesn't exist | Check the file path       |
| `INVALID_REF`      | Git ref doesn't exist        | Verify with `vc log`      |
| `NO_COMMITS`       | No commits in history        | Create your first commit  |

### Branch Errors

| Error Code                     | Description                                    | Solution                                                           |
| ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------ |
| `BRANCH_NOT_FOUND`             | Branch doesn't exist                           | Check names with `vc branch`                                       |
| `BRANCH_ALREADY_EXISTS`        | Branch name is taken                           | Choose a different name                                            |
| `CANNOT_DELETE_CURRENT_BRANCH` | On the branch being deleted                    | Switch to another branch first                                     |
| `BRANCH_NOT_MERGED`            | Branch has unmerged commits                    | Merge the branch first, or verify you no longer need those commits |
| `INVALID_BRANCH_NAME`          | Invalid characters in name                     | Use alphanumeric, `/`, `-`, `_`, `.`                               |
| `UNCOMMITTED_CHANGES`          | Uncommitted changes block operation            | Commit changes or use `--force`                                    |
| `NO_BRANCH_RESOLVED`           | Could not determine which branch to operate on | Specify the branch explicitly or check out a branch first          |

### Merge Errors

| Error Code                 | Description                         | Solution                                         |
| -------------------------- | ----------------------------------- | ------------------------------------------------ |
| `MERGE_CONFLICT`           | Conflicting changes detected        | Resolve conflicts, then `vc merge --continue`    |
| `MERGE_IN_PROGRESS`        | A merge is already underway         | `--continue` or `--abort` first                  |
| `NO_MERGE_IN_PROGRESS`     | No active merge to continue/abort   | Nothing to do                                    |
| `CONFLICT_MARKERS_PRESENT` | Unresolved markers in files         | Remove all `<<<<<<<`/`=======`/`>>>>>>>` markers |
| `UNRELATED_HISTORIES`      | No common ancestor between branches | Add `--allow-unrelated-histories` flag           |

### Remote & Sync Errors

| Error Code              | Description                 | Solution                                                          |
| ----------------------- | --------------------------- | ----------------------------------------------------------------- |
| `NO_REMOTE`             | No remote configured        | `vc remote add origin <url>`                                      |
| `REMOTE_ALREADY_EXISTS` | Remote `origin` already set | Use `vc remote set-url` to update                                 |
| `INVALID_REMOTE_URL`    | URL format is wrong         | Use `https://byterover.dev/<team>/<space>.git`                    |
| `NO_UPSTREAM`           | No upstream tracking branch | Use `vc push -u origin <branch>` or `vc branch --set-upstream-to` |
| `NON_FAST_FORWARD`      | Remote has newer commits    | Pull first, resolve conflicts, then push                          |
| `NOTHING_TO_PUSH`       | No new local commits        | Already up to date                                                |
| `CLONE_FAILED`          | Clone operation failed      | Check URL and network connection                                  |
| `FETCH_FAILED`          | Fetch operation failed      | Check network connection                                          |
| `PULL_FAILED`           | Pull operation failed       | Check network connection                                          |
| `PUSH_FAILED`           | Push operation failed       | Check network connection                                          |
| `NETWORK_ERROR`         | Network connectivity issue  | Check your internet connection and try again                      |
| `AUTH_FAILED`           | Authentication failed       | Log in with `brv login` and verify access                         |

### Legacy Command Errors

| Error Code           | Description                                       | Solution                                                                            |
| -------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `VC_GIT_INITIALIZED` | Legacy `brv push`/`brv pull` used after `vc init` | Use `brv vc push` / `brv vc pull` instead. See [Migration](/git-semantic/migration) |