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

# 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](/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](https://app.byterover.dev/) and a remote space. See [Remote Sync](/git-semantic/remote-sync) for details.
</Note>

## Initialize Version Control

Set up Git-Semantic version control for your context tree. This is required before you can use any other `vc` commands.

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

  <Tab title="TUI">
    ```
    /vc init
    ```
  </Tab>
</Tabs>

### 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`.
</Tip>

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.

<Steps>
  <Step title="Set your name">
    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        brv vc config user.name "Alice Chen"
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /vc config user.name "Alice Chen"
        ```
      </Tab>
    </Tabs>
  </Step>

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

      <Tab title="TUI">
        ```
        /vc config user.email "alice@example.com"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify your configuration">
    Read back the values to confirm they were set correctly:

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        brv vc config user.name
        # Output: Alice Chen

        brv vc config user.email
        # Output: alice@example.com
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /vc config user.name
        /vc config user.email
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

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

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

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

  <Tab title="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
    ```
  </Tab>
</Tabs>

### 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](https://app.byterover.dev).

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

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

## Typical First-Time Setup

### Local Only (no account needed)

Use Git-Semantic purely on your machine — no login, no cloud, no remote space:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="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
    ```
  </Tab>
</Tabs>

### Local to Cloud (requires login + remote space)

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

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="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
    ```
  </Tab>
</Tabs>

### Clone an Existing Space (requires login)

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

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="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
    ```
  </Tab>
</Tabs>

## What's Next

Now that version control is set up, learn how to track changes:

<CardGroup cols={2}>
  <Card title="Staging & Committing" icon="check" href="/git-semantic/staging-and-committing">
    Stage changes, create commits, and view history
  </Card>

  <Card title="Remote Sync" icon="cloud" href="/git-semantic/remote-sync">
    Push and pull context to ByteRover cloud
  </Card>
</CardGroup>