Understanding Branches
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.
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.
- 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.
# List local branches only
brv vc branch
# List all branches (including remote-tracking)
brv vc branch -a
* 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.
brv vc branch feature/auth-patterns
/vc branch feature/auth-patterns
Creating a branch does not switch to it. Your working tree stays on the current branch. Use vc checkout to switch.
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.
brv vc checkout feature/auth-patterns
/vc checkout feature/auth-patterns
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.
brv vc checkout -b feature/new-context
/vc checkout -b feature/new-context
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.
brv vc checkout --force main
/vc checkout --force main
--force permanently discards any uncommitted changes in your working tree. Commit your work before force-switching if you want to keep it.
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.
brv vc branch -d feature/old-experiment
/vc branch -d feature/old-experiment
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.
brv vc branch --set-upstream-to origin/main
/vc branch --set-upstream-to origin/main
You can also set upstream tracking during push with brv vc push -u origin <branch>, which pushes and sets the upstream in one step.
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
brv vc merge feature/auth-patterns
/vc merge feature/auth-patterns
Merge with Custom Message
Provide a custom message for the merge commit instead of the default:
brv vc merge -m "merge auth patterns into main" feature/auth-patterns
/vc merge -m "merge auth patterns into main" feature/auth-patterns
--allow-unrelated-histories flag to override:
brv vc merge --allow-unrelated-histories imported/legacy
/vc merge --allow-unrelated-histories imported/legacy
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 |
--abort and --continue are mutually exclusive — you cannot use both in the same command.
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.
Check merge status
Confirm the merge state and see which files are affected:Status will show that a merge is in progress and list unmerged paths. 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:<<<<<<< HEAD
Content from your current branch (the branch you're merging into)
=======
Content from the source branch (the branch being merged)
>>>>>>> feature/auth-patterns
- Decide which content to keep (or combine both)
- Remove the conflict markers (
<<<<<<<, =======, >>>>>>>)
- Save the file
All conflict markers must be removed before you can complete the merge. The CONFLICT_MARKERS_PRESENT error will occur if any remain.
Stage the resolved files
After resolving all conflicts, stage the fixed files: Complete the merge
Finalize the merge by creating the merge commit:# 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
/vc merge --continue -m "resolve auth conflicts and merge"
/vc merge --continue
-m flag is provided, your configured editor ($GIT_EDITOR or $EDITOR or vim) opens for you to write the commit message. Abort a Merge
If you want to cancel a merge entirely and restore the state before the merge started:
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:
# 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:
# 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:
# 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
