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

# Remote Sync

> Connect to ByteRover cloud, push and pull context, and collaborate with your team

<Tip>
  Prefer a visual workflow? See [Changes in the web UI](/local-web-ui/changes).
</Tip>

## Understanding Remotes

<Info>
  **Remote sync is optional.** All local Git-Semantic commands (init, add, commit, branch, merge, reset, log, status) work without a ByteRover account. You only need to log in and have a remote space when you want to push, pull, fetch, or clone.
</Info>

A remote is a connection to a ByteRover cloud space. It allows you to synchronize your local context tree with the cloud, enabling team collaboration and backup.

Git-Semantic supports a single remote named `origin`, which points to your space on ByteRover cloud. All sync operations (fetch, pull, push) communicate with this remote.

### Remote URL Format

```
https://byterover.dev/<team>/<space>.git
```

| Segment   | Description                    | Example   |
| --------- | ------------------------------ | --------- |
| `<team>`  | Your team or organization name | `acme`    |
| `<space>` | The space name                 | `project` |

Team and space names in URLs are matched case-insensitively — `Acme/Project.git` and `acme/project.git` resolve to the same space.

## Manage Remotes

### View Current Remote

Check which remote is configured for your space:

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

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

Returns the configured remote URL (e.g., `https://byterover.dev/acme/project.git`), or "No remote configured" if none is set.

### Add a Remote

Connect your local space to a remote space on ByteRover cloud. This is required before you can push, pull, or fetch.

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

  <Tab title="TUI">
    ```
    /vc remote add origin https://byterover.dev/acme/project.git
    ```
  </Tab>
</Tabs>

<Note>
  Only `origin` is supported as a remote name. Attempting to add a remote with a different name will fail.
</Note>

### Update Remote URL

Change the URL of an existing remote. Use this when your space has been moved or renamed.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc remote set-url origin https://byterover.dev/acme/new-project.git
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc remote set-url origin https://byterover.dev/acme/new-project.git
    ```
  </Tab>
</Tabs>

### Remove a Remote

Disconnect your local space from ByteRover cloud. After removal, `vc push`, `vc pull`, and `vc fetch` will fail with `NO_REMOTE` until you add the remote back.

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

  <Tab title="TUI">
    ```
    /vc remote remove origin
    ```
  </Tab>
</Tabs>

You can also remove the remote from the [web UI Configuration page](/local-web-ui/configuration#origin-remote) — the Remotes panel shows a Delete button with a confirmation step.

### Error Handling

| Error                   | Cause                                         | Solution                                                  |
| ----------------------- | --------------------------------------------- | --------------------------------------------------------- |
| `REMOTE_ALREADY_EXISTS` | A remote named `origin` is already configured | Use `vc remote set-url` to update it instead              |
| `INVALID_REMOTE_URL`    | URL doesn't match the expected format         | Use the format `https://byterover.dev/<team>/<space>.git` |
| `NO_REMOTE`             | No remote configured                          | Add one with `vc remote add origin <url>`                 |

## Fetch

Download the latest changes from ByteRover cloud **without modifying your local context tree or current branch**. Fetch lets you see what others have pushed before you decide to merge those changes into your work.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Fetch all branches from origin
    brv vc fetch

    # Explicitly specify the remote
    brv vc fetch origin

    # Fetch only a specific branch
    brv vc fetch origin main
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc fetch
    /vc fetch origin
    /vc fetch origin main
    ```
  </Tab>
</Tabs>

### When to Use Fetch

Use `fetch` when you want to:

* See what others have pushed without affecting your local work
* Update remote-tracking branches before comparing (`vc log --all`)
* Check for new remote branches (`vc branch -a` after fetching)

Fetch is always safe — it never modifies your local branches or working tree.

### Arguments

| Argument | Required | Description                                                 |
| -------- | -------- | ----------------------------------------------------------- |
| `remote` | No       | Remote name (only `origin` supported). Defaults to `origin` |
| `branch` | No       | Specific branch to fetch. Defaults to all branches          |

### Error Handling

| Error          | Cause                                         | Solution                                       |
| -------------- | --------------------------------------------- | ---------------------------------------------- |
| `FETCH_FAILED` | Network error or server issue                 | Check your internet connection and try again   |
| `NO_REMOTE`    | No remote configured                          | Add a remote with `vc remote add`              |
| `AUTH_FAILED`  | Not authenticated or insufficient permissions | Log in with `brv login` and verify team access |

<Note>
  Fetch operations have a **120-second timeout**. If the operation times out, check your network connection and try again.
</Note>

## Pull

Fetch remote changes and merge them into your current branch. This is equivalent to running `vc fetch` followed by `vc merge`.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Pull from the upstream of your current branch
    brv vc pull

    # Pull from a specific remote and branch
    brv vc pull origin main

    # Pull with unrelated histories (for initial sync of disconnected spaces)
    brv vc pull --allow-unrelated-histories origin main
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc pull
    /vc pull origin main
    /vc pull --allow-unrelated-histories origin main
    ```
  </Tab>
