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

# Staging & Committing

> Stage changes, create commits, view history, and undo mistakes

<Tip>
  Prefer a visual workflow? See [Changes in the web UI](/local-web-ui/changes).
</Tip>

## The Staging Workflow

Git-Semantic uses the same two-step workflow as Git: **stage** changes first, then **commit** them. This gives you control over exactly what goes into each commit.

```
Working Tree → (vc add) → Staging Area → (vc commit) → Commit History
```

* **Working tree**: The current state of your context tree files on disk
* **Staging area**: A snapshot of changes queued for the next commit
* **Commit history**: The permanent record of all committed snapshots

## Check Working Tree Status

See what has changed in your context tree since the last commit. This is usually the first command you run to understand the current state.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc status
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc status
    ```
  </Tab>
</Tabs>

### What Status Shows

The output includes several sections:

| Section              | Description                                                                          |
| -------------------- | ------------------------------------------------------------------------------------ |
| **Current branch**   | The branch you are on (e.g., `main`, `feature/auth`)                                 |
| **Tracking info**    | How many commits you are ahead/behind the upstream remote branch                     |
| **Merge state**      | Whether a merge is currently in progress                                             |
| **Staged changes**   | Files added to the staging area, ready to be committed                               |
| **Unstaged changes** | Files that have been modified but not yet staged                                     |
| **Untracked files**  | New files that are not being tracked by version control                              |
| **Unmerged paths**   | Files with conflicts during an active merge                                          |
| **Conflict markers** | Files still containing unresolved conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) |

<Tip>
  Run `vc status` frequently to stay aware of your working state — especially before committing, merging, or switching branches.
</Tip>

## Stage Changes

Add files to the staging area to include them in the next commit. Only staged changes are included when you run `vc commit`.

### Stage All Changes

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc add .
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc add .
    ```
  </Tab>
</Tabs>

The `.` stages everything — all modified, deleted, and new (untracked) files in the context tree.

### Stage Specific Files

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Stage a single file
    brv vc add notes.md

    # Stage multiple files
    brv vc add design/architecture.md api/endpoints.md

    # Stage an entire directory
    brv vc add authentication/
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc add notes.md
    /vc add design/architecture.md api/endpoints.md
    /vc add authentication/
    ```
  </Tab>
</Tabs>

### Default Behavior

When no paths are provided, `vc add` defaults to staging everything (equivalent to `vc add .`).

<Note>
  Paths are relative to the context tree root. You can stage individual files, multiple files, or entire directories.
</Note>

## Create a Commit

Save staged changes as a new commit with a descriptive message. Each commit is an immutable snapshot of your context tree at that point in time.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc commit -m "add authentication best practices"
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc commit -m add authentication best practices
    ```
  </Tab>
</Tabs>

### Commit Message

The `-m` flag is **required** — every commit needs an explicit message. There is no auto-generated commit message.

Write messages that describe **what changed and why**:

```bash theme={null}
# Good messages
brv vc commit -m "add JWT token rotation patterns"
brv vc commit -m "reorganize database domain into separate topics"
brv vc commit -m "update API design context after v2 migration"

# Avoid vague messages
brv vc commit -m "update"
brv vc commit -m "changes"
```

### What a Commit Records

Each commit stores:

| Field            | Description                                                         |
| ---------------- | ------------------------------------------------------------------- |
| **SHA**          | A unique ID for this commit (displayed as a short 7-character code) |
| **Message**      | The commit message you provided                                     |
| **Author name**  | From `vc config user.name`                                          |
| **Author email** | From `vc config user.email`                                         |
| **Timestamp**    | When the commit was created                                         |
| **Parent(s)**    | Reference to the previous commit(s)                                 |

### Requirements

* **Author configured**: Both `user.name` and `user.email` must be set via `vc config`
* **Something staged**: At least one file must be in the staging area

### Error Handling

| Error                 | Cause                               | Solution                                             |
| --------------------- | ----------------------------------- | ---------------------------------------------------- |
| `USER_NOT_CONFIGURED` | `user.name` or `user.email` not set | Run `vc config user.name` and `vc config user.email` |
| `NOTHING_STAGED`      | No files in the staging area        | Run `vc add` to stage changes first                  |
| `GIT_NOT_INITIALIZED` | VC not initialized                  | Run `vc init` first                                  |

## View Commit History

