Remote Sync - Byterover

Prefer a visual workflow? See Changes in the web UI.

Understanding Remotes

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.

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:

brv vc remote

/vc remote

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.

brv vc remote add origin https://byterover.dev/acme/project.git

/vc remote add origin https://byterover.dev/acme/project.git

Only origin is supported as a remote name. Attempting to add a remote with a different name will fail.

Update Remote URL

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

brv vc remote set-url origin https://byterover.dev/acme/new-project.git

/vc remote set-url origin https://byterover.dev/acme/new-project.git

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.

brv vc remote remove origin

/vc remote remove origin

You can also remove the remote from the web UI Configuration page — 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.

# 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

/vc fetch
/vc fetch origin
/vc fetch origin main

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

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

Pull

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

# 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

/vc pull
/vc pull origin main
/vc pull --allow-unrelated-histories origin main

How Pull Works

Fetches the latest refs from the remote
Merges the remote branch into your current local branch
If conflicts occur, the merge pauses — resolve them using the conflict resolution workflow

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

Pull operations have a 120-second timeout. For large spaces, ensure a stable network connection.

Push

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

# 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

/vc push
/vc push -u origin main
/vc push origin feature/auth

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`

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.

First Push

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

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:

# 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

Push operations have a 120-second timeout. For large commits, ensure a stable network connection.

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.

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.

brv vc clone https://byterover.dev/acme/project.git

The CLI streams real-time progress during the download.

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

What Clone Does

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

After cloning, you still need to configure your 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:

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

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

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

# 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

​Understanding Remotes

​Remote URL Format

​Manage Remotes

​View Current Remote

​Add a Remote

​Update Remote URL

​Remove a Remote

​Error Handling

​Fetch

​When to Use Fetch

​Arguments

​Error Handling

​Pull

​How Pull Works

​Pull Outcomes

​Arguments & Flags

​Error Handling

​Push

​Push Semantics

​First Push

​Non-Fast-Forward Rejection

​Arguments & Flags

​Error Handling

​Clone

​What Clone Does

​Error Handling

​Collaboration Workflows

​Daily Team Sync

​Feature Branch Collaboration

​Resolving Push Conflicts

​Checking Remote State Without Merging

Understanding Remotes

Remote URL Format

Manage Remotes

View Current Remote

Add a Remote

Update Remote URL

Remove a Remote

Error Handling

Fetch

When to Use Fetch

Arguments

Error Handling

Pull

How Pull Works

Pull Outcomes

Arguments & Flags

Error Handling

Push

Push Semantics

First Push

Non-Fast-Forward Rejection

Arguments & Flags

Error Handling

Clone

What Clone Does

Error Handling

Collaboration Workflows

Daily Team Sync

Feature Branch Collaboration

Resolving Push Conflicts

Checking Remote State Without Merging