Getting set up

Before you can contribute code to an emLab project, you need three things in place: git installed on your machine, a GitHub account, and membership in the emLab GitHub organization.

Installing git

Git is the version control system that underlies everything on GitHub. It runs locally on your computer and tracks changes to files in a repository.

Do you already have git?

Open a terminal and run:

git --version

If you see a version number, git is already installed and you can skip ahead to configuring it. macOS users who do not have git may see an immediate offer to install command line developer tools – accept it.

macOS

The simplest option is to install the Xcode Command Line Tools, which include git. Run either of the following in a terminal to trigger the installer:

git --version
xcode-select --install

Click “Install” when prompted. Note that after a macOS upgrade you may need to repeat this step and re-agree to the Xcode license.

Two alternatives worth knowing:

  • Direct download: git-scm.com/downloads provides the latest macOS git installer and is a good option if you want the most current version.
  • Homebrew: If you use Homebrew as a package manager, brew install git works well and makes future updates easy.

Windows

The recommended approach is to install Git for Windows, also known as Git Bash. This installs git in a location that other programs (including RStudio and Positron) can find it, and also provides a Bash shell environment.

When the installer asks about “Adjusting your PATH environment”, select “Git from the command line and also from 3rd-party software”. Otherwise, the defaults are fine. Git is typically installed at C:/Program Files/Git/bin/git.exe.

If you already have Git for Windows but want to update it:

git update-git-for-windows

Linux

Install via your distribution’s package manager:

# Ubuntu or Debian
sudo apt-get install git

# Fedora or RedHat
sudo yum install git

For other distributions, see git-scm.com/download/linux.

Configuring git after installation

Once git is installed, tell it your name and email address. These appear in every commit you make:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Use the email address associated with your GitHub account.

Creating a GitHub account

If you do not already have a GitHub account, create one at github.com. Use an email address you will have long-term access to, since your GitHub account can persist beyond your time at emLab.

Joining the emLab GitHub organization

All emLab repositories live under the emlab-ucsb organization on GitHub. Send Erin O’Reilly a Slack message to request an invitation. You will receive an email from GitHub with a link to accept.

Base permissions

Once you join the emlab GitHub organization, you have read access to all repositories in the organization by default. If you create a new repository in the organization, you will automatically have admin access and can grant additional permissions to specific team members or outside collaborators on a per-repository basis. If you need write access to a repository and do not have it, ask the repository admin.

Organization owners can manage team membership and repository permissions through the organization’s People and Teams settings pages on GitHub.

Authenticating with GitHub

To push and pull code between your local machine and GitHub, you need to authenticate. Git can communicate with GitHub over two protocols – HTTPS and SSH – and the credentials differ between them.

HTTPS with a personal access token (PAT) is the recommended starting point, and is what GitHub itself recommends. It is easier to get working quickly on all platforms and has the added benefit that the same credential works for R packages that call GitHub’s API (e.g., usethis, gh, pak). SSH is a fine alternative once you are more comfortable with the tooling, and some people prefer it. You can always switch protocols later, and even mix them across different repositories or computers.

Note that GitHub no longer accepts your account password for command-line git operations. You must use a PAT (for HTTPS) or an SSH key pair.

HTTPS: personal access token

Generate a PAT

