Git excited: How GitHub makes group projects easier

So you’re about to start your first group coding project — congratulations! When you collaborate with other software engineers, you can all accomplish more.

It’s exciting to work on a team, but it can also be challenging to combine your code with your teammates’. Fortunately, with a little practice, Git and GitHub makes it easy to keep everyone’s code in sync.

What are Git and GitHub?

If you’ve used these tools before for personal projects, feel free to skip ahead to the next section. If not, here’s a quick rundown:

Git logo from Wikimedia Commons

Git is a free version control system that help you keep your coding projects organized. As you save changes to a software project, Git keeps a record of those changes. I’ll be using Git commands throughout this post, so if you’re not familiar with them yet, you may want to learn the basics of Git before reading on. One good way to start is to check out gTerm, a free tool I built with my teammates at Codesmith.

A shameless plug for gTerm

GitHub is a popular website that makes it easy to back up your Git projects online and collaborate with other developers. There are many ways to use GitHub for group projects — here’s the workflow we use at Codesmith.

Create an organization

Once all your teammates have created free GitHub accounts, you can keep your team organized by creating an organization on GitHub. (You’ll be asked to provide a billing email address, but as long as you’re OK with making your projects open source rather than private, creating an organization is free.) You’ll then be able to store your team’s project on your organization page — we’ll see how shortly. That way, everyone will know where to go to find the “official” version.

Pair-program a project skeleton

Once you and your teammates have decided what you want to build, it’s time to start coding! The first thing you’ll want to do is create a basic skeleton for your project, all working together on one computer.

For this example, let’s say your team is all working on your Mac to set up a simple website. The skeleton might be as simple as a folder with three starter files inside it to hold your HTML, CSS, and JavaScript:

Set up a shared repository

Once you’ve finished your project skeleton, you can initialize your Git repository and add it to GitHub. For now, your team should all continue working on one computer — your Mac. Here are the steps you’ll follow, adapted from GitHub’s directions. (They’ll be a bit different if you’re using a Windows or Linux machine.)

  • Log in to your GitHub account.
  • From your organization page on GitHub, create a new repository without a README, license, or gitignore file. (You can add these later.)
  • Open Terminal (or gTerm) on your computer and navigate to your project folder.
  • Run the following commands to initialize the local project folder (i.e., the project folder on your machine) as a Git repository and commit the files inside it.
git init
git add .
git commit -m "First commit"
  • Back on GitHub.com, copy the clone URL for your new remote repository. It should look something like this: https://github.com/TeamName/ProjectName.git (should end with .git).
  • Back in Terminal, run the following commands to link your local repo to the team’s remote repo and to push your changes from the local to the remote (replacing URL with the URL you just copied).
git remote add upstream URL
git push upstream master

Now you have one “official” copy of your project on your organization’s GitHub page. The next step is to create a copy for each team member.

Set up repositories for individual team members

For this stage, you and your teammates will split up and work on your individual computers.

Since you already have a local copy of the project repo on your Mac, the steps you’ll follow will be slightly different from the steps for your teammates.

Here’s what you’ll do on your machine. (Again, the instructions will be a bit different for folks not using Macs.)

  • Back on GitHub.com, navigate to your organization’s project page. The URL should look something like this: https://github.com/TeamName/ProjectName (no .git at the end).
  • Click the “Fork” button and select your GitHub account to create a new remote repository just for you.
  • Copy the clone URL for your new remote repository. It should look something like this: https://github.com/YourName/ProjectName.git.
  • Back in Terminal, run the following commands to link your local repo to your remote repo and to push the changes from your local to your remote (again, replacing URL with the URL on your clipboard):
git remote add origin URL
git push origin master
  • Run the following command to be sure you’ve set up your remotes correctly.
git remote -v

This will show you a list of the remote repositories linked to your local repository. The URL for the origin should contain your GitHub name, while the URL for the upstream should contain your team’s name. Conceptually, the upstream is the official copy of the project, which should stay clean, whereas the origin is your personal copy of the project, where you can make changes and experiment without polluting the official copy. We’ll dive into this idea more in later sections.

