1 Introduction to GitHub

GitHub is a hosting service (like a Cloud) that allows version-control and source-code management (i.e., tracking changes on files). GitHub is similar to Google Docs with the ability to collaborate on single documents and projects. Though, GitHub has more strucuture for collaborations on files, which are discussed here.

Requirements to use:

GitHub Account - This is your account to use the “cloud”

RStudio - RStudio can directly integrate with GitHub. This allows you to make local changes (i.e., changes on your computer) to a file and add them to the GitHub cloud

GitHub Desktop - This allows you to integrate with GitHib for files outside of R. This is not required if you are only using R and GitHub.

2 GitHub Functions

Repository: A repository is the most basic element of GitHub. They’re easiest to imagine as a project’s folder. A repository contains all of the project files (including documentation), and stores each file’s revision history. Repositories can have multiple collaborators and can be either public or private.

Committing Similar to saving a file that’s been edited, a commit records changes to one or more files in your branch. Git assigns each commit a unique ID, called a SHA or hash

Pushing: To push means to send your committed changes to a remote repository on GitHub.com. For instance, if you change something locally, you can push those changes so that others may access them.

Pulling/Pull Requests: Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.

3 Creating R Projects in GitHub

3.1 How to publish files directly from RMarkdown to Github

In order to publish files from RMarkdown to GitHub you must have (1) a GitHub repository for the files to be stored in, and (2) RStudio linked to GitHub via RProject

3.1.1 Creating a Repository on GitHub

A. In the upper-right corner of any page on your GitHub, use the drop-down menu, and select New repository. Name your repository as desired (e.g., pupil-project). Describe it as needed (e.g., this project will optimize our pupilometry pipeline). Choose your visibility (Public or Private).

B. Choose “Initialize this repository with a README. Click”Create repository"

C. Now that your repository has been created. Select it from your GitHub homepage. Choose the “Code” dropdown menu and copy the HTTPS URL (we need this to link the GitHub repository to our RStudio Project.)

Green box, top right to see URL code

3.1.2 Linking RStudio to GitHub via RProject

A. In RStudio select File > New Project > Version Control > Git. In the “Repository URL” paste the URL of your desired GitHub repository. In the “Project Directory Name:” specify the Project Name you would like. In the “Create Project as Subdirectory of:” select the subfolder of choice.

B. Click “Create Project”. This will create (1) a folder on your computer with the Project name, (2) a local Git Repository linked to your remote Git repository, and an RStudio Project.

This will create a Git tab

4 Managing projects in GitHub

4.1 How to share and edit within repositories

A. Editing the local file tied to the repository

This simply means that you can make changes to a local file, commit those changes, and push them to the main file on the GitHub repository. This is the most direct way to make edits. This will be the most common case when you are working on something independently.

B. Creating a branch

4.1.0.1 Branching

Creating a branch means that you create a parallel version of the repository that is contained within the master repository (i.e., main branch). Branches are used to isolate development work without affecting the main brain (or other branches) in the repository.

This allows you to make all sorts of changes and modifications to files in a repository without constantly adding edits to be approved in the master repository. When you finsish editing your branch, you can merge it into the master branch using a pull request. This is common when a person is making many changes to one or a few files in a repository.

4.1.0.2 How to create a branch:

A. Navigate to the main page of your chosen repository and select “master” dropdown

Grey box, top left to see branches

B. Type in unique name for your branch and select “create branch”

4.1.0.3 How to edit within a branch and push to the main branch

A. Select the Git dropdown in RStudio and select “Pull Branches”. This will pull in the branch you recently made, or branches others have added.

Top left-of-center in RStudio

B. Now select the Branch dropdown menu and select your branch of choice. Your edits will be committed and pushed to this branch.

In the Git Tab

C. Make your changes to a file (Script, Markdown, CSS, etc), check the “Staged” box (so changes are included in the commit), then select “Commit” in the Git Tab. A new window will appear (image below) where you can review changes. Make sure you add a comment to describe your changes in “Commit Message”, then select “Commit”. Finally, select the Green Push arrow to push changes to the remote branch repository.

This screen appears after selecting “Commit”

C. Creating a fork

4.1.0.4 Forking

A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project. This is similar to a branch, but a fork is modified totally “off the grid” without anyone seeing changes someone is making until they attempt to merge. This is more common with lab-to-lab or developer-to-developer projects. Within-lab activity will generally stick to branching.

4.1.0.5 How to create a fork:

See tutorial here

4.2 How to make repository public or private

A. With your repository open, select the “Settings” tab. This will bring you to a new page. Scroll until you see “Danger Zone” subheading, and select “Change visibility”.

5 GitHub and R

5.1 How to insert relative paths in R Markdown files

Images

A. Open the repository where the image is stored and select the image. With the image selected, click the “Download” button. This will give you the raw HTTPS path to be copied into your Markdown.

B. Paste the link with the code below:

<img src="https://raw.githubusercontent.com/maxflurie/test2/master/coglab_logo20.png" width="300">
#Note we also see an option at the end to specify the size

This will show as:

Style Sheets

A. To insert a style sheet from your computer, you can use the r package ‘here’ to specify your chosen CSS. With your CSS in the same folder as your Markdown, simply use the following code to designate the path:

css: !expr here::here("/yourCSS.css")