Skip to main content

​
Prerequisites

Before using Git-Semantic version control, make sure you have:
  • ByteRover CLI installed — See Quickstart for installation instructions
That’s it for local use. You can initialize, stage, commit, branch, and merge with no account and no internet connection.
For cloud sync only (push, pull, fetch, clone): You also need a ByteRover account and a remote space. See Remote Sync for details.

​
Initialize Version Control

Set up Git-Semantic version control for your context tree. This is required before you can use any other vc commands. 
brv vc init

​
What vc init Does

  • Creates the internal Git data structures inside your .brv/ directory
  • Sets up the default main branch
  • Prepares the staging area (index) for tracking changes
If version control is already initialized, the command is safe to re-run — it will report that it was reinitialized without losing any existing history.
If you cloned a space with vc clone, version control is already initialized — you don’t need to run vc init.
If your project is also a Git repository, vc init automatically adds .brv/ to your .gitignore to prevent conflicts with the nested Git repository inside .brv/context-tree/.

​
Configure Author Identity

Before you can commit, you must set your name and email. These are attached to every commit you create, identifying who made each change.
1

Set your name

brv vc config user.name "Alice Chen"
2

Set your email

brv vc config user.email "alice@example.com"
3

Verify your configuration

Read back the values to confirm they were set correctly:
brv vc config user.name
# Output: Alice Chen

brv vc config user.email
# Output: alice@example.com
Configuration is local to the current space — it does not apply globally. Each space has its own author identity, so you need to configure user.name and user.email per space.

​
Supported Configuration Keys

KeyDescriptionExample
user.nameAuthor name shown in commit log"Alice Chen"
user.emailAuthor email shown in commit log"alice@example.com"
Only these two keys are supported. Attempting to set other keys will result in an INVALID_CONFIG_KEY error.

​
Reading vs Setting

  • Set a value: brv vc config <key> <value> — provide both the key and the value
  • Read a value: brv vc config <key> — omit the value to read the current setting
If a key hasn’t been set yet, reading it returns a CONFIG_KEY_NOT_SET error.

​
Error Handling

ErrorCauseSolution
INVALID_CONFIG_KEYKey is not user.name or user.emailUse a supported key
CONFIG_KEY_NOT_SETKey hasn’t been configured yetSet it with vc config <key> <value>
GIT_NOT_INITIALIZEDVC not initializedRun vc init first

​
Clone a Remote Space

To work with an existing space from ByteRover cloud, clone it to your local machine. This downloads the full context tree along with its complete commit history. 
brv vc clone https://byterover.dev/acme/project.git

​
Clone URL Format

https://byterover.dev/<team>/<space>.git
SegmentDescriptionExample
<team>Your team or organization nameacme
<space>The space nameproject
You can find the clone URL on the space’s page in the ByteRover Dashboard.

​
What vc clone Does

  1. Downloads the full commit history from ByteRover cloud
  2. Creates the .brv/ directory with the context tree
  3. Checks out the default branch (usually main)
  4. Configures origin remote pointing to the cloud space
  5. Streams real-time progress during the download (CLI)

​
Error Handling

ErrorCauseSolution
CLONE_FAILEDNetwork error or invalid URLCheck the URL and your internet connection
AUTH_FAILEDNot authenticated or insufficient permissionsLog in with brv login and verify team access
INVALID_REMOTE_URLURL doesn’t match the expected formatUse the format https://byterover.dev/<team>/<space>.git
Clone operations have a 120-second timeout. For spaces with very large context trees, ensure a stable network connection.
If your project is also a Git repository, vc clone automatically adds .brv/ to your .gitignore. This prevents git add . from failing due to the nested Git repository inside .brv/context-tree/.

​
Typical First-Time Setup

​
Local Only (no account needed)

Use Git-Semantic purely on your machine — no login, no cloud, no remote space: 
# 1. Initialize project and version control
brv vc init

# 2. Configure your identity
brv vc config user.name "Alice Chen"
brv vc config user.email "alice@example.com"

# 3. Curate some context (via your coding agent or manually)
# ... add context to your context tree ...

# 4. Stage and commit
brv vc add .
brv vc commit -m "initial context tree"

# 5. Branch, merge, reset — all local, all offline
brv vc checkout -b experiment

​
Local to Cloud (requires login + remote space)

Start locally, then push to ByteRover cloud when you’re ready to collaborate: 
# 1. Initialize project and version control
brv vc init

# 2. Configure your identity
brv vc config user.name "Alice Chen"
brv vc config user.email "alice@example.com"

# 3. Curate some context (via your coding agent or manually)
# ... add context to your context tree ...

# 4. Stage and commit
brv vc add .
brv vc commit -m "initial context tree"

# 5. Log in and connect to a remote space
brv login --api-key <your-api-key>
brv vc remote add origin https://byterover.dev/acme/project.git

# 6. Push to cloud and set upstream tracking
brv vc push -u origin main

​
Clone an Existing Space (requires login)

Join a team project by cloning an existing space from ByteRover cloud: 
# 1. Log in
brv login --api-key <your-api-key>

# 2. Clone the remote space
brv vc clone https://byterover.dev/acme/project.git

# 3. Configure your identity for this space
brv vc config user.name "Bob Smith"
brv vc config user.email "bob@example.com"

# 4. Verify everything is set up
brv vc status
brv vc log --limit 5

​
What’s Next

Now that version control is set up, learn how to track changes:

Staging & Committing

Stage changes, create commits, and view history

Remote Sync

Push and pull context to ByteRover cloud