Getting Started

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

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

Set your name

brv vc config user.name "Alice Chen"

/vc config user.name "Alice Chen"

Set your email

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

/vc config user.email "alice@example.com"

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

/vc config user.name
/vc config user.email

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

Key	Description	Example
`user.name`	Author name shown in commit log	`"Alice Chen"`
`user.email`	Author 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

Error	Cause	Solution
`INVALID_CONFIG_KEY`	Key is not `user.name` or `user.email`	Use a supported key
`CONFIG_KEY_NOT_SET`	Key hasn’t been configured yet	Set it with `vc config <key> <value>`
`GIT_NOT_INITIALIZED`	VC not initialized	Run `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

You can provide the URL directly:

/vc clone https://byterover.dev/acme/project.git

Or omit the URL to browse your team’s spaces with an interactive picker:

/vc clone

Clone URL Format

https://byterover.dev/<team>/<space>.git

Segment	Description	Example
`<team>`	Your team or organization name	`acme`
`<space>`	The space name	`project`

You can find the clone URL on the space’s page in the ByteRover Dashboard.

What `vc clone` Does

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

Error Handling

Error	Cause	Solution
`CLONE_FAILED`	Network error or invalid URL	Check the URL and your internet connection
`AUTH_FAILED`	Not authenticated or insufficient permissions	Log in with `brv login` and verify team access
`INVALID_REMOTE_URL`	URL doesn’t match the expected format	Use 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

/vc init
/vc config user.name "Alice Chen"
/vc config user.email "alice@example.com"
/vc add .
/vc commit -m "initial context tree"
/vc checkout -b experiment

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                           # opens your browser for OAuth
# on CI / SSH, use: 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

/vc init
/vc config user.name "Alice Chen"
/vc config user.email "alice@example.com"
/vc add .
/vc commit -m "initial context tree"
/login
/vc remote add origin https://byterover.dev/acme/project.git
/vc push -u origin main

Join a team project by cloning an existing space from ByteRover cloud:

# 1. Log in
brv login                           # opens your browser for OAuth
# on CI / SSH, use: 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

/login
/vc clone https://byterover.dev/acme/project.git
/vc config user.name "Bob Smith"
/vc config user.email "bob@example.com"
/vc status
/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

LLM Providers

Agent Connectors

Context Tree

Knowledge Sharing

Memory Swarm

Git-Semantic Version Control

Review Changes

BRV Hub

Headless Mode

Daemon-First Architecture

Local Web UI

Reference

FAQs

Security

ByteRover Cookbook

Getting Started

Prerequisites

Initialize Version Control

What `vc init` Does

Configure Author Identity

Supported Configuration Keys

Reading vs Setting

Error Handling

Clone a Remote Space

Clone URL Format

What `vc clone` Does

Error Handling

Typical First-Time Setup

Local Only (no account needed)

What’s Next

Staging & Committing

Remote Sync

​Prerequisites

​Initialize Version Control

​What vc init Does

​Configure Author Identity

​Supported Configuration Keys

​Reading vs Setting

​Error Handling

​Clone a Remote Space

​Clone URL Format

​What vc clone Does

​Error Handling

​Typical First-Time Setup

​Local Only (no account needed)

​Local to Cloud (requires login + remote space)

​Clone an Existing Space (requires login)

​What’s Next

Staging & Committing

Remote Sync

Prerequisites

Initialize Version Control

What `vc init` Does

Configure Author Identity

Supported Configuration Keys

Reading vs Setting

Error Handling

Clone a Remote Space

Clone URL Format

What `vc clone` Does

Error Handling

Typical First-Time Setup

Local Only (no account needed)

Local to Cloud (requires login + remote space)

Clone an Existing Space (requires login)

What’s Next