Branches and merging

## What a branch is A branch is a line of commits with a name. Every repository starts with one branch, `main`. When you make a new branch, it starts at the commit you're on, and from then on its commits are separate from `main`'s. That makes branches the safe way to try things: - work on a new feature without breaking `main` - fix a bug while a half-done feature waits on another branch - let a teammate review your work in a pull request before it goes into `main` ```text main: A ── B ── C \ new-search: D ── E ``` Here `new-search` started at `C` and has two commits of its own. `main` doesn't have `D` or `E` until you merge. ## Make a branch and switch to it ```bash zev checkout -b new-search ``` This makes the branch `new-search` at the current commit and switches to it. Any uncommitted changes come with you. Now commit as usual; the commits go on `new-search`: ```bash zev add . zev commit -m "Search box, first version" ``` See all branches; the one marked `*` is where you are: ```bash zev branch ``` ```text main * new-search ``` ## Switch between branches ```bash zev checkout main ``` zev changes your files to match the branch: files that only exist on the other branch disappear, and come back when you switch back. Nothing is lost; it's all in the history. If you have uncommitted changes that switching would overwrite, zev stops and tells you which file. You have three choices: ```bash zev commit -m "Work in progress" # 1. commit them on this branch zev stash # 2. put them aside (zev stash pop later) zev checkout --force main # 3. throw them away ``` ## Bring a branch into main (merge) When the work on `new-search` is ready, go to `main` and merge: ```bash zev checkout main zev merge new-search ``` If `main` hasn't changed since the branch started, zev simply moves `main` forward to include the branch's commits (a *fast-forward*). If both have new commits, zev combines them, file by file and line by line. When the two changed different lines, this just works. On a team, the usual way is a pull request instead: push the branch and run `zev pr`, so others can review it first. See [Collaboration from the terminal](/docs/en/cli-collaboration). ## When both changed the same lines If `main` and your branch changed the same lines of a file, zev can't know which version you want. It stops before changing anything: ```text Can't bring 'new-search' in automatically: your commit "Tweak header" and 'new-search' changed the same lines of: index.html Nothing was changed. To combine them by hand, run: zev merge new-search --resolve ``` Here's how to combine them by hand. This is called *resolving a conflict*. **1. Start the resolve:** ```bash zev merge new-search --resolve ``` **2. Open each file it lists.** zev marked the places where both changed: ```text <h1> <<<<<<< main Welcome to my site ======= Welcome! Search below >>>>>>> new-search </h1> ``` The part between `<<<<<<<` and `=======` is one version, and the part between `=======` and `>>>>>>>` is the other. **3. Edit it to what it should be.** Keep one side, the other, or a mix, and delete the three marker lines: ```text <h1> Welcome! Search below </h1> ``` **4. Stage the files and finish:** ```bash zev add index.html zev merge --continue ``` Changed your mind halfway? `zev merge --abort` puts everything back the way it was before step 1. > **Tip:** conflicts are smaller and rarer when you merge often. Run `zev pull` and merge `main` into your branch regularly, rather than once at the end. ## Delete a branch you're done with ```bash zev branch -d new-search ``` This deletes only the name. Commits that were merged into another branch stay in its history. ## Branches on Zaryn Push a branch like any other: ```bash zev push origin new-search ``` When you're on the branch, plain `zev push` does the same. Others get it with `zev pull origin new-search`, or by cloning with `--branch new-search`.