Complete Setup

This is a more complete setup. It includes RStudio, Git, and GitHub integration.

Requirements:

  1. RStudio Desktop:

  2. Git Housekeeping

    • If you already have Github Desktop installed, you still need to install the standalone Git version for the following steps.

    • The integration of RStudio using Git with authentication that was installled with GitHub Desktop is still possible on some systems.

      For LJMU users this means: if you have GitHub Desktop installed and authenticated your GitHub.com access within GitHUb Desktop, you should be able to install Git standalone (Point 3 below), without having to authenticate with PAT and command line after that. After Git installation, you can go straight to Point 6 below.

  3. Git Installation First, check if you already have Git installed: How to Check for Git Installation

    If you DO NOT have Git installed:

    If you DO have Git installed: Great! You’re all set for the Git part of this setup. !! If you also have GitHub Desktop installed, go straight to Point 6 from here.

  4. Configure Git (First-Time Setup): After installing Git, tell it who you are by running these commands in your RStudio Terminal:

     git config --global user.name "Your Name"
     git config --global user.email "your.email@example.com"
  • User email has to be an email address connected to your github.com profile. These can be found on github.com, by clicking on your profile picture -> Settings -> Emails. You can use your actual email address, or, more standard, there is a more anonymous email that can be used (look on that page for the email, ending in @users.noreply.github.com)

