Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.byterover.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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
The current branch is marked with * in the output. Remote-tracking branches (shown with -a) appear as origin/<branch-name>.

​
Flags

FlagDefaultDescription
-a, --allfalseInclude 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
Creating a branch does not switch to it. Your working tree stays on the current branch. Use vc checkout to switch.

​
Error Handling

ErrorCauseSolution
BRANCH_ALREADY_EXISTSA branch with that name already existsChoose a different name, or delete the existing branch first
INVALID_BRANCH_NAMEThe branch name contains invalid charactersUse 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

​
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
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
--force permanently discards any uncommitted changes in your working tree. Commit your work before force-switching if you want to keep it.

​
Flags

FlagDefaultDescription
-b, --createfalseCreate a new branch and switch to it
--forcefalseDiscard uncommitted changes and force the switch

​
Error Handling

ErrorCauseSolution
BRANCH_NOT_FOUNDThe target branch doesn’t existCheck available branches with vc branch
UNCOMMITTED_CHANGESYou have uncommitted changes that conflictCommit your changes first, or use --force to discard them
BRANCH_ALREADY_EXISTSUsing -b but the branch already existsOmit -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

​
Error Handling

ErrorCauseSolution
CANNOT_DELETE_CURRENT_BRANCHYou’re currently on this branchSwitch to another branch first with vc checkout
BRANCH_NOT_MERGEDThe branch has commits not merged into the current branchMerge the branch first with vc merge, or verify you no longer need those commits
BRANCH_NOT_FOUNDThe branch doesn’t existCheck 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
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
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

​
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

​
Merge Outcomes

A merge can result in one of three outcomes:
OutcomeDescriptionWhat Happens
Already up to dateThe source branch has no new commitsNothing changes
Fast-forward or clean mergeNo conflicts between the branchesA merge commit is created automatically
ConflictBoth branches modified the same filesMerge pauses — you must resolve conflicts manually

​
Flags

FlagDescription
-m, --messageCustom merge commit message
--abortCancel the current merge and restore the previous state
--continueComplete the merge after resolving conflicts
--allow-unrelated-historiesAllow merging branches with no common ancestor
--abort and --continue are mutually exclusive — you cannot use both in the same command.

​
Error Handling

ErrorCauseSolution
MERGE_CONFLICTConflicting changes in both branchesResolve conflicts and run vc merge --continue
MERGE_IN_PROGRESSA merge is already underwayComplete it with --continue or cancel with --abort
NO_MERGE_IN_PROGRESSTried --continue/--abort with no active mergeNothing to continue or abort
UNRELATED_HISTORIESBranches have no common ancestorAdd --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.
1

Check merge status

Confirm the merge state and see which files are affected:
brv vc status
Status will show that a merge is in progress and list unmerged paths.
2

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:
  1. Decide which content to keep (or combine both)
  2. Remove the conflict markers (<<<<<<<, =======, >>>>>>>)
  3. 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.
3

Stage the resolved files

After resolving all conflicts, stage the fixed files:
brv vc add .
4

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