Learning Goals

  1. Perform basic Git workflows using GitHub Desktop.

It’s time to start learning how to use Git and GitHub! In the following activities we’re going to learn how to:

Activity 1: Clone a Repository

  1. In GitHub Desktop: File → Clone repository (CTRL + SHIFT + O)

  2. Choose the following repo to clone: WWS-TEST-example-repo

  3. Set the local path to C:\Users\your username\Documents

  4. Hit Clone

  5. Find the repository you just cloned in file explorer. Check out the folders and files in the repository.

Activity 2: Create a Branch

Find a partner.

Partner 1:

  • Create a new repository branch with the name: your name-their name

    • Go to GitHub Desktop

    • Click the Current branch button

    • Click New Branch

  • Publish the branch so your partner can see the branch by hitting the Publish branch button in the top right.

Partner 2:

  • Pull the repository using the Pull origin button in the top right of GitHub desktop to get the new branch.

  • Check out the repository by hitting the middle Current branch button in GitHub Desktop and selecting the one with your names.

This is where you’ll be working for the rest of the Github Activities. The changes you make to this branch will not affect anyone else’s files unless they are also on this branch.

Activity 3: Turn the Repository in an R Project

R Projects make your data/code portable and keep file paths consistent across computers.

  1. Open up code/example-script1.R

    • Edit line 3 with your username then run lines 4-5 to get the file path to the .csv file.

    • Notice this is a long file path to have to type, and is unique to the user so this isn’t ideal for sharing code across the project.

  2. Let’s fix this by turning the repo into an R project by running the following code in the R console:

     #install.package("usethis") #only need to run the first time 
 library(usethis)

 #the location you of your project folder 
    repo <- file.path(fs::path_home(), "Documents/WWS-Node1-TEST-example-repo/")

 #create an R project from the directory
    usethis::create_project(repo)

  3. The new R project should open up in a new R window. In this project go back to code/example-script1.R and change the file path to data/example-csv.csv. Run the rest of the lines. What happens?

HINT: In the project on the lower right of R Studio, you will see all your files in the repository, you can use this to open up example-code1.R.

Because the repository is now an R project, it will automatically treat WWS-TEST-example-repo as the working directory and base all file paths from here. Meaning that the file paths will work for anyone who clones the repository.

Activity 4: Add a .gitignore File

We changed some files, let’s go see the changes in GitHub Desktop. On the left it shows the files that have been added, changed, or removed in your repo. You should see four:

  • .gitignore
  • example-code1.R
  • example-csv.csv
  • WWS-TEST-example-repo.Rproj

HINT: If you don’t see example-code1.R, make sure the script is saved.

What is the .gitignore file? It tells Git which files/folders not to track.

  1. Open up the file via file explorer, right now it only has one line:

    • .Rproj.user (used to store project-specific temporary files)

  2. There are many of other temporary files we may not want to include in our repository (ie. lock files for Office files). The easiest way to ignore all of these files is to use gitignore.io.

    • Open the link, enter: MicrosoftOffice, R, Windows, and Mac OS and hit create
    • Copy all the text and paste into the .gitignore file. Save the file.

Activity 5: Committing Changes

  1. We’ve now made some changes to the files in this project, will others see them? Go check out the project on GitHub, do you see the changes you’ve made?

    • No, we need commit and push those changes first!

  2. Go back to the project in GitHub Desktop, on the left side you can see the files that have been changed. Select all the files.

  3. Add a commit message:

    • Summary: GitHub Workshop
    • Description:
      • creating R project
      • changing file path to relative to be be more collaborative
      • ignoring nuisance files from R, Office, Windows, and Mac

  4. Commit your changes.

  5. Go back to the repository on GitHub, do you see your changes?

Activity 6: Pushing Changes

Your changes are tracked locally by Git after you make a commit, but in order to share your commits with others, you need to push those changes to the remote (GitHub).

Partner 1:

  1. In GitHub Desktop, push the Push origin button in the upper right to send your changes to GitHub.

  2. Go back to the repo on GitHub, do you see your changes now?

Partner 2:

  1. Without pulling your partner’s changes, push your changes.

  2. You’ll get a warning about needing to fetch changes, go ahead and click Fetch, then Pull origin. This will attempt to reconcile your changes with the changes you just pulled.

Uh Oh! We’ve got a merge conflict! This means that Git has two different versions of the same file and it doesn’t know which one to keep.

