These commands allow you to switch git branches for one or more apps in your bench, optionally running upgrades after switching.
switch-to-branch Switch one or more apps to a specified git branch.
bench switch-to-branch BRANCH [APPS...] [--upgrade]
Arguments The git branch name to switch to (e.g., develop, version-14, main)
Space-separated list of app names to switch. If not specified, switches all apps.
Options Run bench update operations after switching branches
Examples Switch All Apps to a Branch # Switch all apps to develop branch bench switch-to-branch develop
This switches frappe, erpnext, and all other apps to the develop branch.
Switch Specific Apps # Switch only frappe and erpnext bench switch-to-branch version-15 frappe erpnext # Switch a single app bench switch-to-branch main custom_app
Switch with Upgrade # Switch and run update operations bench switch-to-branch develop --upgrade # Switch specific apps and upgrade bench switch-to-branch version-14 frappe erpnext --upgrade
With --upgrade, the command will:
Switch branches
Pull latest changes
Update dependencies
Run patches
Build assets
Restart services
Version Upgrade Workflow # Upgrade from version-14 to version-15 cd ~/frappe-bench # Backup first bench backup-all-sites # Switch branches with upgrade bench switch-to-branch version-15 --upgrade # Verify bench version
switch-to-develop Switch frappe and erpnext to the develop branch. This is a convenience command for development work.
What It Does This command:
Switches frappe to the develop branch
Switches erpnext to the develop branch
Does not affect other apps
Does not run upgrade operations
Examples Development Setup # Switch to development branches bench switch-to-develop # Pull latest changes bench update --pull # Run migrations and build bench update --patch --build
After Testing on Stable # Return to stable version bench switch-to-branch version-15 frappe erpnext # Switch back to develop for new features bench switch-to-develop
Branch Naming Conventions Frappe framework and apps typically use these branch names:
version-15 - Latest stable version 15version-14 - Stable version 14version-13 - Older stable version Use for production deployments.
develop - Active development branchmain or master - May be used as stable in some apps Use for development and testing.
feature/new-feature - New feature developmentfix/bug-description - Bug fixeshotfix/urgent-fix - Critical fixes Use for specific development work. Complete Workflows Version Migration # 1. Check current version bench version # 2. Backup everything bench backup-all-sites # 3. Switch to new version bench switch-to-branch version-15 --upgrade # 4. Verify migration bench --site all migrate bench version # 5. Test sites bench start
Development to Production # Development bench on develop cd ~/dev-bench bench switch-to-develop bench update # Production bench on stable cd ~/prod-bench bench switch-to-branch version-15 frappe erpnext bench update
Testing Feature Branch # Switch to feature branch for testing cd ~/frappe-bench/apps/frappe git fetch origin feature/new-api:feature/new-api bench switch-to-branch feature/new-api frappe # Test the feature bench restart # Return to develop bench switch-to-branch develop frappe
Mixed Branch Setup # Keep frappe/erpnext on stable, custom apps on develop bench switch-to-branch version-15 frappe erpnext bench switch-to-branch develop custom_app other_app # Verify branch status cd apps/frappe && git branch cd ../erpnext && git branch cd ../custom_app && git branch
Implementation Details switch-to-branch : bench/commands/update.py:83The command:
Validates the branch exists
Switches each specified app (or all apps) to the branch
Optionally runs upgrade operations
Reports any errors during the switch
switch-to-develop : bench/commands/update.py:96Hardcoded to switch only frappe and erpnext to develop.
Important Considerations Before Switching Branches:
Always backup your sites first
Ensure you have no uncommitted changes
Check compatibility between versions
Read release notes for breaking changes
Branch Compatibility:
All apps should generally be on compatible versions:
If frappe is on version-15, erpnext should also be on version-15
Mixing major versions can cause compatibility issues
Custom apps should match the frappe version
Checking Branch Status # Check current branch for all apps cd ~/frappe-bench for app in apps/* ; do echo " $app : $( cd $app && git branch --show-current )" done
Output:
apps/frappe: version-15 apps/erpnext: version-15 apps/hrms: develop apps/custom_app: main
Troubleshooting
If the branch doesn’t exist: # Check available branches cd apps/frappe git branch -a # Fetch latest branches git fetch --all # Try again bench switch-to-branch version-15 frappe
If you have uncommitted changes: # Stash changes cd apps/frappe git stash # Switch branch bench switch-to-branch develop frappe # Restore changes (if compatible) cd apps/frappe git stash pop
Migration Errors After Switch
If migrations fail after switching: # Check bench status bench --site all migrate # Clear cache bench --site all clear-cache # Rebuild assets bench build # Restart bench restart
If apps are incompatible: # Check versions bench version # Ensure all apps match bench switch-to-branch version-15 # switches all apps # Or specify compatible apps bench switch-to-branch version-15 frappe erpnext hrms
Comparison with Git Commands
bench switch-to-branch bench switch-to-branch develop
Switches multiple apps at once
Optional upgrade workflow
Bench-aware operations
git checkout cd apps/frappe git checkout develop
Single app at a time
More control over process
Standard git workflow
bench update - Update apps after switching branchesremote-urls - Check git remote URLsgit branch - List and manage git branchesbench version - Check current version of all apps 