You have now learned how to:

1. Fork a repo in someone else’s github account to your github account
2. Clone this repo to your local computer
3. Edit copies of that cloned repo locally on your computer
4. add, commit those edits to your git repo locally
5. Push the committed edits back to your fork

In this lesson, you’ll learn how to submit a pull request to suggest that your edits are included in another (the central Earth Lab) repo.

About pull requests

A pull request to another repo is similar to a “push”. However it allows for a few things:

1. It allows you to contribute to another repo without needing administrative privileges to make changes to the repo.
2. It allows others to review your changes and suggest corrections, additions, edits, etc..
3. It allows repo administrators control over what gets added to their project repo.

The ability to suggest changes to ANY repo, without needing administrative privileges is a powerful feature of GitHub. In our case, you do not have privileges to make changes to the earthlab/14ers-git repo. However, you can make as many changes as you want in your fork, and then suggest that Earth Lab incorporate those changes into their repo, using a pull request.

Pull requests in GitHub

This section was adapted from the GitHub Hello World guide. They provide an animated version of these directions.

Pull requests are the heart of collaboration on GitHub. When you open a pull request, you’re proposing your changes and requesting that someone review and pull in your contribution and merge them into their project.

Pull requests show diffs, (differences), of the content between your repo and the repo that you are submitting changes to. The changes, additions, and subtractions are shown in green and red.

Step 1 - Start Pull Request

To begin a pull request (PR), click the pull request button on the main repo page.

Data Tip: You can also click the “Pull requests” tab at the top of the page to submit a pull request. When the pull request page opens, click the “New pull request” button to initiate the PR.

Step 2 - Which repo to update - select your base & head

Next you need to select which repo you wish to update (the base repo) and which repo contains the content that you wish to use to update the base (the head repo). In this example, you want to update earthLab/14ers-git with commits in your fork YOUR-USERNAME/14ers-git.

Head vs Base

• Base: the repo that will be updated, the changes will be added to this repo.
• Head: the repo from which the changes come.

One way to remember this is that the “head” is ahead of the base. So we must add from the head to the base.

When you begin a pull request, the head and base will auto-populate as follows:

• base fork: earthlab/14ers-git
• head fork: YOUR-USERNAME/14ers-git

The above pull request configuration tells Git to update the Earth Lab repo with contents from your repo.

Step 3 - Verify changes

When you compare two repos in a pull request page, GitHub provides an overview of the differences (diffs) between the files. Look over the changes and make sure nothing looks surprising.

Step 4 - Create a pull request

If you are adding new commits to the Earth Lab repo, then the pull request button will be available. Click the green “Create Pull Request” button to submit your pull request.

Step 5 - Describe your pull request using a short title

Give your pull request a title and write a brief description of your changes. When you’re done with your message, click “Create Pull Request”.

Notice the repo name up at the top (in your repo and in screenshot above) When creating the pull request you will be automatically transferred to the base repo. Since your fork was the base (we are updating it), GitHub will transfer you to your github.com fork landing page.

Data Tip: While you can submit a pull request to any (public) repo on GitHub, you can only merge a PR if you own the repo or have appropriate permissions. You don’t have contributor permissions to the Earth Lab repo. Thus the workshop instructors will merge the pull requests as they are submitted during the workshop.

Workflow summary

Syncing repos with pull requests

On GitHub:

• Fork the earthlab/14ers-git repo to your GitHub account.

On your computer:

• Clone the repo to your computer locally (you’ll only do this once)
• Edit any files that you wish to change
  • add and commit your changes to your repository
  • git push your changes up to your fork on GitHub

On GitHub:

• Button: Create New Pull Request
• Set base: earthlab/14ers-git, set head: your fork
• Make sure changes are what you want to sync
• Button: Create Pull Request
• Describe the Pull Request using a succinct title & descriptive comments
• Button: Create Pull Request

Remember that you can only merge the pull request if you have contributor permissions to the repo!

Data Tip: Are you a Windows user and are having a hard time copying the URL into shell? You can copy and paste in the shell environment after you have the feature turned on. Right click on your bash shell window (at the top) and select “properties”. Make sure “quick edit” is checked. You should now be able to copy and paste within the bash environment.

What’s A Merge Conflict?

A merge conflict occurs when two users edit the same part of a file at the same time. Git cannot automatically determine which edit should be in the most current copy. Hence the conflict.