This is why it’s always best to pull changes right before you push changes, to avoid merge conflicts. We’ll practice that again later.

Activity 7: Merge Conflicts

When you have a merge conflict you’ll have to manually tell Git which version of the file you want to keep. You can do that in two ways. We’ll explore using both ways:

  1. Merge in GitHub Desktop:

    • GitHub Desktop will let you keep a specific version.
      • Use the modified files from <branch>: keep the version on the GitHub branch
      • Use the modified file: keep the version in your commit.
    • Choose the local version for the .Rproj file.

  2. Merge Manually:

    • GitHub Desktop also gives you the option to open in the default program, click that option on the .csv file.

    • Take a look at the file, take note of the conflict markers, which show the conflicting file lines:

      <<<<<<< HEAD
      your local version
      =======
      remote version
      >>>>>>> branch-name

    • To resolve the conflict we can choose to delete the lines for one version, or keep both. Lets keep both, so we’ll just remove the conflict markers (above) and save the file.

  3. Go back to GitHub Desktop, you should now see that your merge conflicts are all resolved, so now we can continue the merge:

  4. Check out the history of your commits, you should now see your initial commit and a commit from merging the commits.

  5. Push both to GitHub.

Activity 8: Working with Binary Files

GitHub was originally designed for coding and works really well with file that can be opened in text editor like .txt, .csv, .R, .py. However, in our project you may find yourself working with binary files (i.e. .docx, .pdf, .xlsx).

Let’s see how Git treats these different kinds of files by making some changes:

HINT: We’re about to make changes to files in our repo, pull the current version to avoid merge conflicts!

  1. Open up data/example-code2.R in RStudio.

  2. In your merge conflict, we decided to keep both sets of data, lets use those as groups in our plot by adding the following code after line 5:

      data$X <- c(rep("Group 1", 4), rep("Group 2", 4))

  3. Then edit line 7 (previously line 6) to look like this:

      ggplot(data, aes(x=site, y=value, color=X)) + geom_point() + geom_line()

  4. Run the whole code to create a new figure 1. Make sure to save your changes to data/example-code2.R.

  5. Next, open methods/example-SOP.docx, on a new line type: Written by <your name>. Then close and save the file.

  6. Open up GitHub Desktop to look at the how it displays the changes you made. On the left you should see three changed files, click on each and see what is displayed on the right.

    • example-code2.R: notice that it shows the line by line changes that were made?

      • Green and + indicate a line was added

      • Red and - indicate a line was removed

    • figure1.png: notice that it shows what the previous figure looked like and what it looks like now. At the top you can also choose additional options to compare the two figures.

    • example-SOP.docx: we just get a message that the binary file has changed. Git doesn’t natively know how to reconcile changes in binary files, making them more challenging to work on collaboratively through Git.

      IMPORTANT: Merge conflicts are also more challenging with binary files. If you choose to keep the remote version during a conflict, you’ll lose your local work, so merge carefully!

Activity 9: Stashing Changes

Great, we’ve made new changes to our files, so let’s share them again.

Partner 2:

  1. Commit your changes, practice writing a descriptive commit message

  2. In GitHub Desktop, push the Push origin button in the upper right to send your changes to GitHub.

Partner 1:

  1. We’re going to use best practices and pull the changes from the branch before we make a commit so we have the most recent version.

  2. Uh Oh! We get an error, that pulling those changes will overwrite some of our changes.

  3. It gives us the option to stash our changes and continue with the pull. This means that it will temporarily save your current changes in a separate location so we can pull without a merge conflict. Click to stash your changes.

  4. Great, now we have the most recent copy of the repo, but where did our changes go? Notice right above the commit message, there’s a bar that says stashed changes. Clicking this will show all those changes you made, and you can click restore to bring them back to your changes.

  5. Alright, now the copies of our files are up to date with the repo, and we’ve still got our changes. Now we can commit and push to GitHub without merge conflicts!

    • When you do this, it’s a good idea to check out the new commit messages and file changes to make sure you don’t write over others work.

    • Git will combine your work on non-binary file, but when you push, your version of the binary files will be the one on the repo.


IMPORTANT: These are the main GitHub workflows you should use. Other Git commands exist, but using them without guidance can cause problems for the whole repository. If you’re unsure or run into an issue, stop and ask Katie, we’ll work through it together.