NEON EDUCATION bio photo

NEON EDUCATION

Devoted to open data and open source in science and education.

View All Tutorials

This tutorial is a part of a series!

Click below to view all lessons in the series!

Tags

R programming (56)
Hierarchical Data Formats (HDF5) (15)
Spatial Data & GIS (22)
LiDAR (10)
Raster Data (14)
Remote Sensing (25)
Data Visualization (4)
Hyperspectral Remote Sensing (18)
Time Series (17)
Phenology (8)
Vector Data (6)
Metadata (1)
Git & GitHub (7)
(1) (1) (14) (1) (1) (1) (1)

Tutorial by R Package

dplyr (9)
ggplot2 (18)
h5py (2)
lubridate (time series) (7)
maps (1)
maptools (1)
plyr (2)
raster (26)
rasterVis (raster time series) (3)
rgdal (GIS) (24)
rgeos (2)
rhdf5 (11)
sp (5)
scales (4)
gridExtra (4)
ggtheme (0)
grid (2)
reshape2 (3)
plotly (5)

View ALL Tutorial Series




Twitter Youtube Github


Blog.Roll

R Bloggers

Overview

This tutorial covers how to set up a Central Repo as a remote to your local repo in order to update your local fork with updates. You want to do this every time before starting new edits in your local repo.

Learning Objectives

At the end of this activity, you will be able to:

  • Explain why it is important to update a local repo before beginning edits.
  • Update your local repository from a remote (upstream) central repo.

Additional Resources:

We now have done the following:

  1. We’ve forked (made an individual copy of) the NEONScience/DI-NEON-participants repo to our github.com account.
  2. We’ve cloned the forked repo - making a copy of it on our local computers.
  3. We’ve added files and content to our local copy of the repo and committed the changes.
  4. We’ve pushed those changes back up to our forked repo on github.com.
  5. We’ve completed a Pull Request to update the central repository with our changes.

Once you’re all setup to work on your project, you won’t need to repeat the fork and clone steps. But you do want to update your local repository with any changes other’s may have added to the central repository. How do we do this?

We will do this by directly pulling the updates from the central repo to our local repo by setting up the local repo as a “remote”. A “remote” repo is any repo which is not the repo that you are currently working in.

LEFT: You will fork and clone a repo only once . RIGHT: After that, you will update your fork from the central repository by setting it up as a remote and pulling from it with git pull . Source: National Ecological Observatory Network (NEON)

Update, then Work

Once you’ve established working in your repo, you should follow these steps when starting to work each time in the repo:

  1. Update your local repo from the central repo (git pull upstream master).
  2. Make edits, save, git add, and git commit all in your local repo.
  3. Push changes from local repo to your fork on github.com (git push origin master)
  4. Update the central repo from your fork (Pull Request)
  5. Repeat.

Notice that we’ve already learned how to do steps 2-4, now we are completing the circle by learning to update our local repo directly with any changes from the central repo.

The order of steps above is important as it ensures that you incorporate any changes that have been made to the NEON central repository into your forked & local repos prior to adding changes to the central repo. If you do not sync in this order, you are at greater risk of creating a merge conflict.

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 decide which edit was first and which was last, and therefore which edit should be in the most current copy. Hence the conflict.

Merge conflicts occur when the same part of a script or document has been changed simultaneously and Git can’t determine should be applied. Source: Atlassian

Set up Upstream Remote

We want to directly update our local repo with any changes made in the central repo prior to starting our next edits or additions. To do this we need to set up the central repository as an upstream remote for our repo.

Step 1: Get Central Repository URL

First, we need the URL of the central repository. Navigate to the central repository in GitHub NEONScience/DI-NEON-participants. Select the green Clone or Download button (just like we did when we cloned the repo) to copy the URL of the repo.

Step 2: Add the Remote

Second, we need to connect the upstream remote – the central repository to our local repo.

Make sure you are still in you local repository in bash

First, navigate to the desired directory.

$ cd ~/Documents/GitHub/DI-NEON-participants

and then type:

$ git remote add upstream https://github.com/NEONScience/DI-NEON-participants.git

Here you are identifying that is is a git command with git and then that you are adding an upstream remote with the given URL.

Step 3: Update Local Repo

Use git pull to sync your local repo with the forked GitHub.com repo.

Second, update local repo using git pull with the added directions of upstream indicating the central repository and master specifying which branch you are pulling down (remember, branches are a great tool to look into once you’re comfortable with Git and GitHub, but we aren’t going to focus on them. Just use master).

$ git pull upstream master

remote: Counting objects: 25, done.
remote: Compressing objects: 100% (15/15), done.
remote: Total 25 (delta 16), reused 19 (delta 10), pack-reused 0
Unpacking objects: 100% (25/25), done.
From https://github.com/NEONScience/DI-NEON-participants
    74d9b7b..463e6f0  master   -> origin/master
Auto-merging _posts/institute-materials/example.md

Understand the output: The output will change with every update, several things to look for in the output:

  • remote: …: tells you how many items have changed.
  • From https:URL: which remote repository is data being pulled from. We set up the central repository as the remote but it can be lots of other repos too.
  • Section with + and - : this visually shows you which documents are updated and the types of edits (additions/deletions) that were made.

Now that you’ve synced your local repo, let’s check the status of the repo.

$ git status

Step 4: Complete the Cycle

Now you are set up with the additions, you will need to add and commit those changes. Once you’ve done that, you can push the changes back up to your fork on github.com.

$ git push origin master

Now your commits are added to your forked repo on github.com and you’re ready to repeat the loop with a Pull Request.

Workflow Summary

Syncing Central Repo with Local Repo

Setting It Up (only do this the initial time)

  • Find & copy Central Repo URL
  • git remote add upstream https://github.com/NEONScience/DI-NEON-participants.git

After Initial Set Up

  • Update your Local Repo & Push Changes
    • git pull upstream master - pull down any changes and sync the local repo with the central repo
    • make changes, git add and git commit
    • git push origin master - push your changes up to your fork
    • Repeat

Got questions? No problem. Leave your question in the comment box below. It’s likely some of your colleagues have the same question, too! And also likely someone else knows the answer.