For example, my commands could look like:

     git config --global user.name "Felix Z"
     git config --global user.email "FelixZ@zajitschek.net"
  • Your Name can be your GitHub user name, but doesn’t have to be. This is what appears as the author of your commits on GitHub.
  1. Connect RStudio to GitHub (Personal Access Token - PAT): This is the most secure way to connect RStudio/Git to GitHub without repeatedly typing your password.
    • Generate a PAT on GitHub:
      1. Go to your GitHub profile settings: github.com/settings/tokens (somehow hidden when you try to navigate to it on the GitHub.com page: Click on your profile picture, upper right corner, then Settings -> Developer settings (last link, bottom left) -> Personal Access Tokens
      2. Choose Tokens (classic), then Button Generate new token (classic) and choose Generate new token (classic).
      3. Give it a descriptive Note (e.g., “RStudio PAT”).
      4. Set an Expiration (e.g., 30 days, 90 days, custom date after the workshop, or No Expiration).
      5. Under Select scopes, check at least repo (full control of private repositories) and potentially workflow if you plan to use GitHub Actions.
      6. Click Generate token.
      7. IMPORTANT: Copy the generated token immediately! You won’t see it again! Store it securely (e.g., in a password manager).
    • Store PAT in RStudio/Git: When you try to interact with GitHub from RStudio for the first time (e.g., by creating a new RStudio project from a GitHub repository, or pushing changes), Git will prompt you for your username and password/PAT.
      • Enter your GitHub username.
      • When prompted for password, paste the PAT you just generated.
      • Git Credential Manager Core (Windows) or macOS Keychain Access will often securely store this for future use, so you don’t have to enter it every time. For instructions to do that later, go HERE.

6. RStudio-GitHub Workflow: Project Setup & Collaboration

Step 1: Create a Project and Add Git

This is the first step to linking your work to Git.

  • For a NEW Project: Go to the RStudio menu bar and select File > New Project…. In the pop-up window, choose New Directory, and make sure to check the box for “Create a Git repository.” Give your project a name and click “Create Project.” This automatically initializes a Git repository in your new project folder.

  • For an EXISTING Project: Go to File > New Project…, then select Existing Directory. Navigate to your project folder. Click “Create Project.” To add Git, go to the RStudio menu bar and select Tools > Project Options…. In the pop-up window, go to the Git/SVN tab. Next to “Version control system,” choose Git from the dropdown menu and click “OK.” RStudio will prompt you to restart. After restarting, a new Git pane will appear in the top-right of the RStudio window.

Step 2: Make Your First Commit

This is how you save a snapshot of your project’s history.

  • Make Changes: Create a new script, save a data file, or make any other changes to your project.

  • Open the Git Pane: In the top-right pane of RStudio, you’ll see a tab named Git. Click on it.

  • Review and Stage: The Git pane shows you a list of all the files that have changed.

    • The “Status” column indicates if a file is new (?), modified (M), or deleted (D).
    • To prepare a file for your commit, click the checkbox next to its name under the “Staged” column. This action is called staging—you’re telling Git which specific changes you want to include in this snapshot.

  • Commit the Changes: Click the Commit button at the top of the Git pane:

    Hover over the symbols on top of the Git window to see their function! In my RStudio version, Commit is the second one (a tick mark). !! Every file change has to be staged, before committing and pushing. There is no button that combines all three of these actions!

    You can also stage all your changes you want to include in a Commit in the following pop-up window (I think it’s easiest to go into the following window and use select all Ctrl + A (PC) or Cmd + A (Mac) and press the ‘Stage’ button in the upper menu bar).

  • This opens a new window called “Review Changes.”

    • On the left, you can see the files you’ve staged.
    • On the bottom right, there’s a box for a Commit message. This is a brief, descriptive note that explains what you changed and why. A good message is like a helpful hint for your future self (or a collaborator).
    • Click the Commit button in the pop-up window. This creates a local snapshot of your staged files. The changes are now saved to your computer’s Git history.

Step 4: Push to GitHub

Once you’ve made a commit, you need to push it to share it with the world.

  • The Push Action: The Push button (the up arrow in the Git pane OR in the ‘Review chnages’ popup window) sends the commits you’ve made on your computer to the remote repository on GitHub.
  • Pushing for the First Time: The first time you push, a window will pop up asking for your GitHub username and password/PAT. Enter your username and paste your PAT, as you set up in the earlier step. Your commits will now be uploaded to GitHub.
  • The Push-Pull Cycle: From now on, your workflow will be a simple “push-pull” cycle. After you commit, you push to share your changes.

Step 5: After the initial setup: PROJECT SETUP WORKFLOWS

After steps 1-4 above, creating a new RStudio project connected to a GitHub repository is much easier!

I will explain two workflows. The first one is independent of having GitHub Desktop installed. In contrast, workflow two uses GitHub Desktop. Just choose the one you prefer!

1: GitHub First Workflow

  1. Create a New Repository on GitHub: 💻 Go to github.com and sign in. Click the “New” button in the top-left corner. Give your repository a name (e.g., my-r-project). You can add a description. Most importantly, check the box to “Add a README file”. Do not add a .gitignore or a license here. Click “Create repository”.

  2. Copy the Repository URL: On the new repository’s page, click the green “< > Code” button. Make sure the HTTPS tab is selected, and then click the copy icon to copy the full URL to your clipboard.

  3. Create a New Project in RStudio: Open RStudio. Go to File > New Project… > Version Control > Git. In the “Repository URL” field, paste the URL you just copied. RStudio will automatically populate the “Project directory name.” Choose a location on your local machine to save the project and click “Create Project”.

  4. Confirm the Connection: RStudio will now clone the repository from GitHub to your local machine. A new RStudio project window will open. You will see a Git tab in the top-right pane. If you see the README.md file listed there, your local R project is successfully connected to the remote GitHub repository.

2: GitHub Desktop Workflow (Starting with “New repository”)

This workflow starts with GitHub Desktop to create a new local repository, then publishing it to a new GitHub repository. It doesn’t involve working on GitHub.com.

  • Create a New Repository in GitHub Desktop: Open the GitHub Desktop application. Go to File > New repository…. In the pop-up window, give your repository a name (e.g., best-R-project-ever). The “Local path” is where the repository will be created on your computer. Choose the directory where you want to store your R project. You can also select to add a README if you like. Click “Create repository”.

  • Publish the Repository to GitHub: GitHub Desktop will create a local Git repository in the folder you selected. It will then prompt you to “Publish repository” to GitHub. Click this button. A new window will appear where you can give it a name and description on GitHub and decide if it should be private. Click “Publish repository”.

  • Create the R Project in RStudio: Now that the repository exists on your local machine and on GitHub, open RStudio. Go to File > New Project… > Existing Directory. Navigate to the folder that GitHub Desktop created for your repository and click “Open”. RStudio will recognize that the directory is already a Git repository and will automatically create the project files, setting up the Git integration in RStudio for you.

Step 6: Working on a Branch (Best Practices)

To avoid problems in collaborative projects, you should always work on a separate branch.

  1. Create a New Branch: In the RStudio Git pane, click the dropdown menu with the branch name (it will likely say “main”). From the menu, select New Branch…. Give your branch a descriptive name (e.g., feature-plots or bug-fix). Click “OK.” RStudio will automatically switch you to this new branch.
  2. Make and Commit Changes: Make all your changes and commits on this branch, just as you did on the main branch. Your commits are now isolated from the main project code.
  3. Push the Branch: Click the Push button to send your new branch and its commits to GitHub. Since this is a new branch, you may need to confirm the “Upstream branch” setting, but RStudio usually handles this automatically.
  4. Create a Pull Request: Go to your repository on the GitHub website. GitHub will usually show a banner at the top prompting you to create a Pull Request for your newly pushed branch. A Pull Request is how you propose that the changes on your branch be merged into the main branch. This is also where you can ask a collaborator to review your work.
  5. Merge and Cleanup: Once the Pull Request is approved, you can click the Merge pull request button on GitHub to safely integrate your changes. After the merge is complete, you can click the Delete branch button on GitHub to keep your repository tidy.

This process keeps your main project code safe and allows for a smooth, collaborative workflow.

Working with a Collaborator on a Branch

Working with a collaborator on a branch is a highly recommended practice for keeping your main branch clean and stable. Here’s a typical workflow:

  1. Both Collaborators Create a Branch: Each person creates their own branch from the main branch (e.g., you create your-branch and your collaborator creates collaborator-branch).
  2. Work and Commit Locally: You both work independently on your branches, making changes and committing them as you go.
  3. The “Pull Before Push” Rule: Before you Push your changes to GitHub, it is best practice to always Pull first. This fetches any new changes from the remote repository that your collaborator might have pushed. Click the Pull button (the down arrow) in the Git pane. This helps prevent merge conflicts.
  4. Push Your Changes: After you pull, and after you are confident that your local branch is up-to-date with your collaborator’s work, you can Push your commits to GitHub. Your collaborator will do the same from their machine.
  5. The Pull Request and Code Review: When you are ready to merge your work, you open a Pull Request on GitHub. The Pull Request shows the changes you’ve made and allows your collaborator (or team) to review the code, suggest changes, or ask questions. This is a crucial step for collaboration, as it ensures quality and prevents bugs from being introduced to the main branch.
  6. Merging: Once the Pull Request is approved, you can merge your branch into main. Then, you can delete your branch on GitHub, and your collaborator will need to Pull from main to get your new changes.

This approach ensures that all work is reviewed and tested before being integrated, making for a much more robust and manageable project.