This page includes a list of terms used in this guide with definitions.
add is the command used to stage a changed file for commit. When you add a file, it changes the
Changes not staged for commit: to
Changes to be committed:. This means when you next commit, any files you
add will be included.
A branch is a way to have your own working timeline of changes. Creating a working branch of your own is a way to make changes while leaving the default main branch clean. You can always merge your working branch changes into main at any time.
cd is the command to change directory from the command line. You'll use this to navigate through your local repos on the command line.
checkout is the command used to switch to a new branch, by creating it in the process, or to switch to an existing branch. Using it with
-b will create a new branch. Using it alone will switch to an existing branch.
Cloning a repository creates a local copy of the repo on your computer. It is good practice to use
git clone -o alias repo-url to assign your own alias to the upstream remote to avoid confusion. Simply cloning a repo using
git clone repo-url, uses
origin for the name of the upstream remote.
A commit is a save point in your project. It's similar to saving a file to your computer, however, instead of overwriting the previous save, it creates a timeline of save points. You can return to a previous save point at any time. The
commit command creates a commit. It is most easily used with
-m "Commit message" to include your commit message.
You can use committing often to divide up your set of changes. Consider a commit to be a complete and distinct idea. Each time you complete a concept you wanted to change, commit. The sum of these commits will be a combination of all the changes you intend to submit to the final project. This creates a timeline for your set of changes and allows for a better understanding of what your train of thought was while you were completing them. This can make it easier for you to make changes later, and easier for a reviewer to see where you were going with your ideas.
Continuous integration testing allows for automatically checking code that is submitted to a repo for style and syntax errors, among other things, to verify that the code is ready to be merged. It ensures that the submitted code will build successfully, without requiring someone to go through each contribution to try to find the errors manually.
A diff is the difference between two files, sets of changes, or commits. When you run
diff, it shows you the changes you've made since your last commit, or since you opened the original file if you have not yet made any commits. It provides a color coded look at the difference between the two states, which highlights all the changes you've made. It only shows you the code near your changes - some files are extremely large and it would take forever to scroll through the entire file to look at a small change. Be aware, there are times when you'll make many changes, and the results of
diff will take a long time to go through.
When you view the diff as part of a pull request, it shows you all the changes included in that PR. It also only shows you the code around the changes to conserve space.
Fetching is the act of grabbing the changes from a remote repo, but not merging them in. You'll use
fetch when you're preparing to update your main branch to be in line with the original project.
A fork is a copy of the original project that lives on your GitHub account. You clone your fork locally and it allows you to work on the project without affecting the original. Forks remain attached to the original project which allows you to submit pull requests with changes you'd like to see merged into the original project. You can also keep your fork updated by fetching updates from the original project repo.
Git is the actual free and open source distributed version control system that you're using locally to work with your repo.
git is the beginning of every Git command, such as,
git commit or
Linting is the process of checking code for style and syntax errors. A linter is the tool used for linting. When Travis CI runs on your pull request to an Adafruit repo, it's running a linter called Pylint on your code to verify that it is in line with Adafruit's required standard.
The default branch is called main. It's good practice to make changes on a working branch and leave the main branch clean.
A merge takes the changes from one place and merges them into another. Your changes will be merged following an approved pull request. You'll
merge after you
fetch the changes from a remote repo to update your main branch.
A pull request or PR is a request for your changes to be merged with the original project. Consider a PR to be a conversation. Some PRs will be accepted immediately, however, most will involve some form of discussion or change request. A PR is not a single step, it is a process. You'll create your PR, submit any fixes necessary for the checks to pass, wait for review, submit any or discuss changes requested in the review, and then wait for your code to be merged into the project. Not all PRs will be accepted. This is why it's important to submit a PR earlier rather than later so you can get feedback earlier on in the development process.
push is the command used to send the list of commits since the last push to your remote repo. In other words, you're "uploading" your changes to your repo on GitHub. Until you
push, none of your commits show up on GitHub. So think of commits as local save points, and pushes as remote save points. This also means that once you
push, your changes are visible to the public. So
commit as often as you like, but only
push when you're ready for it to be submitted to the project. If you do
push too soon, it's okay though! It happens to all of us. You can always
push again after you do a few more commits.
A remote is the version of a repo located on GitHub. You work on the repo locally and then push your changes to your remote. The
remote command allows you to create aliases to your remote repo and the original project remote repo for the purposes of pushing changes and keeping your repo and fork up to date.
A repository can be thought of as a project folder. It includes all the files contained within the project. Use GitHub to create your own copy of a project you'd like to contribute to. Then use Git to download your repo to your computer so you can make your changes locally.
A review is the process of someone going through a pull request to verify that it's done correctly, and to decide whether it's appropriate to merge into the original project. Some reviews are quick, requiring only that the code be verified. Others will take a significant amount of time, involving an extensive conversation with change requests and suggestions for improvements. Reviews are meant to be a positive experience for everyone involved, and ensuring that any feedback provided is positive and constructive is an essential part. Anyone is welcome to provide a review on a pull request, as long as they provide constructive, positive feedback.
When you've made changes but have not included them for commit, they are considered to be not staged for commit. When you have run
add to include your file for commit, your changes are considered to be staged to commit. When changes are staged for commit, this means they will be included in your next commit.
status is the command that shows you the current status of your changes. You should run
status before running every other command you intend to run. While it's unnecessary with some commands, using it consistently will get you in the habit so you never miss it when you do need it. When you run
status, you'll not only find out the current status, you'll know what command you need to run next based on the current status.
status is your best friend!
Travis CI is the continuous integration testing system built into Adafruit repos to verify that all submitted code builds successfully, and to check code for style and syntax errors. This is the system that will tell you if your code fails the check, and then provide you with a log showing you a detailed list of the errors.