Getting Started

Initialize version control, configure your identity, and clone remote spaces

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.

NOTE

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.

CLI

brv vc init

TUI

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

TIP

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.

Step 1: Set your name

CLI

brv vc config user.name "Alice Chen"

TUI

/vc config user.name "Alice Chen"

Step 2: Set your email

CLI

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

TUI

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

Step 3: Verify your configuration

Read back the values to confirm they were set correctly:

CLI

brv vc config user.name
# Output: Alice Chen

brv vc config user.email
# Output: alice@example.com

TUI

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

WARNING

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.

CLI

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

TUI

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

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

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

NOTE

Clone operations have a 120-second timeout. For spaces with very large context trees, ensure a stable network connection.

TIP

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:

CLI

# 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

TUI

/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

Local to Cloud (requires login + remote space)

Start locally, then push to ByteRover cloud when you're ready to collaborate:

CLI

# 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

TUI

/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

Clone an Existing Space (requires login)

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

CLI

# 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

TUI

/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