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

# Branching & Merging

> Work in parallel with branches, merge changes, and resolve conflicts

## Understanding Branches

<Tip>
  **Most users only need the `main` branch.** Branching is useful for teams or advanced workflows, but if you're working solo or just getting started, staying on `main` is perfectly fine — you can always create branches later.
</Tip>

<Note>
  **Web app:** The ByteRover web dashboard currently supports the `main` branch only. Multi-branch support in the web app is coming soon. In the CLI and TUI, all branching features are fully available now.
</Note>

Branches let you work on different versions of your context tree in parallel. Each branch is an independent line of development — changes on one branch don't affect others until you explicitly merge them.

Common use cases:

* **Feature branches**: Experiment with new domain structures or context reorganization
* **Team branches**: Each team member curates context independently, then merges
* **Release branches**: Maintain a stable context baseline while developing new content

## List Branches

View the branches in your context tree.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # List local branches only
    brv vc branch

    # List all branches (including remote-tracking)
    brv vc branch -a
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc branch
    /vc branch -a
    ```
  </Tab>
</Tabs>

The current branch is marked with `*` in the output. Remote-tracking branches (shown with `-a`) appear as `origin/<branch-name>`.

### Flags

| Flag          | Default | Description                                     |
| ------------- | ------- | ----------------------------------------------- |
| `-a`, `--all` | `false` | Include remote-tracking branches in the listing |

## Create a Branch

Create a new branch from the current HEAD. The new branch points to the same commit you're currently on.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc branch feature/auth-patterns
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc branch feature/auth-patterns
    ```
  </Tab>
</Tabs>

<Note>
  Creating a branch does **not** switch to it. Your working tree stays on the current branch. Use `vc checkout` to switch.
</Note>

### Error Handling

| Error                   | Cause                                       | Solution                                                            |
| ----------------------- | ------------------------------------------- | ------------------------------------------------------------------- |
| `BRANCH_ALREADY_EXISTS` | A branch with that name already exists      | Choose a different name, or delete the existing branch first        |
| `INVALID_BRANCH_NAME`   | The branch name contains invalid characters | Use valid branch name characters (alphanumeric, `/`, `-`, `_`, `.`) |

## Switch Branches

Switch your working tree to a different branch. This updates all context tree files to match the target branch's latest commit.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc checkout feature/auth-patterns
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc checkout feature/auth-patterns
    ```
  </Tab>
</Tabs>

### Create and Switch in One Step

Use the `-b` flag to create a new branch and immediately switch to it. This is the most common way to start working on a new branch.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc checkout -b feature/new-context
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc checkout -b feature/new-context
    ```
  </Tab>
</Tabs>

This is equivalent to running `vc branch feature/new-context` followed by `vc checkout feature/new-context`.

### Force Switch

If you have uncommitted changes that would conflict with the target branch, the checkout will fail with an `UNCOMMITTED_CHANGES` error. Use `--force` to discard those changes and switch anyway.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc checkout --force main
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc checkout --force main
    ```
  </Tab>
</Tabs>

<Warning>
  `--force` permanently discards any uncommitted changes in your working tree. Commit your work before force-switching if you want to keep it.
</Warning>

### Flags

| Flag             | Default | Description                                      |
| ---------------- | ------- | ------------------------------------------------ |
| `-b`, `--create` | `false` | Create a new branch and switch to it             |
| `--force`        | `false` | Discard uncommitted changes and force the switch |

### Error Handling

| Error                   | Cause                                      | Solution                                                    |
| ----------------------- | ------------------------------------------ | ----------------------------------------------------------- |
| `BRANCH_NOT_FOUND`      | The target branch doesn't exist            | Check available branches with `vc branch`                   |
| `UNCOMMITTED_CHANGES`   | You have uncommitted changes that conflict | Commit your changes first, or use `--force` to discard them |
| `BRANCH_ALREADY_EXISTS` | Using `-b` but the branch already exists   | Omit `-b` to switch to the existing branch                  |

## Delete a Branch

Remove a branch you no longer need. This deletes the branch pointer only — the commits it pointed to are preserved in the history.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc branch -d feature/old-experiment
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc branch -d feature/old-experiment
    ```
  </Tab>
</Tabs>

### Error Handling

| Error                          | Cause                                                     | Solution                                                                           |
| ------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `CANNOT_DELETE_CURRENT_BRANCH` | You're currently on this branch                           | Switch to another branch first with `vc checkout`                                  |
| `BRANCH_NOT_MERGED`            | The branch has commits not merged into the current branch | Merge the branch first with `vc merge`, or verify you no longer need those commits |
| `BRANCH_NOT_FOUND`             | The branch doesn't exist                                  | Check the name with `vc branch`                                                    |

## Set Upstream Tracking

Link your current local branch to a remote-tracking branch. This enables `vc status` to show ahead/behind counts and allows `vc pull`/`vc push` to work without specifying the remote and branch.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc branch --set-upstream-to origin/main
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc branch --set-upstream-to origin/main
    ```
  </Tab>
</Tabs>

<Tip>
  You can also set upstream tracking during push with `brv vc push -u origin <branch>`, which pushes and sets the upstream in one step.
</Tip>

## Merge a Branch

Merge another branch into your current branch. This incorporates all the commits from the source branch into your current branch.

### Basic Merge

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc merge feature/auth-patterns
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc merge feature/auth-patterns
    ```
  </Tab>
</Tabs>

If the merge completes without conflicts, a merge commit is created automatically.

