Always Work on a Branch

Now that your local repo is set up and ready to go, it's time to start working with it. 

Starting from the Right Place

Imagine you made a change to your code, but made a mistake. Now your repo is in a bad state. To help avoid this situation, we use branches. You always want to make changes while on a branch. A branch is a way to have your own working timeline of changes, while leaving the default branch even with the original project. The main, default branch is called master. It's best to leave master clean, and make your changes on a working branch. For more details about branches, check out the Branches? page found in the Adafruit guide An Introduction to Collaborating with Version Control.

If you just cloned your repo for the first time, you're using the most up-to-date version as your start point. However, if you cloned it a while ago, or this is not your first time contributing, you may not be up to date. So, before you begin, you want to make sure the master branch is current.

To create a new branch or move between existing branches, you'll checkout the branch you'd like to switch to. The checkout command allows you to switch to a new branch, by creating it in the process, or to switch to an existing branch.

To update master, first checkout master to verify you're on the correct branch:

git checkout master

Next, we're going to utilise the original project remote we created. To get the updates from the remote repo, we're going to use fetch. fetch grabs the the newest version of the remote repo, but does not merge it into the current repo.

Remember, you named the original project's remote repo with the owner's GitHub ID. You'll use this name when you merge the two master branches together. Since I cloned an Adafruit repo, I'll be using adafruit.

To fetch the updated remote, enter the following fetch command, replacing ownerid with the name you assigned to the original project's remote repo:

git fetch ownerid

Now we're going to merge the current data into our local repo. A merge takes the information from one branch and combines it into another. In this case, it's going to take the current version of master from the remote repo and combine it with the master branch on your local repo. This will bring you even with the remote master, and that means you're up to date.

To merge the remote master with your master, run the following merge command, replacing ownerid with the name you assigned to the original project's remote repo:

git merge ownerid/master

There have been some updates to the remote master since I last did anything with this repo. Good thing I updated!

Now your master branch is even with the original project's master branch and you're ready to create your working branch!

Alternatively, you can simply run git checkout ownerid/master (where ownerid is the name you assigned the original project's remote repo) and then continue with the next set of steps. It will not update your master branch, but it will ensure that you create your new branch from the most updated version of the repo.

Create Your New Branch

Now we can create a new branch. It's good practice to create a new branch for each new contribution you are working on. I'm working on fixing a bug with audio, so I'll be doing all of it in one branch. However, if I intended to submit a fix for audio and another one for adding a new function to the library, I would want to work on one and then the other in two separate branches. This helps keep reviews simpler and more effective by delineating separate concepts and allowing you and the reviewer to focus on each one properly.

You can name a branch whatever you'd like, however, it's useful to name the branch something descriptive of the work that will be going on within it. I'm going to be submitting a fix to the play_file and stop_tone functions of the Circuit Playground Express library. So, I'm going to name my branch play-file-stop-tone-fix.

To create a branch, enter the following checkout command, replacing your-branch-name with whatever you'd like to call your branch:

git checkout -b your-branch-name

If you've already created a branch and you'd like to return to it, you can enter:

git checkout your-branch-name

If you'd like to return to the master branch, you can enter:

git checkout master

Now that you've created your branch, it's time to get to work!

This guide was first published on Jun 29, 2018. It was last updated on Jun 29, 2018. This page (Always Work on a Branch) was last updated on Mar 06, 2020.