Description
Promote an experiment to a permanent Git branch. This command creates a Git branch from an experiment, making it part of your regular Git history. This is useful when you want to preserve a successful experiment as a permanent branch for collaboration, code review, or deployment.
Use this command to convert temporary experiments into permanent branches that can be pushed to remote repositories and shared with your team.
Usage
dvc exp branch <experiment> [branch]
Arguments
The experiment name to promote to a branch.Can be:
- Auto-generated experiment name (e.g.,
exp-a1b2c)
- Custom experiment name (specified with
-n during dvc exp run)
dvc exp branch exp-44136
dvc exp branch high-accuracy-run
Name for the new Git branch. If not specified, defaults to {experiment-name}-branch.dvc exp branch exp-a1b2c feature/new-model
dvc exp branch my-experiment # Creates 'my-experiment-branch'
Examples
Create branch with auto-generated name
Output:
Git branch 'exp-a1b2c-branch' has been created from experiment 'exp-a1b2c'.
The default branch name is the experiment name with -branch appended.
Create branch with custom name
dvc exp branch high-accuracy-run feature/improved-model
Git branch 'feature/improved-model' has been created from experiment 'high-accuracy-run'.
Use descriptive branch names following your team’s Git conventions (e.g., feature/, experiment/, model/).
Push branch to remote
# Create branch from experiment
dvc exp branch exp-d3e4f experiment/lr-optimization
# Push to remote for collaboration
git push -u origin experiment/lr-optimization
Git branch 'experiment/lr-optimization' has been created from experiment 'exp-d3e4f'.
To https://github.com/user/repo.git
* [new branch] experiment/lr-optimization -> experiment/lr-optimization
Branch 'experiment/lr-optimization' set up to track remote branch 'experiment/lr-optimization' from 'origin'.
Create branch and switch to it
# Create branch
dvc exp branch best-model model/production-v2
# Switch to the new branch
git checkout model/production-v2
# View the experiment's state
dvc exp show
Git branch 'model/production-v2' has been created from experiment 'best-model'.
Switched to branch 'model/production-v2'
The new branch contains the full experiment state including code, parameters, and DVC pipeline information.
# View all experiments
dvc exp show --sort-by accuracy --sort-order desc
# Promote the top performer
dvc exp branch exp-top1 releases/model-v3.0
# Push for deployment
git push origin releases/model-v3.0
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Experiment ┃ accuracy ┃ loss ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ ├── exp-top1 │ 0.95 │ 0.178 │
│ ├── exp-abc123 │ 0.92 │ 0.234 │
│ └── exp-def456 │ 0.89 │ 0.287 │
└───────────────────┴──────────┴─────────────┘
Git branch 'releases/model-v3.0' has been created from experiment 'exp-top1'.
Common Workflows
Collaboration Workflow
# 1. Run experiments locally
dvc exp run -S train.lr=0.001 -n "lr-experiment"
# 2. Promote to branch for code review
dvc exp branch lr-experiment feature/lr-tuning
# 3. Push for team review
git push -u origin feature/lr-tuning
# 4. Team can now checkout and test
# (On teammate's machine)
git fetch
git checkout feature/lr-tuning
dvc pull
Production Release Workflow
# 1. Find best experiment
dvc exp show --sort-by metrics.json:accuracy --sort-order desc
# 2. Create release branch
dvc exp branch production-candidate releases/v2.0
# 3. Switch to release branch
git checkout releases/v2.0
# 4. Run final validation
python scripts/validate_model.py
# 5. Tag and deploy
git tag -a v2.0.0 -m "Production release v2.0.0 - 95% accuracy"
git push origin releases/v2.0 --tags
# Development
dvc exp run -n "dev-test"
dvc exp branch dev-test experiment/dev-test
git push origin experiment/dev-test
# After review, promote to staging
git checkout -b staging/new-model experiment/dev-test
git push origin staging/new-model
# After validation, merge to production
git checkout main
git merge staging/new-model
git push origin main
Feature Branch Workflow
# 1. Create feature branch from experiment
dvc exp branch exp-feature feature/add-transformer
# 2. Switch to the branch
git checkout feature/add-transformer
# 3. Continue development
vim model.py
dvc exp run
# 4. Create pull request
gh pr create --title "Add transformer model" --body "Accuracy improved to 95%"
Understanding Branch Creation
When you create a branch from an experiment:
What Gets Included
-
Git Commit: A proper Git commit is created containing:
- Code changes from the experiment
- Parameter files (
params.yaml)
- DVC pipeline files (
dvc.yaml, dvc.lock)
- Metrics files
-
Commit Message: Auto-generated message includes:
- Experiment name
- Timestamp
- Changed metrics and parameters
-
DVC Cache: References to cached model outputs and data
The branch is a full Git branch, indistinguishable from branches created manually. It can be merged, rebased, and pushed like any other branch.
Branch vs Apply
Choose between dvc exp branch and dvc exp apply:
| Operation | dvc exp branch | dvc exp apply |
|---|
| Creates | New Git branch | No new branch |
| Workspace | Unchanged | Updated |
| Use case | Preserve/share | Continue working |
| Permanent | Yes | No (until commit) |
| Remote | Can push | Cannot push |
# Use branch for collaboration
dvc exp branch exp-abc feature/new-model
git push origin feature/new-model
# Use apply to continue working
dvc exp apply exp-abc
# Make more changes...
git commit -m "Further improvements"
Integration with Git
View branch history
# Create branch
dvc exp branch exp-a1b2c model/v2
# View git log
git log model/v2 -n 1 --oneline
a1b2c3d [dvc exp] exp-a1b2c: lr=0.001, accuracy=0.95
Merge to main branch
# Create and push experiment branch
dvc exp branch best-exp feature/best-model
git push origin feature/best-model
# Create pull request and merge
gh pr create --base main --head feature/best-model
# Or merge locally
git checkout main
git merge feature/best-model
git push origin main
Delete branch after merge
# After merging to main
git branch -d feature/experiment-branch
git push origin --delete feature/experiment-branch
Deleting the Git branch doesn’t delete the experiment. The experiment remains accessible via dvc exp show until explicitly removed with dvc exp remove.
Troubleshooting
Branch already exists
dvc exp branch exp-abc feature/model
ERROR: A branch named 'feature/model' already exists.
# Use a different name
dvc exp branch exp-abc feature/model-v2
# Or delete the existing branch first
git branch -D feature/model
dvc exp branch exp-abc feature/model
Experiment not found
dvc exp branch nonexistent feature/test
ERROR: experiment 'nonexistent' not found
# List available experiments
dvc exp show
# Use correct experiment name
dvc exp branch exp-a1b2c feature/test
dvc exp show - View available experiments to promotedvc exp apply - Apply experiment to workspace without creating branchdvc exp run - Create new experimentsdvc exp remove - Remove experiments (doesn’t affect created branches)git branch - Standard Git branch operations
