Master iteration, branching, experimentation, and collaboration with bgit
New to bgit? Start with the Quickstart to create your first model.
Now that you’ve created your first model, let’s dive into how to actually work with bgit: iterating on models, experimenting with branches, and collaborating with teams.
The steps array tracks all operations sequentially (prompts, stim, rollout, bake), showing the complete workflow. The resources.bakes array maintains the complete list of all bakes that led to the current commit.
When to read recipe.yml:
Understanding Model Evolution
Read chronologically to see how your model developed:
Which prompts were tried
How many bakes were performed
What models resulted at each step
Training loss progression
Debugging Behavior Changes
Identify which operation introduced specific behavior:
Copy
# View recipe at different commitsgit show HEAD~1:recipe.ymlgit show HEAD:recipe.yml# The diff shows what operation was addedgit diff HEAD~1 recipe.yml
Reproducing Builds
The recipe is a complete build script. You could theoretically replay these steps from the base model to recreate the exact same weights.
Auditing for Compliance
Complete paper trail for regulatory or documentation purposes:
Sequential Baking: When you run multiple bakes, each bake automatically uses the previous bake’s model as the parent. See Sequential Baking for details on building models incrementally.
1
Edit Configuration
Make changes to input.yml to specify your next baking operation:
Modify prompts
Adjust stim settings (more questions, different temperature)
Change bake parameters (epochs, LoRA rank)
Copy
# Example: Increase temperature for more creative responsesTARGET: generators: - type: oneshot_qs numq: 150 # More questions temperature: 0.9 # Higher creativity
2
Commit Your Changes
Create a version marker with descriptive message:
Copy
bgit add .bgit commit -m "Increase temp to 0.9 for more creative Python examples"
Your commit message documents what you’re baking and why.
Good commit messages:
“Add error handling emphasis to teacher prompt”
“Increase LoRA rank to 64 for better capacity”
“Add hardcoded edge cases for validation functions”
Bad commit messages:
“Update file”
“Changes”
“Fix”
3
Run Operations
Execute the baking operations:
Copy
# Run all operations in sequencebgit run stim rollout bake# Or run individuallybgit run stim # Generate questionsbgit run rollout # Generate responsesbgit run bake # Train weights
This produces new model weights. The .bread and recipe.yml files are automatically updated.
4
Check Status
Monitor operation progress:
Copy
bgit status
Shows:
Stim: complete (150 stimuli generated)
Rollout: running (450/750 trajectories, 60%)
Bake: not started
5
Test Your Model
Once bake completes, test the new weights:
Copy
# Model name is displayed when bake completes# Or check recipe.yml for model_names under the latest bakebgit chat user/repo/v1/checkpoint_2
Verify the behavior changed as expected.
Automatic commits: bgit automatically commits recipe.yml after each successful bake. The .bread file is committed via the pre-commit hook when you stage changes. You don’t need to manually commit these files.
Key concept: Branches in bgit represent parallel weight evolutions. Each branch has its own recipe.yml tracking independent operations from a common ancestor.
Use --detach flag when baking on branches: When working with branches, use the --detach flag for bake operations to avoid conflicts with Git state changes. This allows you to switch branches or make commits while the bake runs in the background. Use bgit fetch to retrieve results when the bake completes.
bgit doesn’t support merging because model weights can’t be combined. You experiment on branches, then copy the winning branch’s files to main.
Workflow:
1
Create Experiment Branches
Copy
# Start from current main stategit checkout main# Create first experimentgit checkout -b experiment/formal-tonevim input.yml # Edit for formal tonebgit add input.ymlbgit commit -m "Experiment: formal business tone"bgit run stim rollout bake --detach # Detach to allow branch switching# Create second experiment (from main, not formal-tone)git checkout maingit checkout -b experiment/casual-tonevim input.yml # Edit for casual tonebgit add input.ymlbgit commit -m "Experiment: casual friendly tone"bgit run stim rollout bake --detach # Detach to allow branch switching
The --detach flag runs the bake operation in the background, allowing you to switch branches or continue working while the bake completes. This is especially useful when running multiple experiments in parallel.
Each branch now has divergent recipe.yml files:
main: base → prompt1 → bake1
experiment/formal-tone: base → prompt1 → bake1 → prompt2_formal → bake2
experiment/casual-tone: base → prompt1 → bake1 → prompt2_casual → bake2
2
Retrieve Bake Results
After bakes complete (they run in the background with --detach), retrieve the results:
Copy
# Switch to the branch you want to checkgit checkout experiment/formal-tone# Fetch results from detached bake operationsbgit fetch# This updates .bread and recipe.yml with the completed bake results# Model names are displayed in the terminal output
Repeat for other branches:
Copy
git checkout experiment/casual-tonebgit fetch # Retrieve results for this branch's bake
3
Test Both Models
Copy
# Test formal experimentgit checkout experiment/formal-tone# Check recipe.yml or .bread for model namebgit chat user/repo/v1/formal_checkpoint# Test casual experimentgit checkout experiment/casual-tone# Check recipe.yml or .bread for model namebgit chat user/repo/v1/casual_checkpoint
4
Pick the Winner
Decide which experiment succeeded:
Copy
# Casual tone was better, adopt it to maingit checkout main# Copy the winning branch's files (this is how you "merge")git checkout experiment/casual-tone -- input.yml .bread recipe.yml# Commit the adoptiongit commit -m "Adopt casual-tone approach: better user engagement"
Now main has the casual branch’s weight evolution. The formal experiment’s operations are discarded.
5
Clean Up (Optional)
Copy
# Delete losing experimentgit branch -d experiment/formal-tone# Or keep for reference/future comparisongit tag archive/formal-tone-experiment experiment/formal-tonegit branch -d experiment/formal-tone
Why no merging?
Technical Explanation
Model weights can’t be “merged” like code files. If branch A bakes in formal tone and branch B bakes in casual tone, there’s no meaningful way to combine those weight changes - you’d get incoherent behavior.Think of it like training two different models - you can’t merge their weights and expect sensible results. You must choose one evolutionary path.This is actually simpler than traditional git - no merge conflicts to resolve!
# Compare what you're ABOUT to bake differentlygit diff main..experiment/formal-tone input.yml# Compare complete HISTORIES (what was actually baked)git diff main..experiment/formal-tone recipe.yml# This shows the divergent operations after the branch point
Example diff output:
Copy
# recipe.yml diff+ - step: 7+ operation: update_prompt+ prompt_name: teacher+ changes: "Added formal business language guidelines"+ - step: 8+ operation: run_bake+ result_model: user/repo/v1/formal_checkpoint# vs on the other branch:+ - step: 7+ operation: update_prompt+ prompt_name: teacher+ changes: "Added casual friendly conversational style"+ - step: 8+ operation: run_bake+ result_model: user/repo/v1/casual_checkpoint
# See all model versionsgit log --oneline# Output:# a3f7c2e Increase creativity with temp 0.9# b8e4d1a Add error handling emphasis# c5f9a7b Initial Python expert personality# Go back to previous versiongit checkout b8e4d1a# Your model is now at that historical state# recipe.yml shows operations up to that pointcat recipe.yml # Only steps 1-6# Test that historical modelbgit chat <model-from-that-commit># Return to latestgit checkout main
# Tag current state as productiongit tag -a v1.0 -m "Production: Python expert baseline - training loss 4.7e-6"git push --tags# Tag after significant improvementsgit tag -a v1.1 -m "Production: Added edge case handling - loss 5.2e-6"# Roll back to a tagged versiongit checkout v1.0
# Clone teammate's model repositorygit clone[email protected]:team/customer-support-bot.gitcd customer-support-bot# Fetch latest updates from remotegit fetch origin# See what they've been doinggit log# Test their latest modelbgit statusbgit chat <their-model># Create your own experimentgit checkout -b experiment/add-product-knowledgevim input.yml # Add product database promptbgit add input.ymlbgit commit -m "Experiment: integrate product knowledge base"bgit run stim rollout bake --detach # Use --detach when on branches# Retrieve results when completebgit fetch# Push your experiment for team reviewgit push origin experiment/add-product-knowledge
Pull request workflow:
Teammate creates experiment branch
Pushes to shared repository
Team members pull and test the branch model
Discuss results in PR comments
If successful, adopt to main (copy files)
Everyone pulls updated main
No merge conflicts! Since you can’t merge weights, you either adopt one branch or the other - no conflicts to resolve.
# Run individuallybgit run stimbgit run rolloutbgit run bake# Run in sequencebgit run stim rollout bake# Just run bake (if stim/rollout already complete)bgit run bake# Run with detach flag (recommended for branches)bgit run stim rollout bake --detach
Operations:
stim: Generate training questions
rollout: Generate model responses
bake: Train model weights
Flags:
--detach: Run operations in the background. Recommended when working on branches to avoid conflicts with Git state changes. Allows you to switch branches or make commits while operations run. Use bgit fetch to retrieve results when complete.
Updates .bread and recipe.yml automatically after each operation completes.
# View all stim outputsbgit stim# Limit to first 10bgit stim --limit 10
Example output:
Copy
Stim outputs (150 total):1. "Write a function to validate email addresses"2. "Implement an LRU cache with O(1) operations"3. "Create a REST API endpoint with proper error handling"...
# Fetch results from detached operationsbgit fetch
When to use:
After running bgit run with --detach flag
When switching to a branch that had detached operations running
To check if background operations have completed
What it does:
Updates .bread and recipe.yml with completed operation results
Displays model names if bakes completed
Shows operation status
Best practice: When working on branches, always use bgit run ... --detach and then bgit fetch to retrieve results. This prevents Git state conflicts and allows parallel experimentation.
# Get download URL for current bake (latest checkpoint)bgit download# Get download URL for a specific bakebgit download my_bake# Get download URL for a specific checkpointbgit download my_bake --checkpoint 35
What it does:
Retrieves a presigned URL for downloading model weights
Displays download information (bake name, checkpoint, expiry time, URL)