Introduction to Git & GitHub

A repository containing interactive trainings, tutorials, and other relevant resources for getting started with Git & GitHub for RStudio & Positron.

Table of Contents

• Audience
• Why Learn Git & GitHub
• Getting Started
  • Learning Objectives
  • Setup
  • Recommended Training Plan (1 - 2 hours)
• All Trainings
• Pull Requests
• Resources

Why Learn Git & GitHub

1. Safe updates to code: If projects are critical to ongoing organization operations, GitHub can provide a safe, separated sandbox ("branch") to work out of and test out improvements – without breaking or jeopardizing currently functional code.
2. Cloud Backup: Projects and code are stored safely in the cloud. They are quick and easy to back up onto a new computer if your old computer was to break and/or be replaced. It is likely much more difficult to back up files from the old computers hard drive.
3. Project management: Github provides many easy-to-use support tools to request, track, and compare changes/added features to code over time. This is extremely helpful for managing projects that might grow or evolve over time.
4. Documentation: Github provides a robust framework of documentation and collaboration for projects via READMEs, issues, etc. No more searching through cluttered shared drives to find code or documentation for why/what changes were made.
5. Avoiding Clutter: Using GitHub allows you to avoid the dreaded scenario where the following filename suffixes being appear throughout a project (we all have done it at some point and we never want to go back): _v1, _v3, _v9, _draft , draft2, _FINAL, _final_final, _archived
6. Enhanced Collaboration: Sharing/collaborating on projects and code is much more efficient on GitHub. Multiple users can work together at the same time, and it avoids many back and forth emails (with clutter mentioned above).

Do you need to use Git & GitHub for all projects?

• No
  • Git & GitHub may be a bit overkill for small, one-off projects that will not need updates.
• Git & GitHub is highly recommended when:
  • There is at least a moderate probability you or your team will do updates, collaborate, and/or share code (if applicable).
  • Enabling Git & GitHub for a project typically takes only a minute or two longer (than traditional prokects), and comes with many of the previously mentioned benefits.
• Git & GitHub will be used by KPHD under the following circumstances at a minimum:
  • Recodes of any database that provide an updated or improved database that should be available for the entire team
  • Code that is ready to be reviewed by the Epi team
  • Sharing code improvements and suggestions across the team

Getting Started

Learning Objectives

1. Create a GitHub account
2. Install Git - For educational purposes only as our IT department installs this for us
3. Connect Git, GitHub, and RStudio or Positron IDE
4. Become familiar with common Git & GitHub terms (i.e."Version Control", "Branch", "Push/Pull", "Clone")
5. Learn how to create and collaborate on GitHub repositories.

Setup

Setup on RStudio (1 - 2 hours)

Note: Set up can often be the most difficult part of learning Git and Github. Why?

• Set up is required to get started, and this is a entirely new platform for users. It will feel weird at first but will become familiar over time.
• You have to install Git, get local Git talking to GitHub, and make sure RStudio can talk to local Git (and, therefore, GitHub). This is one-time or once-per-computer pain.
• It is recommended to set aside 1 to 2 hours to complete these steps.

1. Create a GitHub account
2. Install Git- For educational purposes only as our IT department installs this for us

• Introduce yourself to Git

3. Connect Git, GitHub, RStudio

• Create a GitHub Personal Access Token
• Connect to GitHub
• Connect RStudio to Git and GitHub
• Detect Git from RStudio

Setup on Positron (30 minutes) - *Not needed at this time for KPHD epidemiologists

