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.
origin, which points to your space on ByteRover cloud. All sync operations (fetch, pull, push) communicate with this remote.
https://byterover.dev/<team>/<space>.git
| Segment | Description | Example |
|---|
<team> | Your team or organization name | acme |
<space> | The space name | project |
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:
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
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
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
Provide the URL directly:/vc clone https://byterover.dev/acme/project.git
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