Here’s what each of your teammates will do:

  • Log in to GitHub.com and navigate to your organization’s project page.
  • Click the “Fork” button and select their GitHub account to create their own fork (a repo just for them).
  • Copy the the clone URL for their new fork. (It should be something like https://github.com/TheirName/ProjectName.git.)
  • In Terminal, run the following command to clone their fork onto their machine. In addition to creating a local copy of the project, this command will link their local repo to their remote repo, which will be their origin.
git clone URL
  • On GitHub.com, navigate back to the organization’s fork and copy the clone URL (something like https://github.com/TeamName/ProjectName.git).
  • Back in Terminal, navigate into the project directory, and run the following command to link their local repo to the organization’s remote repo, which will be their upstream.
git add remote upstream URL
  • Run the following command to check that they’ve set up their remotes correctly.
git remote -v

Phew — it took some time to set up all our repos, but now that that’s finished, we can move on to the fun part: actually building stuff! Once you and your teammates have decided who’ll work on which pieces of the project, you can get back to coding.

Start the build cycle

Branch out

Adding new features to your project is a cyclical process, and the first step each time is to create a new branch on your local repo. That way, you can keep your local’s master branch clean and in sync with the official version of the project on your upstream remote.

Let’s say you’re going to create a navigation bar for your project. You can create a new branch and check it out by running this command in Terminal:

git checkout -b navigation

As you work, add and commit your changes just like you would for a solo project. You’ll also want to push them to GitHub periodically:

git push origin navigation

In this case, you’re pushing to the navigation branch of your origin remote. You don’t want to push to your upstream remote, because that’s the official copy that everyone on your team relies on.

When you think your new feature is finished and should be incorporated into the official version of the project, continue with the next phase of the build cycle.

Get your branch ready for your teammates to review it

Before you ask your teammates to review your code, you’ll want to make sure your branch incorporates the latest changes elsewhere in the project. Here’s how:

  • Commit your latest changes. (You should still be on the navigation branch.)
  • Open Terminal and navigate to your project directory.
  • Run the following commands to switch to your master branch and to bring the master branch of your local repo in sync with the master branch of the upstream repo.
git checkout master
git pull upstream master
  • If there are any merge conflicts, resolve them and commit again.
  • Run the following commands to switch back to your navigation branch and to merge the changes from your master branch into your navigation branch:
git checkout navigation
git merge master
  • Again, if there are any merge conflicts, resolve them and commit once more.
  • Push to the navigation branch of your origin remote:
git push origin navigation

Submit a pull request

Now that the latest version of your code is on GitHub, you can ask your teammates to review it and incorporate it into the upstream repo. Fortunately, you can do this all through GitHub:

  • On GitHub.com, navigate to your fork. (The URL should be something like https://github.com/YourName/ProjectName.git.)
  • You should see a note about your recently pushed branches. If so , click “Compare and pull request.” Otherwise, “New pull request” will also work.
  • Make sure the four settings for the pull request are correct.
  1. The base fork should be your upstream (something like TeamName/ProjectName).
  2. The base should be master.
  3. The head fork should be your origin (something like YourName/ProjectName).
  4. The compare should be the branch you were just working on (in this case, navigation).
  • Add a note for your team and click “Create pull request.”

At this point, one of your teammates should review your code to make sure everything is working properly. (This is much easier to do if you and your teammates have been writing tests for each feature you add — but that’s a topic for another post.) If it is, they’ll approve your pull request, incorporating your new feature into the master branch of the upstream repo so that everyone can access it.

Sync your repos

Now the “official” version of the project includes your new feature, but the versions on your personal fork do not. Here’s how to get back in sync:

  • Open Terminal and navigate to your project directory.
  • Run the following commands to switch back to your master branch and to incorporate the changes from the upstream repo into your local repo and your origin repo:
git checkout master
git pull upstream master
git push origin master

Repeat!

When you’re ready to start a new feature, you can start the whole process again on a new branch. With practice, the cycle will become second nature. They key thing to remember is that you’re always pushing to the origin remote (your personal copy) and pulling from the upstream remote (the official one).

You did it!

You conquered your team project! I hope you and your team find this guide helpful and that you’re able to adapt it to your individual needs. When you do, I’d love to hear about your GitHub process. And in the meantime, happy coding!