5. Contributing to an existing GitHub project

In this section, we will cover topics that will allow you to use the full scope of version control's strengths, especially when working with teams. We'll start with cloning and forking existing projects.

Cloning and Forking existing repositories

There are several ways to copy an existing project on GitHub for us to play with the source code. One brute force method is to simply download the repository as a folder. Since we're aiming for more elegant (and honestly cooler looking) methods for maintaing projects, we will consider two primary ways of downloading source code:cloning and forking.

Cloning

A repository is a container with your files that is stored in a remote location. You can clone your repository to make a local copy on your computer. This lets you work on files both online and offline, while offering the ability to sync changes using Git.

Unless you are a collaborator on the project, you can't pull down changes from the remote repository, and you can't send changes. Further, other elements, such as Issues, Pull Requests, and other project management elements will not be shown to you (more on these later).

The takeaway is that you should clone a repository if you need to make a copy of the project without syncing between the remote and your local copy.

To clone a project, you need to simply copy and paste the url (use the HTTPS protocol without setting up SSH for now) to the project, and type in the following command in the terminal:

git clone <url>

Forking

Forking a repository makes a copy of all the files and code in a fresh repository under your GitHub profile. This method creates a link between your copy of the project and the parent repository, allowing you to propose changes using Pull Requests.

**The takeaway is that you should fork a repository if you are actively collaborating in the same project`.

Using the GitHub website, you can easily fork a repo by pressing the Fork button on the top right-hand side of any repository. This will add the repository to your user profile. To download a local version of the project, you can clone the repository (now under your profile).

If you want to keep your clone synced to both your repo and the original repo, we need to add the remote url to the original repo.

In the command line, move into the existing project, where we'll set the remote url to point to the original project.

# First clone the project. To keep this realistic, you can fork the sriram-lab/github repository and clone it to your computer:
git clone https://github.com/sriram-lab/github.git

# Next we need to move into the local copy
cd github

# Let's check the remote url that this repo currently points to:
git remote -v

# The output will look something like this:
> origin    https://github.com/YOUR_USERNAME/github.git (fetch)
> origin    https://github.com/YOUR_USERNAME/github.git (push)

# Let's now say we want to point to the original project, either to sync with the latest version of the code or to send our own changes to the owner. To do that, we need to add a remote to this repo. Let's call the new remote `sriram-lab` and point back to the sriram-lab GitHub repo:
git remote add sriram-lab https://github.com/sriram-lab/github.git

You can check your remotes, and you will find that the sriram-lab remote is added. Next, let's go over syncing with this other remote.

Syncing a forked repository and handling multiple branches

While we created remote variable (sriram-lab) that points to that remote repository, we don't actually have all the data from that remote. To sync and download data from the original remote, we need to do git fetch, which downloads data from the remote without integrating it to your current version of the files.

Recall that branches are basically containers of the repo. Let's see what branches are in our local repo and let's create a new branch for you:

git branch

# should return master
> master

# To create your own branch in this repo, type in the following:
git checkout -b <insert_your_branchName>

# This should create your own branch, which you can checkout:
git branch

> master
> <your_branchName>

Now let's get the latest version of the remote repo, and let's just get everything to be thorough:

git fetch sriram-lab --all

You will notice that there are some new branches that exist with the remote. You have your own sets of branches, and the remote repository has its own set of branches. If you want to checkout another branch (ie test), you can do the following:

git checkout sriram-lab/test

This specifically gets the existing test branch from the sriram-lab repo.

Finally, let's merge changes that may exist in the sriram-lab/master branch to our local master branch.

# First move to the local master branch
git checkout master

# Now merge with the sriram-lab/master branch
git merge sriram-lab/master

Sweet! We've covered how to download remote repos using git clone, keep remote repositories from existing projects up-to-date using git fetch, and making new containers called branches using git checkout.

In the next tutorial, we will cover how to propose changes to the existing code within our own branch using Pull Requests.

Proposing changes using Pull Requests

Now that we know how to contribute to a specific branch, what happens when we want to share a final project that is closer to publication? We need to submit our changes to the master branch. But we must also realize that other people may contributing to the same project, so the question is, is there a systematic way to introduce changes that will not break other people's software? There is, and that is using pull requests.

Submitting a pull request