</Tabs>

### How Pull Works

1. **Fetches** the latest refs from the remote
2. **Merges** the remote branch into your current local branch
3. If conflicts occur, the merge pauses — resolve them using the [conflict resolution workflow](/git-semantic/branching-and-merging#resolve-merge-conflicts)

### Pull Outcomes

| Outcome                | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------ |
| **Already up to date** | Your local branch has all the remote commits                             |
| **Clean merge**        | Remote changes merged without conflicts                                  |
| **Merge conflict**     | Both local and remote modified the same files — manual resolution needed |

### Arguments & Flags

| Argument | Required | Description                                                     |
| -------- | -------- | --------------------------------------------------------------- |
| `remote` | No       | Remote name (only `origin` supported). Defaults to `origin`     |
| `branch` | No       | Branch to pull. Defaults to the upstream of your current branch |

| Flag                          | Default | Description                                    |
| ----------------------------- | ------- | ---------------------------------------------- |
| `--allow-unrelated-histories` | `false` | Allow merging branches with no common ancestor |

### Error Handling

| Error            | Cause                                         | Solution                                                    |
| ---------------- | --------------------------------------------- | ----------------------------------------------------------- |
| `PULL_FAILED`    | Network error or server issue                 | Check your internet connection and try again                |
| `NO_REMOTE`      | No remote configured                          | Add a remote with `vc remote add`                           |
| `NO_UPSTREAM`    | Current branch has no upstream tracking       | Specify remote and branch explicitly: `vc pull origin main` |
| `MERGE_CONFLICT` | Conflicting changes between local and remote  | Resolve conflicts and run `vc merge --continue`             |
| `AUTH_FAILED`    | Not authenticated or insufficient permissions | Log in with `brv login` and verify team access              |

<Note>
  Pull operations have a **120-second timeout**. For large spaces, ensure a stable network connection.
</Note>

## Push

Upload your local commits to ByteRover cloud. This makes your changes available to other team members.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Push current branch to its upstream
    brv vc push

    # Push and set upstream tracking in one step
    brv vc push -u origin main

    # Push a specific branch to origin
    brv vc push origin feature/auth
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc push
    /vc push -u origin main
    /vc push origin feature/auth
    ```
  </Tab>
</Tabs>

### Push Semantics

The behavior depends on which arguments you provide:

| Command                      | Behavior                                           |
| ---------------------------- | -------------------------------------------------- |
| `brv vc push`                | Push the current branch to its configured upstream |
| `brv vc push -u origin main` | Push the main branch and set it as the upstream    |
| `brv vc push origin`         | Push the current branch to `origin`                |
| `brv vc push origin feat/x`  | Push the `feat/x` branch to `origin`               |

<Warning>
  `brv vc push feat/x` (without `origin`) will fail — the first positional argument is always interpreted as the remote name. Always specify `origin` before the branch name.
</Warning>

### First Push

When pushing a branch for the first time, use `-u` to set up upstream tracking:

```bash theme={null}
brv vc push -u origin main
```

This configures the remote branch as the upstream for your local branch, so future `vc push` and `vc pull` commands work without specifying the remote and branch.

### Non-Fast-Forward Rejection

If the remote has commits that you don't have locally (e.g., a teammate pushed changes), your push will be rejected with a `NON_FAST_FORWARD` error. To resolve:

```bash theme={null}
# 1. Pull the remote changes first
brv vc pull

# 2. Resolve any merge conflicts if needed
brv vc status
# ... fix conflicts ...
brv vc add .
brv vc merge --continue -m "resolve conflicts"

# 3. Push again
brv vc push
```

### Arguments & Flags

| Argument | Required | Description                                                 |
| -------- | -------- | ----------------------------------------------------------- |
| `remote` | No       | Remote name (only `origin` supported). Defaults to `origin` |
| `branch` | No       | Branch to push. Defaults to the current branch              |

| Flag                   | Default | Description                                           |
| ---------------------- | ------- | ----------------------------------------------------- |
| `-u`, `--set-upstream` | `false` | Set the remote branch as the upstream tracking branch |

### Error Handling

| Error              | Cause                                          | Solution                                                |
| ------------------ | ---------------------------------------------- | ------------------------------------------------------- |
| `PUSH_FAILED`      | Network error or server issue                  | Check your internet connection and try again            |
| `NON_FAST_FORWARD` | Remote has commits you don't have locally      | Pull first, resolve any conflicts, then push again      |
| `NOTHING_TO_PUSH`  | No new commits to push                         | Your local branch is already up to date with the remote |
| `NO_REMOTE`        | No remote configured                           | Add a remote with `vc remote add`                       |
| `NO_UPSTREAM`      | No upstream set and no remote/branch specified | Use `vc push -u origin <branch>`                        |
| `AUTH_FAILED`      | Not authenticated or insufficient permissions  | Log in with `brv login` and verify team access          |

<Note>
  Push operations have a **120-second timeout**. For large commits, ensure a stable network connection.
</Note>

<Tip>
  **TUI users:** If push, pull, or fetch encounters a `NO_REMOTE` error, the TUI shows an interactive prompt where you can enter your space URL directly. The command retries automatically after the remote is added — no need to run `vc remote add` separately.
</Tip>

## Clone

Clone a remote space from ByteRover cloud to your local machine. This is the fastest way to start working with an existing team space.

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

    The CLI streams real-time progress during the download.
  </Tab>

  <Tab title="TUI">
    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>

### What Clone Does

1. **Authenticates** with ByteRover cloud using your credentials
2. **Downloads** the full commit history and all branches
3. **Creates** the `.brv/` directory with the complete context tree
4. **Checks out** the default branch (usually `main`)
5. **Configures** `origin` remote pointing to the cloud space

After cloning, you still need to [configure your author identity](/git-semantic/getting-started#configure-author-identity) before you can commit.

### Error Handling

| Error                | Cause                                          | Solution                                           |
| -------------------- | ---------------------------------------------- | -------------------------------------------------- |
| `CLONE_FAILED`       | Network error, invalid URL, or space not found | Verify the URL and your internet connection        |
| `AUTH_FAILED`        | Not authenticated or no access to the space    | Log in with `brv login` and verify team membership |
| `INVALID_REMOTE_URL` | URL doesn't match the expected format          | Use `https://byterover.dev/<team>/<space>.git`     |

## Collaboration Workflows

### Daily Team Sync

The most common pattern — pull before you start, push when you're done:

```bash theme={null}
# Start of your session: pull the latest
brv vc pull

# Do your work...
brv vc add .
brv vc commit -m "update deployment context after infra changes"

# End of your session: push to cloud
brv vc push
```

### Feature Branch Collaboration

Work on a feature branch and push it for team review:

```bash theme={null}
# Pull latest main
brv vc checkout main
brv vc pull

# Create and work on a feature branch
brv vc checkout -b feature/database-patterns

brv vc add .
brv vc commit -m "add connection pooling best practices"

brv vc add .
brv vc commit -m "add migration strategy documentation"

# Push the feature branch to cloud
brv vc push -u origin feature/database-patterns

# After review, merge into main
brv vc checkout main
brv vc pull
brv vc merge feature/database-patterns
brv vc push

# Clean up
brv vc branch -d feature/database-patterns
```

### Resolving Push Conflicts

When your push is rejected because a teammate pushed first:

```bash theme={null}
# Push fails with NON_FAST_FORWARD
brv vc push
# Error: NON_FAST_FORWARD

# Pull their changes
brv vc pull

# If there are conflicts, resolve them
brv vc status
# ... edit files to resolve ...
brv vc add .
brv vc merge --continue -m "merge remote changes"

# Now push succeeds
brv vc push
```

### Checking Remote State Without Merging

Use fetch to see what's changed on the remote before deciding to merge:

```bash theme={null}
# Download remote state without merging
brv vc fetch

# See all branches including remote-tracking
brv vc branch -a

# See remote commits
brv vc log origin/main --limit 5

# Check how your branch compares
brv vc status
# Output shows: "Your branch is behind 'origin/main' by 3 commits"

# When ready, pull the changes
brv vc pull
```