### Merge with Custom Message

Provide a custom message for the merge commit instead of the default:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc merge -m "merge auth patterns into main" feature/auth-patterns
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc merge -m "merge auth patterns into main" feature/auth-patterns
    ```
  </Tab>
</Tabs>

### Merge Unrelated Histories

When merging branches that share no common ancestor (e.g., importing context from a completely separate space), Git-Semantic will refuse the merge by default. Use the `--allow-unrelated-histories` flag to override:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc merge --allow-unrelated-histories imported/legacy
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc merge --allow-unrelated-histories imported/legacy
    ```
  </Tab>
</Tabs>

### Merge Outcomes

A merge can result in one of three outcomes:

| Outcome                         | Description                           | What Happens                                       |
| ------------------------------- | ------------------------------------- | -------------------------------------------------- |
| **Already up to date**          | The source branch has no new commits  | Nothing changes                                    |
| **Fast-forward or clean merge** | No conflicts between the branches     | A merge commit is created automatically            |
| **Conflict**                    | Both branches modified the same files | Merge pauses — you must resolve conflicts manually |

### Flags

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

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

### Error Handling

| Error                  | Cause                                             | Solution                                               |
| ---------------------- | ------------------------------------------------- | ------------------------------------------------------ |
| `MERGE_CONFLICT`       | Conflicting changes in both branches              | Resolve conflicts and run `vc merge --continue`        |
| `MERGE_IN_PROGRESS`    | A merge is already underway                       | Complete it with `--continue` or cancel with `--abort` |
| `NO_MERGE_IN_PROGRESS` | Tried `--continue`/`--abort` with no active merge | Nothing to continue or abort                           |
| `UNRELATED_HISTORIES`  | Branches have no common ancestor                  | Add `--allow-unrelated-histories` flag                 |

## Resolve Merge Conflicts

When a merge produces conflicts, the merge pauses and waits for you to manually resolve them. Conflicts occur when both branches modified the same part of the same file.

<Steps>
  <Step title="Check merge status">
    Confirm the merge state and see which files are affected:

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

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

    Status will show that a merge is in progress and list unmerged paths.
  </Step>

  <Step title="Edit the conflicting files">
    The status output lists unmerged paths and files with conflict markers.
    Open each conflicting file and resolve the conflict markers. A typical conflict looks like:

    ```markdown theme={null}
    <<<<<<< HEAD
    Content from your current branch (the branch you're merging into)
    =======
    Content from the source branch (the branch being merged)
    >>>>>>> feature/auth-patterns
    ```

    To resolve:

    1. Decide which content to keep (or combine both)
    2. Remove the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
    3. Save the file

    <Warning>
      All conflict markers must be removed before you can complete the merge. The `CONFLICT_MARKERS_PRESENT` error will occur if any remain.
    </Warning>
  </Step>

  <Step title="Stage the resolved files">
    After resolving all conflicts, stage the fixed files:

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

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

  <Step title="Complete the merge">
    Finalize the merge by creating the merge commit:

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        # With a custom message
        brv vc merge --continue -m "resolve auth conflicts and merge"

        # Without -m (opens your configured editor for the message)
        brv vc merge --continue
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /vc merge --continue -m "resolve auth conflicts and merge"
        /vc merge --continue
        ```
      </Tab>
    </Tabs>

    If no `-m` flag is provided, your configured editor (`$GIT_EDITOR` or `$EDITOR` or `vim`) opens for you to write the commit message.
  </Step>
</Steps>

### Abort a Merge

If you want to cancel a merge entirely and restore the state before the merge started:

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

  <Tab title="TUI">
    ```
    /vc merge --abort
    ```
  </Tab>
</Tabs>

This is safe — it discards the merge state and returns your working tree to the pre-merge state. No commits are lost.

## Branching Workflow Examples

### Feature Branch Workflow

The most common pattern — create a branch, make changes, merge back:

```bash theme={null}
# 1. Start a feature branch
brv vc checkout -b feature/restructure-api-docs

# 2. Make changes, stage, and commit (repeat as needed)
brv vc add .
brv vc commit -m "reorganize API patterns by endpoint type"

brv vc add .
brv vc commit -m "add rate limiting context to API domain"

# 3. Switch back to main
brv vc checkout main

# 4. Merge the feature branch
brv vc merge feature/restructure-api-docs

# 5. Clean up the feature branch
brv vc branch -d feature/restructure-api-docs

# 6. Push the merged result to cloud
brv vc push
```

### Team Collaboration Workflow

Multiple team members working on different context areas:

```bash theme={null}
# Alice works on authentication context
brv vc checkout -b alice/auth-patterns
brv vc add authentication/
brv vc commit -m "add OAuth2 and SAML patterns"
brv vc push -u origin alice/auth-patterns

# Bob works on database context (on his machine)
brv vc checkout -b bob/database-patterns
brv vc add database/
brv vc commit -m "add connection pooling and migration patterns"
brv vc push -u origin bob/database-patterns

# When ready, merge both into main
brv vc checkout main
brv vc pull
brv vc merge alice/auth-patterns
brv vc merge bob/database-patterns
brv vc push
```

### Experiment and Discard

Try a risky restructuring without affecting your main context:

```bash theme={null}
# Create an experiment branch
brv vc checkout -b experiment/flat-structure

# Try restructuring...
brv vc add .
brv vc commit -m "flatten all domains into single level"

# Decided it didn't work? Switch back and delete
brv vc checkout main
brv vc branch -d experiment/flat-structure
```