When to use a branch
Major refactor
“Convert the auth flow to a new architecture.” Branch first; merge if it works.
Experiment
“Try a different layout” or “try Anthropic instead of OpenAI for the chatbot.” Branch and play.
Multi-developer parallel work
Two team members working on different features at the same time. Each on their own branch; merge when done.
Release candidate
Cut a
release-v2 branch, freeze it for QA, keep building on main.Creating a branch
1
From the current state
Sidebar → Branches → New branch. Name it (
feature/billing, experiment/new-design).2
From a specific revision
History → click a revision → “Branch from here”. The branch starts at that point.
3
Switch to the branch
Branch dropdown in the header. The editor and preview both update to the branch’s state.
Working on a branch
Everything is the same as on main: prompts, hand-edits, plan mode, deploys to a per-branch preview URL (e.g.,feature-billing.your-app.vly.app).
Convex schema changes on a branch are isolated from main — branches have their own database snapshot. When you merge, vly handles the schema reconciliation.
Merging back to main
1
Branches → [your branch] → Merge to main
Or open a pull request if you want a review step.
2
Resolve conflicts (if any)
Two-way conflicts (both branches edited the same file) open a side-by-side diff. Pick the winning side per file.
3
Schema reconciliation
If both branches changed the schema, vly walks you through the merge: rename collisions, type conflicts, etc.
4
Confirm
The merge appears as a single revision on main, attributed to the branch.
Discarding a branch
If the experiment didn’t work out:- Branches → [branch] → Delete. The branch and its preview URL are removed.
- Revisions made on the branch stay in version history (under the branch’s namespace) for the standard retention window.
GitHub sync
If GitHub is connected, vly branches map 1:1 to GitHub branches:- Creating a branch in vly creates one in GitHub (and vice versa).
- Pushing to a branch in either place propagates.
- Opening a pull request in vly opens one in GitHub.
- Merging happens in either place.
Limits
| Plan | Concurrent branches |
|---|---|
| Free | 1 |
| Pro | 10 |
| Business | 50 |
| Enterprise | Unlimited |
Related
Version history
The single-timeline view of revisions.
GitHub integration
Branch parity with GitHub.
Real-time collaboration
Multiple people on the same branch.