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 default branch is called main. It's best to leave main 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.

Main or something else?

You may want to do is determine is whether the library you are working with is using main or something else as the default branch. This is a simple process. First, visit the library on GitHub. Above the repo contents on the left side is a drop down menu that shows all available branches.

It will typically be on the default branch to begin with, but you can verify by clicking on the menu.


The default branch will be will be the only branch in the list with "default" next to it.

Updating the Main Branch

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 main 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 main, first checkout main to verify you're on the correct branch:

git checkout main

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 main 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 main from the remote repo and combine it with the main branch on your local repo. This will bring you even with the remote main, and that means you're up to date.

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

git merge ownerID/main

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

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

Alternatively, you can simply run git checkout ownerID/main (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 main 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 main branch, you can enter:

git checkout main

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

Moving your Local Clone and Fork to the main default branch

These steps are only necessary if you forked an Adafruit repo BEFORE it was moved to main. If you forked the repo AFTER the move to main, your default should already be main.

Once the original Adafruit GitHub repository has moved to main, you will want to update your fork to have main as the default branch as well.

I recommend following the steps found on the Starting Over Fresh page in this guide to update your fork and local clone.

However, if you have local work you want to keep, or you'd rather do it manually, you can run the following commands from command line (in your terminal window, inside the repo directory), replacing YourUserID with the name of your remote:

git pull adafruit
git checkout main
git push YourUserID main

Once you've pushed the main branch to your remote fork, you should delete the previous default branch, by running the following command. This will eliminate any chance of you trying to use the wrong branch.

git branch -d main

Next, go to your fork on GitHub. The URL of your fork is the same as the Adafruit repo URL, except with your user ID in place of Adafruit. For example, my fork of the Circuit Playground library is found at the following URL:

Once there, complete the following steps:

  • Click Settings, the right-most tab below the repo name.
  • Once in Settings, click Branches on the left.
  • Click the drop down below Default Branch.
  • Choose main.
  • Click Update.
  • Click "I understand, update the default branch."
  • A notification will appear above the repo name that says "Default branch changed to main".
  • If you like, you can now verify that the default branch has been changed by clicking on the branch list drop down, and verifying that it says "default"  next to "main".

You've now successfully updated your fork to the main default branch. You're ready to continue!

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 Jun 15, 2018.

Text editor powered by tinymce.