Skip to contents

Using Git and GitHub

Source: vignettes/git_github.Rmd
git_github.Rmd

Introduction and notation

This vignette explains how to set up and use Git (a version control system) and GitHub (a website where files, usually code, can be stored) with RStudio.

Angled brackets (<...>) indicate place holders that should be replaced with specific text to get working code or working file paths. For example, <username> and <repository> are place holders that refer to a username and repository name, e.g., https://github.com/<username>/<repository> could refer to the URL https://github.com/JesseAlderliesten/checkrpkgs, the GitHub repository of this package.

Files on your PC are called often called ‘local files’, whereas files on GitHub are called ‘remote files’. Similarly, a folder on your PC (e.g., C:\Program Files\R\R-4.6.0\library\checkrpkgs) is often called a ‘directory’, whereas a folder on GitHub (e.g., https://github.com/JesseAlderliesten/checkrpkgs) is often called a ‘repository’.

Setting up Git and GitHub

Create a GitHub account, download a GitHub client such as Git SCM or Git for Windows and install it. To update Git for Windows if you already have it, type git\update-git-for-windows in the shell.

To use Git and GitHub from RStudio, in RStudio go to Tools > Global Options > Git/SVN and tick Enable version control interface for RStudio projects. The Git executable field should point to the git.exe file, which probably is at C:\Program Files\Git\bin\git.exe or in a hidden folder at C:\Users\<owner>\AppData\Local\Git\bin\git.exe (in Windows notation; outside Windows, these paths are written as C:/Program Files/Git/bin/git.exe and C:/Users/<owner>/AppData/Local/Git/bin/git.exe, respectively, see Paths in the shell). If the content of the field Git executable is not correct, open the Git Bash shell (which was installed when installing Git for Windows) by searching for Git Bash in Windows’ Start menu. In the Git Bash shell, run where git.exe to get the location of the Git executable.

To associate Git with your GitHub account, you need to provide your name (this name is listed in GitHub with the changes you make and does not have to be your GitHub username), and the email associated with your GitHub account. See the Chapter Introduce yourself to Git from Happy Git and GitHub for the useR for more details.

git config --global user.name '<Jane Doe>'
git config --global user.email '<jane@example.com>'
git config --global --list

The last line should return the username and email address you just entered.

Using personal access tokens (PATs)

On the use of personal access tokens (PATs) instead of a username and password, see:

Using Git and GitHub

To work with GitHub in RStudio, you should open the R Project file (i.e., a file with extension .Rproj), not the R script (i.e., a file with extension .R). Then the Git menu will be visible as a tab in the Environment pane.

Pull to get changes from GitHub incorporated in your PC, and handle any conflicts to get directory on your PC up-to-date with the repository on GitHub:

  • in RStudio: use the pull button (downward arrow) in the Git menu
  • or in the shell: git pull https://github.com/<username>/<repository>

Save the modified R file after you have made some changes, only then will the name of the file appear in the Git menu of RStudio to review changes:

  • in RStudio: check the Staged box in front of the relevant filename, use the Diff button in the Git menu to get an overview of the changes to the file, in the box Commit message you should describe the changes and why you made them, and use the Commit button. Pull again (downward arrow) to make sure the directory on your PC is up-to-date, and handle any conflicts. Then push (upward arrow) to incorporate the changes in the repository on GitHub.
  • or in the shell: compare the content of two files, see the instructions in the section Comparing files below. Next, use git commit -m '<your commit message>' <path>/<and>/<filename>.R git push https://github.com/<username>/<repository> to commit changes.

If a Push leads to an error because of an invalid username or password, Push again, then you will be asked for a personal access token (PAT; see the section Using personal access tokens (PATs) above). After you have entered the PAT once, RStudio will remember it.

To Push only some of the changes you made, use the Diff button in the Git menu and select the line or lines of code containing the changes you want to Push. Then a button Stage line or Stage chunck will show up next to the selected code. Click that button to Push only the selected lines.

Adding a new file

To add a file to GitHub that is not there yet, first add it to the R project folder on your PC (see the output of getwd()), then check the Staged box in front of the relevant filename in the GitHub pane of RStudio and commit it as described above.

Using the shell to add a new file is more involved: if the working directory of the shell (see the output of pwd) is not the folder where the to-be-added file is in, the working directory has to be changed to that folder (e.g., using cd <path/to/folder> in the shell), or the path has to be added in front of the filename (dragging the file onto the shell will copy the path to the shell).

Then let git know the new file is there by typing (it is convenient to use tab-completion to select files): git add <filename>.<extension>.

Comparing files

Using GitHub

  • For a chronological overview of all commits (i.e., across all files) in a particular branch of a repository, use an URL of the form http://github.com/<username>/<repository>/commits, or go to the main page of the repository and in the Code panel click the clock icon at the top of the file overview.
  • To compare different branches of a repository, use three dots between their names, giving an URL of the form https://github.com/<username>/<repository>/compare/<branch>...<otherbranch>, for example https://github.com/JesseAlderliesten/checkrpkgs/compare/main...devel that compares the main and devel branches of this package. Details: here
  • To compare different commits in a repository, use two dots between their commit IDs (the shortened SHA codes displayed at the right of each commit in the commit history, and at the top of the commit), giving an URL of the form https://github.com/<username>/<repository>/compare/<ID_commit>...<ID_othercommit>, for example https://github.com/JesseAlderliesten/checkrpkgs/compare/e8eb0a1...e60a155 that compares two commits. Details: here
  • See also section Repositories: download, fork, or clone? below.

Not using GitHub

R scripts can be compared using tools::Rdiff(): use the quoted file paths (i.e., the directories and file names, including the extensions) of the two files as arguments from and to:
tools::Rdiff(from = "<path/and/filename_file1>.R", to = "<path/and/filename_file2>.R")

For a nicer output, compare R scripts using the Bash shell: open the Bash shell and copy the file paths (i.e., the directories and file names, including the extensions) of the two files to be compared into the shell on the same line, and press Enter: git diff --no-index '<path/and/filename_file1>.R' '<path/and/filename_file2>.R'

Notes:

  • --no-index makes it possible to compare files that are not under version control in Git.
  • Using quotes ('') around the paths ensures this also works when they contain spaces.
  • The two paths should be on the same line, i.e., not separated by a newline.
  • Although the scroll bar in Git Bash seems to indicate the end of the file is reached (and scrolling with the mouse does not work), usually a colon (:) will be displayed left to the cursor to indicate that only part of the file is shown. Use the down arrow key to see the whole file until the end of the file is reached, which is indicated by (END).
  • The location of a change is indicated at the top of a changed chunk. E.g., -13,5 +14,9 indicates a deletion at character five of line thirteen and an insertion at character nine of line fourteen.

Deleting a file

To delete a file, delete the file from your PC, then commit the change (i.e., deletion of a file), using the commit message to describe why the file was deleted. Then pull to make sure directory on your PC is up to date with the repository on GitHub, and then push the change to the GitHub repository.

Alternatively, open the file in the GitHub repository, click the three dots at the top-right of the file > delete > commit. Use the commit message to describe why the file was deleted. After that, find the file on your PC and delete it. Then pull.

Deleted files and their history can still be viewed on GitHub, e.g., by finding the commit in which the file was deleted.

Moving or renaming a file

See the GitHub documentation here and here.

Repositories: download, fork, or clone?

There are several ways to copy code from a GitHub repository to your PC:

  • To be able to push your changes back to a GitHub repository to which you do not have writing access, you need to fork the repository: use the fork button on the GitHub page of the repository and then use create a new fork. This creates a copy of the repository in your own GitHub repository. Next, you have to clone your copy to your PC, see the next point.
  • To be able to push your changes back to a GitHub repository to which you do have writing access (e.g., to work on a fork you created in the step above; or to work on your project from another PC), you have to clone the GitHub repository to your PC: use the green Code button on the GitHub page of the repository (if you forked a repository, you need the Code button of your fork, not of the original repository), copy the URL to the clipboard (i.e., do not use download ZIP), create a new R project in RStudio (File > New Project > Version control > Git), paste the repository URL (https://github.com/<username>/<repository>) in the designated field, select the desired location on your PC, and create the project. The same repository URL can be used when using shell commands to clone a repository, either with its complete history by using git clone https://github.com/<username>/<repository> or with only the last commit by using git clone --depth=1 https://github.com/<username>/<repository>.
  • To download code without being able to push your changes back to a GitHub repository, download the repository by using the green Code button on the GitHub page of the repository, choose Download ZIP and unzip the downloaded file (right-click on them and choose extract all). To be able to let R use the R files correctly, R has to know where the files are. If the downloaded files are an R package, move it to a location where R looks for packages (given by cat(normalizePath(.libPaths())), something like C:\Program Files\R\R-4.6.0\library or C:\Users\<owner>\AppData\Local\R\win-library\4.6). Then open the .Rproj file that has the same name as the repository. If the downloaded files are not a package but an R project, open the .Rproj file to change the working directory to the folder where that project file is. If the downloaded files are not an R project, you have to move them to the working directory (see the output of getwd()), or use setwd(<path/to/files>) to change the working directory to the location where the files are.

Installing a package from GitHub

The following code can be used to install packages from GitHub (for details see the section Installing packages > Github in the vignette R packages: vignette("r_pkgs", package = "checkrpkgs")):

pkgs_new <- "JesseAlderliesten/checkrpkgs"
if(!requireNamespace("remotes", quietly = TRUE)) {
  install.packages(pkgs = "remotes", lib = .libPaths(), dependencies = NA,
                   type = getOption("pkgType"), verbose = getOption("verbose"),
                   quiet = FALSE)
}
remotes::install_github(repo = grep(pattern = "/", x = pkgs_new, value = TRUE,
                                    fixed = TRUE),
                        dependencies = NA, upgrade = "ask", force = FALSE,
                        quiet = FALSE, build_vignettes = TRUE, lib = .libPaths(),
                        verbose = getOption("verbose"))

Further documentation

In addition to section Using GitHub above, see:

GitHub Actions

See the section Automate checks in the vignette Package setup and section Use GitHub Actions in the vignette Package development, both from package develcoder: vignette("pkg_setup", package = "develcoder") and vignette("pkg_devel", package = "develcoder").

Common shell commands

For an overview of shell commands, see the documentation of Git SCM, the section about the shell from Happy Git and GitHub for the useR (a summary of which is given below), or in the BASH shell type git config or git help <command> (replace <command> by the command you want help about).

  • list files: ls (use ls -a to also show hidden files)
  • list remote repositories: git remote -v
  • show status of repositories: git status
  • show user details: git config --global --list
  • working directory: change it with cd (e.g., cd 'D:/Userdata/<owner>/Documents/GIT/<somefolder>'); navigate to it: cd ~; print it: pwd

Paths in the shell

When entering paths in the shell, use the forward slash (/) as file separator instead of the Windows-default backslash (\). If the path you want to specify contains spaces (e.g., D:\Userdata\My Account\...), you need to use quotes around the path (e.g., "D:/Userdata/My Account/..."). Tab-completion can be used when entering paths: single tab to select an option, double tab to see multiple options. Dragging a file into the shell gives the absolute path to that file. The current and parent directory can be indicated by a single (.) or two (..) dots in file paths, respectively. On paths and file separators in R, see the ‘Notes on paths’ in help("is_path", package = "checkinput").

Documentation

Official documentation

Books

Chapters