If you haven’t set up git and GitHub yet do that first. If you’ve done this, you now know why you should use git and Github, but how do you actually start using all these things you just got setup?

Setting up a new research project

If you’re starting a new research project you’ll want to set up a GitHub repository (repo) for it from the get go. Doing it from the start is ideal, but if you’re moving an existing project to GitHub see the next section.

  1. Make the repo on GitHub

    1. Go to the WWS GitHub organization ((https://github.com/orgs/wildfire-water-security/repositories).

    2. Click the green ‘New repository’ button in the right corner.

    3. Give your repo a name. It should take the form WWS-Node#-ProjectCode-ProjectKeywords where:

      • # is the node number
      • ProjectCode is a short (<5 letter) acronym for the project
      • ProjectKeywords describe what the project is about in a few words

    1. Give the repo a description to provide some more information about the project.

    2. Set the repo as public or private. Private repos are still viewable by the entire WWS organization.

    3. Click the box to initialize the README file. This will be the landing page for the repo where you can store links for important files, share important information, and provide contact information for the project. We’ll discuss more on that in another tutorial.

    4. If you’d like you can add a .gitignore or a license, but if you’re not sure, skip these you can always add them later.

    5. Create the repository by clicking the green button on the bottom.

  2. Now that your project exists on GitHub, lets get it on your local computer. To do this, go to GitHub desktop got to file -> clone repository (CRTL + SHIFT + O).

    This will open up a box, where you can select the GitHub repository you want to put on your computer, and where you want those files located.

  3. Now if you go to the location where you specified as the local path above, you should see a folder that looks like this:

    Store all your project files here to take advantage of all that GitHub has to offer. We’ll talk about maintaining a repo in the next tutorial.

Adding an Existing Project to GitHub

If you already have a folder for an existing research project, all your stuff is there, but now you want it on GitHub so you can take advantage of the version control and collaborative features. Here’s how to do that:

  1. It’s recommended that you turn your folder into an R project if you haven’t already done so.

    Why? R projects makes data more shareable: data stored in project is easily findable with relative file paths (meaning that the path will work even if the project gets moved to different places). To do that run the following code:

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

#the location you of your project folder
local_dir <- "file path to project folder"

#create a project from the directory
usethis::create_project(local_dir)
  1. Once you create your project, the project should open up in R Studio. In the project, run the following code to initialize git to start version tracking. Use the following code to do that:
usethis::use_git()

  1. Next you’ll want to go to GitHub desktop. Go to file -> add local repository (CTRL+O), navigate to your project directory and hit add repository.

    It will link this folder to your GitHub desktop. On the right side you should all the files in your project folder ready to commit. At this point your files are linked to git, but they’re not stored on GitHub.

  2. To link your repository to GitHub so it’s backed up online, you’ll want to publish the repository by clicking the button in the right corner. It’ll prompt you to give the repository a name, it should take the form WWS-Node#-ProjectCode-ProjectKeywords where:

    • # is the node number
    • ProjectCode is a short (<5 letter) acronym for the project
    • ProjectKeywords describe what the project is about in a few words

    Then hit the blue “Publish repository” button.

  1. We now need to save our first set of files to the repository (a commit) and save it GitHub (a push). This will save a copy of all your files to Github.

    1. GitHub desktop will automatically select all your files to include in the initial commit. Add a commit comment to share your changes to the repo, for the first time, “initial commit” is often used. Then hit the blue Commit button. You will no longer see your files on the right side, because it will only show files that have been changed here.

    1. Lastly, we need to upload or push these changes to GitHub so they’re backed up online. Do this by hitting the “Publish Branch” button on the top right.

  2. Now all your files are backed up, version controlled, and accessible by the whole project! You can see you files on the repository on GitHub online.

Sources and Further Reading