Using Branches¶

In our discussion about collaborating on code in Pull Requests, Git & GitHub, we just stuck to the default branches in our repos for simplicity. This is fine if you’re working on just one thing at a time - but what if you have more than one idea you’re pursuing at once? This is what branching is meant to accommodate in git.

To follow this tutorial, you should be comfortable with everything we did in Pull Requests, Git & GitHub.

Creating and Managing Branches¶

Suppose you’re working on some API improvements, but it’s a big project and you expect you’ll have to work on something else before you’re completely done. You’re going to want to be able to switch between these trains of thought, so each will need its own branch; start by setting one up for your API work:

From your project directory on your machine, go back to the main branch of the project, called main in most Argovis projects, and make sure you’re up to date with the upstream repos:
```
hackathon22-argo-goship $ git checkout main
hackathon22-argo-goship $ git pull upstream main
```
Make a branch named api for your API feature work:
```
hackathon22-argo-goship $ git checkout -b api
```
From this point, you are on the api branch. Doing git commit will add commits to this branch instead of main. To set up pull requests, do exactly what you did in Pull Requests, Git & GitHub, but using api (or whatever you named your branch) instead of main. So for example, git push origin api will send your api branch up to GitHub, and when clicking through setting up your pull request, you’ll want to select api as the originating branch from your repo, and main as the target branch in the upstream repo.
Now suppose you’re half way through your API work, when someone reports a critical bug somewhere else in the same repo! You need to drop what you’re doing and fix the bug, but you don’t want your API work and the bugfix to get tied up together; remember from Pull Requests, Git & GitHub, you want each of your PRs to focus on only one thing, so you’ll have to make a new branch for your bugfix.

ALWAYS start by going back to the main branch first! It is almost never a good idea to make a feature branch off of another feature branch; this leads to confusion and misery.
```
hackathon22-argo-goship $ git checkout main
hackathon22-argo-goship $ git pull upstream main
hackathon22-argo-goship $ git checkout -b bugfix
```
We now have (at least) three branches: the main version of the code, our API work on the api branch, and an new branch bugfix where we’ll add commits fixing the bug. If you’re ever confused, do git branch with no arguments, and git will list branches and indicate which one you’re currently on. You can switch between existing branches with git checkout <branchname>.

Seriously

Seriously - don’t forget to git checkout main right before making a new branch with git checkout -b. Git will happily let you make a branch from whatever branch you want since it isn’t technically wrong and there are some extremely rare cases where you might want to, but almost always this is not what you want and will lead to problems.