GitHub Desktop Guide

Author

Prof Kelling

Getting setup with GitHub Desktop

You should first install the Github Desktop application. I use this app for my research because I can really easily see what changes I’ve made between pushes. I find the user interface to be very user-friendly.

Make sure you have followed steps 1-4 of Part 1: Installing and authenticating for Github Desktop. This will connect your Github account with the files on your local computer.

Individual research projects

Cloning a repository

Go to the GitHub page (hosted on https://github.com/) and find your desired repo, such as https://github.com/ckelling/github_workshop. For today’s workshop at Washington State, you should fork this repository so you have your own personal copy.
Now, find your own personal copy of this repository on GitHub by navigating to your account. Click the green “Code” button. Click “Open with Github Desktop”.
If prompted to “Allow this site to open… with GitHubDesktop?” click Open Link.
In the Github Desktop window do not change the repository URL (the first argument). Change the local path to be within a folder that you’d like to use for today’s materials. Then click Clone.

You should now be able to see all files related to this repository in a folder on your local computer. Navigate to this folder in RStudio to edit files.

I would suggest also creating an R Project within your directory for each repository, if one is not already present. This will make your life easier in terms of handling directories.

Working on your research/exercise

A folder should now be available for this repository on your local computer, which will allow you to start collaborating on this project, assuming you have added collaborators (we won’t have time for that today). You can navigate to this repository in your File Explorer on your computer to find your files. Click on whatever file you want to edit (the .Rmd file for today) and edit away.

Commits

After you make changes to the files, commit them. What are commits you ask? Commits are essentially taking a snapshot of your projects. Commits save this snapshot to your local version of Git (located on your hard drive or the maize server). For example, if I make changes to a code so that it prints “Hello world”, and then commit them with an informative message, I can look at the history of my commits and view the code that I wrote at that time. If I made some more changes to the function that resulted in an error, I could go back to the commit where the code was originally working. This prevents you from creating several versions of your work (test-v1, test-v2, …) or from trying to remember what your code originally looked like.

You can make commits in the Github Desktop interface. Highlighted in yellow you will see the name of the repository.

In blue is the name of the file you are editing. In pink is the space where you will add your commit message, for example “Added a comment to start the script.” You can see what change you’ve made since your most recent commit on the right hand side in orange. In this case, I’ve added one line, shown in a light green highlight. If you have deleted code, the lines will show up here in light red. You can have one commit message be associated with edits to more than one file.

After you’ve typed your commit message, click Commit to main below the typed commit message.

After you’ve done this, you should be able to click “Push Origin”, as shown in the image below, highlighted in yellow.

Two things about committing.

You should commit somewhat frequently. At minimum, commit each time you’ve made a major functional change.
Leave informative commit messages. “Added stuff” will not help you if you’re looking at your commit history in a year. A message like “Added initial version of hello-world function” will be more useful.

Pushing changes to Github

At some point you’ll want to get the updated version of the files back onto GitHub, potentially so that collaborators can help you with your code. If you are ready to push, you can again click on the “Push Origin” button, as shown above.

Setting up collaborative work

Collaborative Github repos are pretty similar to individual repos.

Creating a group repo

Go to the desired GitHub repository. Add collaborators to the repo using “Settings” and “Collaborators” on the left hand side.

Working with collaborative repos

For group projects, I suggest that only one person at a time edit the .Rmd file to avoid merge conflicts!

When you are working together on a Github project, you should commit and push your modifications frequently. You will also need to frequently pull updates from Github down to your local version of RStudio. These updates are changes that your collaborators have made since your last pull. To pull in changes, click the “Fetch Origin” button (which should be shown if you have nothing to push). After clicking “Fetch Origin”, you should be prompted to “Pull Origin” with the number of commits that have been made next to this prompt. Click this “Pull Origin” button.

If you get an error about conflict after pulling or pushing, don’t freak out! This can happen if you edit a file (usually an .Rmd or .R file) in a location that was also changed by a collaborator. When this happens you should attempt to fix the merge conflict. One simple way to do this is to undo your conflicting commit (in the bottom left of Github Desktop) but be sure to copy/paste your changes somewhere, as undoing the commit will revert the file back to a previous form. Take a look at this resource site and try to fix the merge conflict in Rstudio.

Additional resources

Acknowledgements

Some of this content in this guide was adapted from Adam Loy’s guide and https://github.com/jfiksel/github-classroom-for-students and is licensed under the CC BY-NC 3.0 Creative Commons License.