Migration Guide

Migrate from the old snapshot-based system to Git-Semantic version control

NOTE

This guide is for existing users who have context trees created before Git-Semantic was introduced. New users should start with the Getting Started guide instead.

Prerequisites

Before starting, make sure you have:

1. Logged in to the ByteRover CLI:

CLI

brv login -k <your-api-key>

TUI

/login

2. Configured a team and space — your current team/space is read from brv status. If you haven't set one up yet, follow the Getting Started guide first.

Automated Migration Script

An interactive script that handles backup, push, and clone in one go.

Linux / macOS

curl -fsSL https://byterover.dev/vc-migration.sh | bash

Windows (PowerShell)

irm https://storage.googleapis.com/brv-releases/vc_migrations/vc-migration-script.ps1 | iex

The script will:

1. Backup your context tree to .brv/context-tree-backup
2. Push any unpushed changes to the cloud
3. Clone your space with Git-Semantic version control

If anything fails, the script automatically rolls back to your backup.

---

Manual Migration

If you prefer to migrate manually, follow the steps below.

Step 1: Check for unpushed changes

CLI

brv status

TUI

/status

If you see unpushed changes, push them first using the old commands:

CLI

brv push

TUI

/push

Optionally, back up your context tree:

cp -r .brv/context-tree .brv/context-tree-backup

Step 2: Clone your space with Git-Semantic

Copy the clone URL from your space on app.byterover.dev, then run:

CLI

brv vc clone https://byterover.dev/<team>/<space>.git

TUI

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

Step 3: Set your identity

CLI

brv vc config user.name "Your Name"
brv vc config user.email "your@email.com"

TUI

/vc config user.name "Your Name"
/vc config user.email "your@email.com"

Step 4: Verify

CLI

brv vc status
brv vc log

TUI

/vc status
/vc log

You should see a clean working tree and your commit history.

That's it — you're on Git-Semantic version control now.

What Changes

Old snapshot commands are replaced by vc commands:

Old command	New command
/push or brv push	/vc push or brv vc push
/pull or brv pull	/vc pull or brv vc pull
/status or brv status	/vc status or brv vc status
/reset or brv reset	/vc reset or brv vc reset

Once version control is initialized (.brv/context-tree/.git exists), the legacy brv push and brv pull commands are blocked and will throw a VC_GIT_INITIALIZED error. This only affects the migrated project — other projects without Git-Semantic still use the old commands normally.

Troubleshooting

VC_GIT_INITIALIZED error on brv push / brv pull

Cause: You ran legacy brv push or brv pull on a project that has Git-Semantic version control initialized.

**Solution:** Use the new `brv vc push` and `brv vc pull` commands instead:

```bash
brv vc add .
brv vc commit -m "update context"
brv vc push
```

ALREADY_INITIALIZED error on clone

Your context tree already has a git repo. Remove it and re-clone:

```bash
rm -rf .brv/context-tree
brv vc clone https://byterover.dev/<team>/<space>.git
```

Authentication failed / 403 error

Make sure you're logged in:

CLI

brv login -k <your-api-key>

TUI

/login