Branching & Merging

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.

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.

# List local branches only
brv vc branch

# List all branches (including remote-tracking)
brv vc branch -a

/vc branch
/vc branch -a

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.

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

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.

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

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:

brv vc merge -m "merge auth patterns into main" feature/auth-patterns

/vc merge -m "merge auth patterns into main" feature/auth-patterns

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:

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:

brv vc status

/vc status

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

To resolve:

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:

brv vc add .

/vc add .

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

If no -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:

brv vc merge --abort

/vc merge --abort

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

​Understanding Branches

​List Branches

​Flags

​Create a Branch

​Error Handling

​Switch Branches

​Create and Switch in One Step

​Force Switch

​Flags

​Error Handling

​Delete a Branch

​Error Handling

​Set Upstream Tracking

​Merge a Branch

​Basic Merge

​Merge with Custom Message

​Merge Unrelated Histories

​Merge Outcomes

​Flags

​Error Handling

​Resolve Merge Conflicts

​Abort a Merge

​Branching Workflow Examples

​Feature Branch Workflow

​Team Collaboration Workflow

​Experiment and Discard

Understanding Branches

List Branches

Flags

Create a Branch

Error Handling

Switch Branches

Create and Switch in One Step

Force Switch

Flags

Error Handling

Delete a Branch

Error Handling

Set Upstream Tracking

Merge a Branch

Basic Merge

Merge with Custom Message

Merge Unrelated Histories

Merge Outcomes

Flags

Error Handling

Resolve Merge Conflicts

Abort a Merge

Branching Workflow Examples

Feature Branch Workflow

Team Collaboration Workflow

Experiment and Discard