> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Branching

> Create a branch to experiment without affecting the main project. Merge or discard. Sync with GitHub if connected.

Branches in vly work like branches in Git: they're independent timelines of your project that can be merged back later (or discarded). Use them when you want to try something risky without affecting the working app.

## When to use a branch

<CardGroup cols={2}>
  <Card title="Major refactor" icon="git-pull-request">
    "Convert the auth flow to a new architecture." Branch first; merge if it works.
  </Card>

  <Card title="Experiment" icon="flask-conical">
    "Try a different layout" or "try Anthropic instead of OpenAI for the chatbot." Branch and play.
  </Card>

  <Card title="Multi-developer parallel work" icon="users">
    Two team members working on different features at the same time. Each on their own branch; merge when done.
  </Card>

  <Card title="Release candidate" icon="package">
    Cut a `release-v2` branch, freeze it for QA, keep building on main.
  </Card>
</CardGroup>

## Creating a branch

<Steps>
  <Step title="From the current state">
    Sidebar → Branches → New branch. Name it (`feature/billing`, `experiment/new-design`).
  </Step>

  <Step title="From a specific revision">
    History → click a revision → "Branch from here". The branch starts at that point.
  </Step>

  <Step title="Switch to the branch">
    Branch dropdown in the header. The editor and preview both update to the branch's state.
  </Step>
</Steps>

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

<Steps>
  <Step title="Branches → [your branch] → Merge to main">
    Or open a pull request if you want a review step.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Schema reconciliation">
    If both branches changed the schema, vly walks you through the merge: rename collisions, type conflicts, etc.
  </Step>

  <Step title="Confirm">
    The merge appears as a single revision on main, attributed to the branch.
  </Step>
</Steps>

## 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](/building/version-history) (under the branch's namespace) for the standard retention window.

## GitHub sync

If [GitHub is connected](/integrations/github), 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

<table className="vly-compare">
  <thead>
    <tr><th>Plan</th><th>Concurrent branches</th></tr>
  </thead>

  <tbody>
    <tr><td>Free</td><td>1</td></tr>
    <tr><td>Pro</td><td>10</td></tr>
    <tr><td>Business</td><td>50</td></tr>
    <tr><td>Enterprise</td><td>Unlimited</td></tr>
  </tbody>
</table>

## Related

<CardGroup cols={3}>
  <Card title="Version history" icon="history" href="/building/version-history">
    The single-timeline view of revisions.
  </Card>

  <Card title="GitHub integration" icon="github" href="/integrations/github">
    Branch parity with GitHub.
  </Card>

  <Card title="Real-time collaboration" icon="users-round" href="/building/real-time-collaboration">
    Multiple people on the same branch.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.