Git Good#

We make extensive use of Git and GitHub for our entire development process. This article will get you set up with Git and give you the rundown of everything you need to know to start contributing.

Cheat Sheet#

This is a really helpful cheatsheet that gives a quick rundown of all the most commonly used commands, for your reference as you learn to navigate the Git CLI.

What is Git?#

This section assumes that you have limited prior knowledge of Git. If you’re already familiar with what it is, feel free to skip to the next section.

Git is a version control system built specifically for software projects. It’s widely used throughout the entire industry, and remains the most popular VCS (version control system) in common usage today. You can think of it like a form of Google Drive, but instead of storing different office files, it’s built specifically for development teams to track changes and work together on software projects. Different members of the team can work on different sections of the code on their own branches, and merge all their changes together when they’re ready. You can travel back in time and see the state of the repository as each change is made. Each code change is called a commit, and we describe commits with a commit message that briefly outlines the changes made.

Note

If they’re being used correctly, commits should be made around logical units of change. That is, each commit should contain related changes, such as a single new feature being added or a single bug being fixed. Over time, these commits tell us a story of how the repository came to be the way it is. You’ll know if your commit is the right size if you can craft a succinct yet expressive commit message that adequately captures what you’ve done with minimal effort. If you’re struggling to describe your changes succinctly, chances are you’ve made too many in one commit.

To illustrate this, let’s say we’re building a calculator program, and we have the ability to add buttons to the calculator and define what these buttons do. However, no one has added the actual buttons yet (add, subtract, multiply… y’know, the usual calculator buttons). We’re on a tight deadline, so we agree that you’ll implement the addition button and I’ll implement the subtraction button. You start a branch called addition, and add your button there, and I start a branch called subtraction and do the same. When we’re done, we can merge these changes into the main branch, and our calculator will have both features. Here is a simple image to help you visualize this:

Each dot is a commit, and each color is a separate branch. The blue branch in the center is called the master branch, and this is the main branch of the repository. That is, it’s the branch that contains the latest working changes in the repository, such that someone can run the main branch and have a working version of the software running. You can see how the other two branches “branch” off from the main branch, and in doing so, they are able to make their own changes without interfering with the main branch. Changes in each branch are reviewed and tested separately from the other branches, and they’re only merged into the main branch once the changes are approved and functional.

Note

The main branch in the CMR Superproject repository is called the master branch because traditionally, this was the default name for the primary branch on all Git repositories. Following the Summer 2020 protests in the United States, the Git project and the Software Freedom Conservancy recognized the offensive and harmful nature of this term, which is rooted in the use of antiquated master-slave terminology in computing, and recommended switching to a branch name that is more inclusive. Later that year, GitHub recommended renaming the default branch to main. We also recognize the offensive and exclusionary nature of this term and fully intend to rename this branch appropriately once we figure out a plan to do so without breaking our local and deployment setups.

What is GitHub?#

This section assumes that you have limited prior knowledge of GitHub. If you’re already familiar with it and you already have an account, you can skip to the next section.

We’ve talked a bit about how Git works, but how do we use Git to work together? Enter GitHub. GitHub is an online version control platform that lets us upload our changes to a shared repository. If I make a change on my computer, I can push it to GitHub, and you can pull it down when you need it. GitHub is just a host for our repository, so everything we talked about before - commits, branches, merging - it all still applies.

What makes GitHub special is that it contains a plethora of collaboration tools that we make use of to make sure our changes are well-defined and scrutinized before they end up in the master branch. Here are a couple:

Issues: Issues are tickets that help us organize ideas, tasks, and bugs. We use issues to keep track of our projects, any defects we find when testing rover software, and to keep track of future tasks that we don’t want to forget about. Issues also have a comment section where you can discuss that issue, mention other team members, or reference other issues. Check out the Superproject issues page.
Pull requests: When you’re ready to merge your code from your development branch to the main branch, you can open a pull request. A pull request contains a summary of your code changes, a list of all the commits that were involved, and a list of file changes. Each pull request is based on a single branch, and for that reason, all the work on each feature or bug happens in its own branch. That way, we can keep track of all the discussion and thought that went into each change for future reference. Pull requests also include code reviews, which allow other members of the team to look over your work and either approve your changes or give you feedback on what should be improved. Once a pull request has at least one approving review, it can be merged into the master branch.
Project Boards: Project Boards are where we can keep track of each individual task that needs to get done. Tasks start out in the To Do column and proceed through the In Progress, In Review, In Testing, and finally Done columns. We use project boards to communicate to the rest of our subteam who’s doing what, and where things are in their development cycle.

You can create a GitHub account on github.com and request to be added to the Superproject by sharing your username on Slack.

Setting up Git#

First, check if you have Git installed by opening a terminal and typing git. If you don’t, you can install it by running apt install git on Ubuntu or brew install git on macOS.

Next, you need to tell Git who you are so that it can attribute all of your commits to you. Run git config --global user.name <your full name>, followed by git config --global user.email <the email you used for GitHub>. All set! We used the --global flag, so these settings will be applied to every repository you make commits to.

Once you’ve been added to the Superproject, you can clone the repository to your computer by running git clone https://github.com/CornellMarsRover/Superproject. This will create a folder called “Superproject” in the directory that your terminal is working inside, and it will contain the entire master branch of the Superproject. We’ll talk about creating and switching between branches in a bit.

Branches#

Recall that branches allow different members of the team to work on different code at the same time. Branches are named that way because the changes we make on them “branch off” from a parent branch. The changes that are made to the parent branch do not show up on our new branch unless we manually merge them in; likewise, the changes we make to our new branch don’t show up on the parent branch unless we merge them in. Unless they are intentionally merged together, branches have separate timelines, and that’s why they’re so useful.

Creating a branch#

Navigate to your local Superproject directory by typing cd $CMR_ROOT/Superproject in your terminal. We can create a new branch by typing git checkout -b our-first-branch. That’s it - you’ve created a new branch, and you’re currently on it! You can run git branch to see all of the branches that you’ve checked out to your local repository. You should see two: master and our-first-branch.

Switching between branches#

As we saw before, you can run git branch to see all of the branches that you’ve checked out locally. What if you want to do some work in another branch without merging your current branch first? Have no fear! You can easily switch between different branches, which is another really useful thing about them. First, you have to make sure there aren’t any changes in the branch you’re currently on. You can check to see if there are any outstanding changse that need to be committed by running git status. If you don’t see any, you’re good to go! Just run git checkout example, where “example” is replaced by the name of the branch you want to select. Now, your repository will look like the latest commit in that branch!

Deleting a branch#

Once you’re done working with a particular branch, you can delete it from your computer by running git branch -d example, where “example” is the name of the branch you want to delete.