Skip to contents

Using Git and GitHub

Source: vignettes/git_github.Rmd
git_github.Rmd

Introduction and notation

This vignette provides information on setting up and using Git (a version control system) and GitHub (a website where files, usually code, can be stored). Git and GitHub are frequently used together.

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

In this vignette, text between angled brackets (<...>) is used to refer to text that should be replaced with specific text to get working code or working file paths. For example, <username> and <repositoryname> are used as place holders to refer to a username and repository name: <username> and <repositoryname> in https://github.com/<username>/<repositoryname> should be replaced with JesseAlderliesten and checkrpkgs, respectively, to obtain the URL https://github.com/JesseAlderliesten/checkrpkgs referring to the GitHub repository of this package.

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 the Git for Windows GitHub client if you already have it, type git\update-git-for-windows in the shell.

To use Git and GitHub from RStudio: in RStudio at Tools > Global Options > Git/SVN, tick Enable version control interface for RStudio projects. Run where git.exe in the shell to get the location of the Git executable: probably C:\Program Files\Git\bin\git.exe or C:\Users\<owner>\AppData\Local\Git\bin\git.exe (usually a hidden folder) in Windows notation; in R these paths are C:/Program Files/Git/bin/git.exe or C:/Users/<owner>/AppData/Local/Git/bin/git.exe, see the Notes on paths.

Open the Git Bash shell (which was installed when installing Git for Windows) by typing Git Bash in Windows’ Start menu and press Enter.

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 not open an R script (i.e., a file with extension .R) but the R Project file (i.e., a file with extension .Rproj). Then the Git menu will be visible as a tab in the Environment pane.

Pull to get changes from the remote repository (i.e., GitHub) incorporated in the local directory (i.e., your PC), and handle any conflicts to get the local directory up-to-date with the remote repository:

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

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 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, describe the changes in the box Commit message, and use the Commit button. Pull again (downward arrow) to make sure the local directory is up-to-date, and handle any conflicts. Then push (upward arrow) to incorporate the changes in the remote repository.
  • in the shell: to compare the content of two files, see the instructions in the section Comparing files below. Next, use git commit -m '<your commit message goes here>' <path>/<and>/<filename>.R git push https://github.com/<username>/<repositoryname> 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 this token for next times.

Adding a new file

To add a file to GitHub that was not there yet, first add it to the local folder (i.e., on your PC), then let git know it is there by typing (it is convenient to use tab-completion to select files): git add <filename>.<extension>.

If the working directory is not the folder where the to-be-added file is in, the working directory has to be set 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).

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>/<reponame>/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.
  • Comparing different branches: see here
  • Comparing commits: see 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'

Note:

  • The flag --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) after opening a file, 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

Consider moving files to a folder archive instead of deleting them. To delete a file, delete the file from the local directory (i.e., 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 the local directory is up to date with the remote repository, and then push the change to the remote repository.

Alternatively, open the file on the remote repository (i.e., on the GitHub website), 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 in the local directory and delete the it. Then pull.

Moving or renaming a file

See the GitHub documentation here and here.

Repositories: download, fork, or clone?

There are several ways to get 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 > 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 your project from another PC; or to work on a fork you created in the step above), you have to clone the GitHub repository to your PC: use the green Code button in 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>/<reposname>) 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>/<reposname> or with only the last commit by using git clone --depth=1 https://github.com/<username>/<reposname>.
  • To download code without being able to push your changes back to a GitHub repository, you can download the repository by using the green Code button, choosing Download ZIP and unzip the downloaded file (right-click on them and choose extract all). To be able to let R use the package correctly, move the package to a location of your R libraries (given by the output of 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 (which has the same name as the repository).

Installing a package from GitHub

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

remotes::install_github(repo = pkgs_new[basename(pkgs_new) != pkgs_new],
                        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 Use GitHub Actions in the vignette Package setup from package develcoder: vignette("pkg_setup", 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, navigate to: cd ~
  • working directory, print: pwd
  • working directory, change: cd (e.g., cd 'D:/Userdata/<owner>/Documents/GIT/<somefolder>').

Notes on paths

When entering paths in the shell, use forward slash (/) instead of the Windows-default backslash (\). If the path you want to specify contains spaces (e.g., D:/Userdata/My Account/...), 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.

Documentation

Official documentation

Books

Chapters

On git tags and releases: