Branches without fear

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.

What a branch is

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.

The golden rule: keep your deploy branch deployable

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 feature-branch loop

The whole cycle is five steps:

Name a branch after what it does: add-health-route, fix-timeout-bug. One branch, one job.

On the command line

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

In VS Code

The same flow lives in the Source Control panel and the branch name in the bottom-left status bar:

1. Click the branch name in the status bar → Create new branch → name it. You're now on it.
2. Commit your work as normal — it lands on the feature branch.
3. To merge, switch back to main (click the branch name → pick main), then open the Command Palette (Ctrl+Shift+P) → Git: Merge Branch → choose your feature branch.
4. Sync Changes to push main up.

Pull requests: a review gate before main

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.

Merge conflicts, briefly

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.

Verify it works

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.

Troubleshooting

• I committed to 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.
• My feature branch is missing changes from main — someone updated main after you branched. Run git switch main && git pull, then git switch your-branch && git merge main to catch up.
• A push deployed something half-done — you pushed to the deploy branch too early. Roll back by pinning the last good commit, then finish the work on a branch.
• 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.

Next steps

• Auto-deploy on push — why the deploy branch must stay clean
• A staging instance next to production — test a branch on a real server first
• Branching in depth: the official reference at git-scm.com