1. Create a GitHub account and sign in.
2. Install Git
3. On the left-hand side bar of Positron, go to Accounts, and click Sign in with GitHub to use GitHub Pull Requests.
4. On the pop-up menu, copy the provide 8 digit code (####-####) and click Copy & Continue to GitHub.
5. A GitHub verification webpage will pop up. Navigate to the GitHub account you have signed into and click Continue.
6. A GitHub Device Activation webpage will pop up and ask you for the 8 digit code from Step 4. (Tip: It should automatically be copied to your clipboard. Press Ctrl + V to paste the code in). Press Continue.
7. A GitHub Authorize Positron webpage will pop up. Under the Organization access section click Request or Grant (if applicable). At the bottom of the page, click Authorize posit-dev.
8. A GitHub Confirm access webpage may pop up (if you have Multi-Factor Authentication or MFA). If so, provide a MFA code using the MFA solution you have set up with your GitHub account.
9. On the left-hand side bar of Positron, go to Accounts, and your GitHub account should now be registered.

• Note: In the past, some users have had to repeat this process twice for Positron's Account tab to successfully update. This may be a bug.

10. If initializing a repository directly from Positron, you must use navigate to the Source control tab, hover over the three dots under the Repositories section,, then select add remote. It is important that you create a blank GitHub repo with the same name on the web browser version for this to work prior to initializing the repo for ease based on my own testing (TE)

Recommended Training Plan (1 - 2 hours)

1. Introduction to GitHub
2. Review pull requests
3. Getting an Existing Project onto GitHub

All Trainings

Interactive

• Interactive Learning with GitHub Skills
  • Introduction to GitHub - Introduces repositories, branches, commits, and pull requests.
  • Review pull requests

Static

• Happy Git and GitHub for the useR - The best resource for connecting Git & GitHub with RStudio
  • Starting a New Project on GitHub - Preferred method for individual work - TE
  • Getting an Existing Project onto GitHub - Preferred method for collaborative work - TE
  • Linking Github to an Existing Project - An option in case you have a project you want to convert over to a GitHub Repo
• EpiR Handbook - Git & GitHub - A single chapter with a comprehensive overview of using Git & Github with RStudio
• GitHub Documents - Short static tutorials (easily browseable, and great to refer back to after doing interactive training)

  • Getting Started

  • Creating a Repository

    • Best Practices for Repositories
    • Creating a New Repository
    • Ignoring files

  • Interacting with a Repository

    • Creating & Deleting Branches
    • Creating an Issue
    • Create a Branch for an Issue

  • Updating a Repository

    • About pull requests
    • Comparing branches

Pull Requests

A pull request (PR) is how you propose changes to a GitHub repository. It's a request for the repository maintainer to review and merge your changes into their repository. Pull requests are a key component of collaborative development and code review on GitHub.

Why Use Pull Requests?

Pull requests provide a structured way to propose, discuss, and review code changes before they are merged into the main codebase. They enable team members to provide feedback, catch potential issues, and maintain code quality through collaborative review.

Forking vs. Cloning vs. Branching

It's important to understand these three different workflows, as they are often confused:

Forking - Creating a complete copy of a repository under your own GitHub account. This is typically used when contributing to projects you don't have direct write access to (e.g., open-source projects). After forking, you clone your fork locally and create a PR back to the original repository. Forking creates a permanent separation and is more complex to manage.

Cloning - Creating a local copy of a repository on your computer. This is the act of downloading the repository code so you can work on it locally. Cloning doesn't create a copy on GitHub; it just downloads the existing repository to your machine.

Branching - Creating a separate line of development within the same repository. All team members with access to the repository can create branches directly without forking. Changes made on a branch don't affect the main codebase until they are merged through a pull request.

For KPHD workflows, we recommend using branching for team collaboration. This approach is simpler to manage, requires less setup, and keeps all work organized within a single repository. Team members create feature branches for their work, submit PRs for review, and merge changes back to the main branch once approved. This avoids the complexity of managing forks and makes it easier for team members to stay synchronized.

Making Pull Requests in R with usethis

The usethis package provides helper functions that streamline the pull request workflow within R. These functions are particularly useful if you're contributing to someone else's repository or collaborating on shared R projects.

Prerequisites

Before using the usethis pull request functions, ensure you have:

• Configured a GitHub personal access token (PAT). Use usethis::create_github_token() to set one up and usethis::git_sitrep() to verify your setup.
• Selected your preferred Git transport protocol ("https" or "ssh"). The "https" protocol with a PAT is the simplest to get started.
• The gert package installed, which handles Git operations from R.

Basic Workflow with usethis

Step 1: Fork and Clone the Repository

Start by forking the repository to your GitHub account and cloning it locally:

library(usethis)
create_from_github("owner/repo-name")

This function will fork the repository into your GitHub account, clone it to your local machine, set up the necessary remote branches (origin and upstream), and open a new RStudio session in the project.

Step 2: Create a Feature Branch

Initialize a new branch for your pull request:

pr_init(branch = "descriptive-branch-name")

This creates a local branch and switches to it. Always use a descriptive branch name that indicates the purpose of your changes (e.g., "fix-calculation-error" or "add-validation-check").

Step 3: Make Your Changes

Edit your files, make commits to Git, and test your changes locally:

# Make changes to files, then commit them using RStudio's Git panel
# or command line: git add . && git commit -m "descriptive message"

Step 4: Push Your Changes and Create a PR

Once you're satisfied with your changes, push them to your fork and create a PR:

pr_push()

This function pushes your branch to your GitHub fork and opens a browser window where you can review your changes and create the pull request. Click "Create pull request" and optionally add a title and description explaining your changes.

Step 5: Address Reviewer Feedback

If reviewers request changes, make them locally, commit, and push again:

pr_push()

Your updates will automatically be reflected in the existing PR.

Step 6: Finishing Up

Once your PR is merged, clean up your local branches:

pr_finish()

This switches you back to the default branch (typically master or main), pulls the latest changes from the source repository, and deletes your local feature branch.

Helpful usethis PR Functions

• pr_init() - Create and switch to a new feature branch
• pr_push() - Push changes to your fork and prepare to create/update a PR
• pr_view() - Open the PR in your browser
• pr_fetch() - Fetch a PR to your local machine (useful for reviewers)
• pr_pull() - Pull updates from the PR branch
• pr_pause() - Switch back to the default branch and sync with the source repo
• pr_resume() - Resume work on a PR after switching branches
• pr_merge_main() - Sync your PR branch with the latest changes from the main branch

For detailed examples and more advanced workflows, see the usethis PR functions guide.

Making Pull Requests via the GitHub Web Interface

If you prefer not to use R functions or need to make quick edits, you can create and manage pull requests entirely through GitHub's web interface.

Creating a PR via Web Interface

Step 1: Fork the Repository

Navigate to the repository on GitHub and click the "Fork" button in the top-right corner. This creates a copy of the repository under your GitHub account.

Step 2: Create a Branch

On your forked repository, click the "Branch" dropdown (typically showing "main" or "master") and type a new branch name. Press Enter to create your feature branch.

Step 3: Edit Files

Click on the file you want to edit and use GitHub's built-in editor to make changes. You can add, modify, or delete content directly in the browser. Click "Commit changes" to save your edits to your branch.

Step 4: Create the Pull Request

Once you've made your changes, navigate to your forked repository and click the "Compare & pull request" button (if visible) or go to the "Pull requests" tab and click "New pull request." Select your feature branch and the target branch (usually the default branch of the original repository). Add a descriptive title and description of your changes, then click "Create pull request."

Step 5: Review and Respond to Feedback

Monitor your PR for comments and suggestions from reviewers. You can continue to make edits by clicking the pencil icon next to files in the PR and committing additional changes directly through the web interface.

Step 6: Merge or Close

Once approved, the repository maintainer can merge your PR. If your PR is no longer needed, you can close it from the PR page.

Viewing and Managing PRs on the Web

• View your PR: Go to your forked repository and click the "Pull requests" tab to see a list of your open and closed PRs.
• Review changes: In the "Files changed" tab of a PR, you can see exactly what modifications were made.
• Comment on specific lines: Hover over a line of code in the PR and click the "+" icon to leave inline comments.
• Request reviews: In the PR details, you can request reviews from specific team members.
• Merge strategies: Reviewers can choose from different merge strategies: create a merge commit, squash and merge (combine all commits into one), or rebase and merge.

Comparing the Two Approaches

Use usethis R functions when:

• You're working on complex changes that require local testing before submission
• You're contributing to R packages or collaborative R projects
• You prefer to work entirely within RStudio/Positron
• You need to address feedback through multiple commit cycles

Use the GitHub web interface when:

• Making simple, straightforward edits (e.g., updating documentation or fixing typos)
• You don't have Git and GitHub set up locally
• You want to quickly propose changes without leaving your browser
• Making minor contributions to repositories you don't frequently work with

Resources

• GitHub Glossary
• GitHub Markdown - Basic Formatting - Markdown is a universal text formatting language used in GitHub, RMarkdown, Quarto, and many other platforms.

License

MIT License. See LICENSE for details.