> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/git-semantic/getting-started) guide instead.
</Note>

## Prerequisites

Before starting, make sure you have:

1. **Logged in** to the ByteRover CLI:

   <Tabs>
     <Tab title="CLI">
       ```bash theme={null}
       brv login -k <your-api-key>
       ```
     </Tab>

     <Tab title="TUI">
       ```
       /login
       ```
     </Tab>
   </Tabs>

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](/git-semantic/getting-started) guide first.

## Automated Migration Script

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

<Tabs>
  <Tab title="Linux / macOS">
    ```bash theme={null}
    curl -fsSL https://byterover.dev/vc-migration.sh | bash
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    irm https://storage.googleapis.com/brv-releases/vc_migrations/vc-migration-script.ps1 | iex
    ```
  </Tab>
</Tabs>

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.

<Steps>
  <Step title="Check for unpushed changes">
    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        brv status
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /status
        ```
      </Tab>
    </Tabs>

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

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        brv push
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /push
        ```
      </Tab>
    </Tabs>

    Optionally, back up your context tree:

    ```bash theme={null}
    cp -r .brv/context-tree .brv/context-tree-backup
    ```
  </Step>

  <Step title="Clone your space with Git-Semantic">
    Copy the clone URL from your space on [app.byterover.dev](https://app.byterover.dev), then run:

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        brv vc clone https://byterover.dev/<team>/<space>.git
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /vc clone https://byterover.dev/<team>/<space>.git
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set your identity">
    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        brv vc config user.name "Your Name"
        brv vc config user.email "your@email.com"
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /vc config user.name "Your Name"
        /vc config user.email "your@email.com"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify">
    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        brv vc status
        brv vc log
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /vc status
        /vc log
        ```
      </Tab>
    </Tabs>

    You should see a clean working tree and your commit history.
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="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 theme={null}
    brv vc add .
    brv vc commit -m "update context"
    brv vc push
    ```
  </Accordion>

  <Accordion title="ALREADY_INITIALIZED error on clone">
    Your context tree already has a git repo. Remove it and re-clone:

    ```bash theme={null}
    rm -rf .brv/context-tree
    brv vc clone https://byterover.dev/<team>/<space>.git
    ```
  </Accordion>

  <Accordion title="Authentication failed / 403 error">
    Make sure you're logged in:

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        brv login -k <your-api-key>
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /login
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>