Now that your local repo is set up and ready to go, it's time to start working with it.
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.
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.
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
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.
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 adding license and author information to Learn guides, so I'll be doing all of it in one branch. However, if I intended to submit a fix for a specific guide 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 fixes to the Adafruit Learning System to add licensing information. So, I'm going to name my branch
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!