What is Git-Semantic Version Control?
Git-Semantic version control lets you track every change to your context tree — the knowledge base that your AI agents rely on. Save snapshots of your context, undo mistakes, experiment on branches, and optionally share with your team via the cloud. If you’ve used Git before, you’ll feel right at home — the commands map directly. If you haven’t, don’t worry: the workflow is simple and the guides walk you through each step.No account required for local use. Git-Semantic works entirely on your machine — no login, no cloud account, no remote space needed. Initialize with
brv vc init, then save, branch, and merge freely. Cloud sync (push, pull, fetch, clone) is optional and requires a ByteRover account and a remote space.How It Works
Git-Semantic operates on your.brv/context-tree/ directory — the hierarchical knowledge base that stores your project’s domains, topics, and subtopics. It tracks changes using a model similar to Git:
- Working tree — The current state of your context tree files on disk
- Staging area — A holding area where you prepare changes before saving them
- Commit history — A chain of saved snapshots, each recording what changed, when, and by whom
- Branches — Independent lines of work, so you can experiment without affecting the main context
- Remote — ByteRover cloud, for syncing context across machines and team members (optional)
Git vs Git-Semantic
If you know Git, the commands map directly. If you’re new to version control, the Getting Started guide walks you through each one.| Git | Git-Semantic (CLI) | Git-Semantic (TUI) |
|---|---|---|
git init | brv vc init | /vc init |
git config | brv vc config | /vc config |
git clone <url> | brv vc clone <url> | /vc clone <url> |
git add . | brv vc add . | /vc add . |
git commit -m "msg" | brv vc commit -m "msg" | /vc commit -m "msg" |
git status | brv vc status | /vc status |
git log | brv vc log | /vc log |
git reset | brv vc reset | /vc reset |
git branch | brv vc branch | /vc branch |
git checkout | brv vc checkout | /vc checkout |
git merge | brv vc merge | /vc merge |
git remote | brv vc remote | /vc remote |
git fetch | brv vc fetch | /vc fetch |
git pull | brv vc pull | /vc pull |
git push | brv vc push | /vc push |
Why Version Control for Context?
Your context tree evolves alongside your codebase. Without version control, changes are invisible and irreversible. With it, you get:- Full history — See what changed, when, and by whom. Every save (called a “commit”) records the author, timestamp, and a descriptive message.
- Safe experimentation — Create a branch to try a different context structure. If it doesn’t work, switch back — your main context is untouched.
- Team collaboration — Multiple people can curate context in parallel, then merge their work together. ByteRover detects conflicts when the same file is edited by two people.
- Undo mistakes — Made a change that degraded your agent’s context quality? Roll back to a previous commit to restore what worked.
- Cloud sync — Optionally push context to ByteRover cloud and pull it on another machine, keeping your team aligned on a single source of truth.
CLI vs TUI
All 15 version control commands are available in two modes:- CLI
- TUI (REPL)
Run commands directly from your terminal. Best for scripting, automation, CI/CD pipelines, and headless environments.CLI commands follow the pattern:
brv vc <subcommand> [args] [flags]| Feature | CLI | TUI |
|---|---|---|
| Execution | Single command, returns output | Interactive guided flow |
| Clone without URL | Requires URL argument | Opens interactive space picker |
| Error display | Printed to terminal | Inline error messages in flow |
| Best for | Automation, scripting, CI/CD | Interactive daily use |
Available Commands
Commands are organized into four groups. The first three groups work entirely locally — no account, no internet, no remote space required. Only the Remote Sync group requires a ByteRover account and a remote space.Setup
| Command | Description | Requires login? |
|---|---|---|
vc init | Initialize version control for a space | No |
vc config | Get or set commit author identity (per-space) | No |
Staging & History
| Command | Description | Requires login? |
|---|---|---|
vc add | Stage files or directories for the next commit | No |
vc commit | Save staged changes as a commit with a message | No |
vc status | Show working tree status — staged, unstaged, untracked files | No |
vc log | Show commit history with SHA, author, and timestamps | No |
vc reset | Unstage files, or undo commits with --soft/--hard | No |
Branching & Merging
| Command | Description | Requires login? |
|---|---|---|
vc branch | List, create, delete branches, or set upstream tracking | No |
vc checkout | Switch to a branch, or create and switch with -b | No |
vc merge | Merge a branch, continue after conflicts, or abort | No |
Remote Sync (requires login + remote space)
| Command | Description | Requires login? |
|---|---|---|
vc clone | Clone a remote space from ByteRover cloud | Yes |
vc remote | Show, add, or update the remote connection (origin) | No * |
vc fetch | Download refs from ByteRover cloud without merging | Yes |
vc pull | Fetch and merge remote changes (fetch + merge) | Yes |
vc push | Upload local commits to ByteRover cloud | Yes |
* vc remote itself doesn’t require authentication — it only configures the remote URL locally. Authentication is checked when you actually communicate with the remote (push, pull, fetch, clone).Next Steps
Getting Started
Initialize version control, configure your identity, and clone your first space
Staging & Committing
Stage changes, create commits, view history, and undo mistakes
Branching & Merging
Work in parallel with branches and resolve merge conflicts
Remote Sync
Push, pull, and sync context with ByteRover cloud