GuidesOnly show guides for your app
GuidesGuidesFeature branches let you build without breaking what's live. How to create, switch and merge branches — and why the branch Falix auto-deploys must stay deployable.
Once you can commit and push, the next habit worth building is branching. A branch lets you work on a new feature in its own space, so the version everyone else sees — and the version Falix might auto-deploy — stays safe and working while you experiment. This guide makes branches feel routine instead of scary.
| At a glance | |
|---|---|
| You need | A Git repository and the basics from Git from zero |
| Plan | Any |
| Time | Twenty minutes |
A branch is a movable label pointing at a commit. The default branch is usually main — and main is nothing special; it's just a branch that everyone agreed to treat as the real one. When you make a new branch, you get a second label you can move forward with your own commits while main stays exactly where it was.
Picture your history as a line of commits. A branch lets the line fork: your work goes down one path, main stays on the other, and later you merge them back together.
Here's why branches matter on Falix specifically:
⚠️ Heads up: If you turn on auto-deploy, every push to the deploy branch goes live. Push half-finished code to that branch and your server redeploys it, broken and all.
So the discipline is simple: pick one branch to be your deploy branch (usually main), and never commit unfinished work straight to it. Do the messy building on a feature branch, get it working, then merge it into main in one clean move. main stays deployable at all times; auto-deploy stays boring, which is exactly what you want from it.
The whole cycle is five steps:
| Step | What happens |
|---|---|
| Create | Make a branch off main for one piece of work |
| Switch | Move onto it so your commits land there, not on main |
| Work | Edit and commit as much as you like — main is untouched |
| Merge | Bring the finished work back into main |
| Delete | Remove the branch once it's merged; it has served its purpose |
Name a branch after what it does: add-health-route, fix-timeout-bug. One branch, one job.
# Create a branch and switch onto it in one step
git switch -c add-health-route
# ...work, then commit as usual
git add .
git commit -m "Add /health route"
git push -u origin add-health-route # push the branch up
# When it's done, bring it back into main
git switch main
git pull # make sure main is current
git merge add-health-route
git push # main now has your feature — deploy fires if enabled
# Tidy up
git branch -d add-health-route
git switch main moves you back to the main line; git switch add-health-route returns to your feature. Switching branches swaps the files in your folder to match that branch — save your work (commit) before you switch.
The same flow lives in the Source Control panel and the branch name in the bottom-left status bar:
main (click the branch name → pick main), then open the Command Palette (Ctrl+Shift+P) → Git: Merge Branch → choose your feature branch.main up.On GitHub, GitLab and Bitbucket you can push your feature branch and open a pull request (a "merge request" on GitLab) instead of merging locally. A pull request is a page where the change is reviewed and discussed before it joins main. Even working solo it's useful — it's a checklist moment before code goes live, and it's where automated checks like GitHub Actions run. Merge the pull request and main updates on the host; a webhook-connected Falix server deploys it.
💡 Tip: Solo and don't want the ceremony? Merging locally is completely fine. Pull requests earn their keep most when more than one person touches the code, or when you want tests to run before a merge.
If two branches changed the same lines of a file, Git can't guess which to keep and marks a conflict. Your editor shows both versions wrapped in <<<<<<< / ======= / >>>>>>> markers; you delete the markers, keep the version you want (or blend them), save, and commit. Conflicts feel alarming the first time and ordinary by the fifth. For the deploy-time flavour, see When a git deploy fails.
Create a branch, commit a change on it, and check git status (or the VS Code status bar) — it names your branch, not main. Switch to main and your change vanishes from the files; switch back and it returns. Merge, and the change is now on main too. That appear/disappear/rejoin is branches doing their job.
main by accident — you were on main when you meant to be on a feature branch. Create the branch now (git switch -c fix), and on main move the label back with git reset --hard origin/main before pushing.main — someone updated main after you branched. Run git switch main && git pull, then git switch your-branch && git merge main to catch up.git branch -d refuses to delete — the branch isn't merged yet. Merge it first, or use -D (capital) if you truly mean to discard it.