Browse the commit log to see what has changed over time.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Show recent commits (default: last 10)
    brv vc log

    # Show more commits
    brv vc log --limit 20

    # Show commits on a specific branch
    brv vc log feature/auth

    # Show commits from all branches
    brv vc log --all

    # Combine flags
    brv vc log --all --limit 50
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc log
    /vc log --limit 20
    /vc log feature/auth
    /vc log --all
    /vc log --all --limit 50
    ```
  </Tab>
</Tabs>

### Log Entry Fields

Each entry in the log includes:

| Field         | Description                           |
| ------------- | ------------------------------------- |
| **SHA**       | The commit's unique ID                |
| **Message**   | The commit message                    |
| **Author**    | Name and email of who made the commit |
| **Timestamp** | When the commit was created           |

### Arguments & Flags

| Argument/Flag | Default        | Description                                              |
| ------------- | -------------- | -------------------------------------------------------- |
| `[branch]`    | Current branch | Show history for a specific branch                       |
| `--limit`     | `10`           | Maximum number of commits to display                     |
| `--all`, `-a` | `false`        | Show commits from all branches, not just the current one |

### Error Handling

| Error              | Cause                          | Solution                                               |
| ------------------ | ------------------------------ | ------------------------------------------------------ |
| `NO_COMMITS`       | No commits exist yet           | Create your first commit with `vc add` and `vc commit` |
| `BRANCH_NOT_FOUND` | Specified branch doesn't exist | Check branch name with `vc branch`                     |

## Unstage Files

Remove files from the staging area without discarding the actual changes. The files remain modified in your working tree.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Unstage all files
    brv vc reset

    # Unstage specific files
    brv vc reset notes.md

    # Unstage multiple files
    brv vc reset design/architecture.md api/endpoints.md
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc reset
    /vc reset notes.md
    /vc reset design/architecture.md api/endpoints.md
    ```
  </Tab>
</Tabs>

This is the equivalent of `git reset` (without `--soft` or `--hard`) — it only affects the staging area, not your working tree.

<Tip>
  Use `vc reset` when you accidentally staged files you didn't intend to commit. Your changes are preserved — only the staging state is cleared.
</Tip>

## Undo Commits

Roll back commits using `--soft` or `--hard` reset. Both move HEAD to a previous commit, but they differ in what happens to your changes.

### Soft Reset

Moves HEAD back but **keeps all changes staged**. The changes from the undone commit(s) remain in the staging area, ready to be re-committed.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Undo the last commit, keep changes staged
    brv vc reset --soft HEAD~1

    # Undo the last 3 commits
    brv vc reset --soft HEAD~3
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc reset --soft HEAD~1
    /vc reset --soft HEAD~3
    ```
  </Tab>
</Tabs>

**Use cases:**

* Re-writing a commit message (soft reset, then commit again with a new message)
* Combining multiple commits into one (soft reset several commits, then commit once)
* Removing a commit but keeping the work

### Hard Reset

Moves HEAD back and **discards all changes**. Your working tree and staging area are reset to match the target commit.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Discard all uncommitted changes (reset to current HEAD)
    brv vc reset --hard

    # Undo the last commit and discard changes
    brv vc reset --hard HEAD~1

    # Reset to a specific commit
    brv vc reset --hard HEAD~3
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc reset --hard
    /vc reset --hard HEAD~1
    /vc reset --hard HEAD~3
    ```
  </Tab>
</Tabs>

<Warning>
  `--hard` reset **permanently discards changes**. There is no way to recover the discarded changes after a hard reset. Make sure you don't need the changes before running this command.
</Warning>

**Use cases:**

* Completely undoing a bad commit
* Resetting to match the remote state after a failed merge
* Starting over from a known good state

### Comparison

| Mode                 | HEAD       | Staging Area      | Working Tree |
| -------------------- | ---------- | ----------------- | ------------ |
| `vc reset` (no flag) | Unchanged  | Cleared           | Unchanged    |
| `vc reset --soft`    | Moved back | **Keeps changes** | Unchanged    |
| `vc reset --hard`    | Moved back | **Cleared**       | **Cleared**  |

<Note>
  `--soft` and `--hard` are mutually exclusive — you cannot use both in the same command.
</Note>

### Error Handling

| Error              | Cause                                  | Solution                                   |
| ------------------ | -------------------------------------- | ------------------------------------------ |
| `INVALID_REF`      | The ref (e.g., `HEAD~5`) doesn't exist | Check how many commits exist with `vc log` |
| `NOTHING_TO_RESET` | No changes to unstage                  | Nothing to do — working tree is clean      |

## Common Workflows

### Basic Edit-Stage-Commit Cycle

The day-to-day workflow for tracking context changes:

```bash theme={null}
# 1. Check what's changed
brv vc status

# 2. Stage your changes
brv vc add .

# 3. Commit with a descriptive message
brv vc commit -m "update API design patterns for v2 endpoints"

# 4. Verify the commit
brv vc log --limit 1
```

### Selective Staging

When you've made changes across multiple domains but want separate commits:

```bash theme={null}
# Stage and commit authentication changes
brv vc add authentication/
brv vc commit -m "add OAuth2 flow documentation"

# Stage and commit database changes separately
brv vc add database/
brv vc commit -m "update connection pooling best practices"
```

### Rewriting a Commit Message

If you made a typo or want a better message:

```bash theme={null}
# Undo the last commit but keep changes staged
brv vc reset --soft HEAD~1

# Re-commit with a new message
brv vc commit -m "add JWT token rotation patterns for auth service"
```

### Squashing Multiple Commits

Combine several small commits into one:

```bash theme={null}
# Soft reset to undo the last 3 commits (changes stay staged)
brv vc reset --soft HEAD~3

# Create a single commit with all those changes
brv vc commit -m "reorganize authentication domain with new subtopics"
```