The recommended way to generate a PAT is from R:^[this requires the usethis package, which can be installed from the R terminal with install.packages("usethis")

usethis::create_github_token()

This opens a pre-filled GitHub form with recommended scopes already selected (repo, user, gist, workflow). Review the scopes, give the token a descriptive name that identifies the computer or project it is for (e.g., "work-macbook-pro"), and set an expiration. GitHub recommends accepting the default 30-day expiration; you will regenerate it on that schedule, which also gives you a chance to verify the scopes are still appropriate.

Click “Generate token” and copy it immediately – you will not be able to see it again after leaving the page. If you use a password manager like 1Password, store it there as well.

In lieu of the usethis package, you can create a PAT by navigating to the Developer Settings on your GitHub profile. You can review the GitHub documentation for generating and saving a PAT and to learn more about this topic.

Store the PAT

Once you have a token, store it in your system’s credential store using gitcreds:

gitcreds::gitcreds_set()

Paste the token when prompted. You can verify the stored credential at any time with gitcreds::gitcreds_get(), and run usethis::git_sitrep() for a broader diagnosis of your git and GitHub setup.

You can also copy the token to your clipboard by clicking the copy icon.

Renewing an expired PAT

When a PAT expires, return to github.com/settings/tokens, click the token’s name, and click “Regenerate token”. Copy the new token, then call gitcreds::gitcreds_set() and paste it in.

Linux note

Linux does not have a native credential store equivalent to macOS Keychain or Windows Credential Manager. The simplest workaround is to configure git’s credential cache with a long timeout:

git config --global credential.helper 'cache --timeout=10000000'

This keeps credentials in memory for roughly 16 weeks. As a fallback, you can store the PAT as an environment variable in ~/.Renviron:

usethis::edit_r_environ()
# Add: GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Restart R after editing .Renviron. Take care that this file never gets pushed to GitHub or synced to cloud storage.

SSH: key pairs

SSH authentication uses a cryptographic key pair: a private key that stays on your machine and a public key that you register with GitHub. If you already have experience with SSH or anticipate working across many repositories, SSH is worth setting up.

Do you already have SSH keys?

Check whether a key pair already exists:

ls ~/.ssh/

If you see files named id_ed25519 and id_ed25519.pub (or id_rsa and id_rsa.pub), you already have a key pair and can skip to adding the public key to GitHub.

Generate a key pair

From the terminal, run:

ssh-keygen -t ed25519 -C "DESCRIPTIVE-COMMENT"

Use a comment that identifies the computer, e.g. "jane-work-macbook". Accept the default save location when prompted. You may also set a passphrase – this is best practice but adds a small amount of complexity, so it is reasonable to skip it when first getting set up.

Add the key to your ssh-agent

macOS:

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

On macOS Sierra 10.12.2 and later, also create ~/.ssh/config with the following contents so the passphrase persists in the keychain across restarts:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Windows (Git Bash):

eval $(ssh-agent -s)
ssh-add ~/.ssh/id_ed25519

Linux:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Add the public key to GitHub

Copy the public key to your clipboard:

# macOS
pbcopy < ~/.ssh/id_ed25519.pub

# Windows (Git Bash)
clip < ~/.ssh/id_ed25519.pub

# Linux
xclip -sel clip < ~/.ssh/id_ed25519.pub

On GitHub, go to Settings > SSH and GPG keys, click “New SSH key”, and paste the key. Give it a title matching the comment you used when generating it.

Test the connection:

ssh -T git@github.com

You should see a message confirming your username.

A note on SSH and R packages

Unlike HTTPS with a PAT, SSH does not automatically authenticate R packages that call the GitHub API. If you use SSH for git operations, you will still need a PAT stored in your credential store for packages like usethis, remotes, and pak to work. This is one reason HTTPS is often the simpler choice.

Starting a new git-tracked repository

When starting a project from scratch, you can initialize git tracking directly from your IDE.

In Positron

  1. Open Positron and create a new directory for your project: File > Open Folder... (or choose an empty folder you’ve already created).
  2. Open the Source Control view in the left Activity Bar (or use the shortcut Ctrl+Shift+G on Windows/Linux or Ctrl+Shift+G on macOS).
  3. Click the Initialize Repository button. This runs git init behind the scenes.
  4. Create an initial file (like a README.md or .gitignore), stage it, and make your first commit in the Source Control panel.

In RStudio

  1. Go to File > New Project...
  2. Choose New Directory, then New Project.
  3. Choose a directory name and subdirectory.
  4. Check the box for Create a git repository.
  5. Click Create Project. RStudio will initialize the repo and restart itself within the new project.

Cloning an existing repository

To work on an existing emLab project, you will need to “clone” it, which downloads a local copy of the repository to your machine and links it to the remote version on GitHub.

Step 1: Copy the repository URL from GitHub

  1. Navigate to the repository on GitHub (e.g., under the emlab-ucsb organization).
  2. Click the green Code button in the upper right.
  3. Select the SSH tab (if you set up SSH keys) or the HTTPS tab (if you set up a PAT).
  4. Click the Copy icon next to the URL.

  • An SSH URL will look like: git@github.com:emlab-ucsb/repo-name.git

  • An HTTPS URL will look like: https://github.com/emlab-ucsb/repo-name.git

Step 2: Clone the repository into your IDE

In Positron

  1. Go to File > New Folder from Git... (or click the New dropdown menu and select New Folder from Git…).
  2. In the New Folder from Git dialog box, paste the repository URL you copied from GitHub.
  3. Choose the local destination where you want to store the project folder. We recommend using a dedicated GitHub directory, e.g. /Users/yourname/github/ on a Mac, to keep all your repositories organized in one place. Avoid saving repositories inside cloud-synced folders (like Google Drive, iCloud, or Dropbox) to prevent sync conflicts with Git.
  4. Click OK to clone the repository and let Positron open the folder.

In RStudio

  1. Go to File > New Project...
  2. Select Version Control.
  3. Select Git.
  4. In the `Repository URL field, paste the URL you copied from GitHub.
  5. The Project directory name will auto-populate. Choose where you want to store the project on your local machine in the Create project as subdirectory of field. We recommend using a dedicate github directory, e.g. /Users/yourname/github/ on a Mac, to keep all your repositories organized in one place. Avoid saving repositories inside cloud-synced folders (like Google Drive, iCloud, or Dropbox) to prevent sync conflicts with Git.
  6. Click Create Project.

Resources

Getting comfortable with Git and GitHub takes time. The following resources are recommended starting points, particularly for researchers coming to version control for the first time:

  • Happy Git and GitHub for the useR (happygitwithr.com) – The most practical introduction to git for R users. Covers installation, authentication, and daily workflows in detail.
  • Pro Git (git-scm.com/book) – The comprehensive reference. Chapters 1-3 cover the fundamentals.
  • GitHub Docs (docs.github.com) – GitHub’s own documentation, useful for organization and repository management questions.