Version Control with Git, R, and Positron

Positron-Only Workflow on the Main Branch

Author

Paul Love

Date

2026-02-12 22:59:16 GMT+4

1 Introduction

This lesson teaches version control with Git and GitHub using only the Positron interface. The workflow stays on the main branch and uses cloning from an existing repository.

Prerequisites:

Git installed on the computer
Positron installed on the computer
GitHub account
Git identity already configured (user.name and user.email)

2 Core Concepts

Repository (repo): A project folder tracked by Git, including file history.

Commit: A saved snapshot of tracked changes.

Remote: The GitHub copy of a repository.

Clone: A local copy of a remote repository.

Pull: Download remote changes to the local repository.

Push: Upload local commits to the remote repository.

Sync in Positron: A single action that combines pull and push.

Checkout: Selecting a previous commit or file state to inspect differences and recover from current issues.

3 Positron Setup Reminder

Before this lesson starts, Git must already be configured on each machine with the correct name and email for commits. If Git identity is not configured, commit history attribution will be incorrect.

To set Git identity, run the following commands in a terminal, replacing the name and email with your own:

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

5 Clone the Repository in Positron

This lesson uses cloning only. Start the clone from the Positron welcome screen or from within the editor UI.

From the welcome screen
- Click New from Git to start the clone flow.

In the “New Folder from Git” dialog enter the repository URL and choose a local destination folder.

Important: Do NOT save repositories to cloud‑synced folders (Google Drive, iCloud, Dropbox). These services can interfere with Git file locking and produce confusing conflicts. Choose a local disk folder instead.
Click OK and allow Positron to open the cloned folder.

From the editor
- Command Palette: run Git: Clone (Ctrl/Cmd+Shift+P) and paste the repository URL.
- Enter a local destination and let Positron open the repository.
This establishes a local copy of the repository, with a connection to the remote on GitHub. The main branch is checked out by default.

Repository URL used in this lesson: https://github.com/recap-org/template-r-small

6 Source Control Workflow in Positron

6.1 1. Make a Small Edit

Open README.md, add a short note, and save the file.

6.2 2. Review and Stage Changes

Open Source Control from the sidebar.
Select the changed file to open the diff view.
Stage the file with the + action.
For the purposes of this demonstration, all changes are staged in a single commit. In more complex projects, staging related changes separately can make for a clearer commit history.

6.3 3. Commit on Main

Enter a clear commit message, for example: Update README with course note.
Select Commit.

6.4 4. Synchronize with GitHub

In Positron, Sync combines pull and push:

Pulls remote updates first (i.e., it downloads any changes from GitHub that may have been made since the last sync).
Pushes local commits second (i.e., it uploads the new commit to GitHub).

This keeps main current on both local and remote copies.

7 Using Checkout to Fix Current Problems

When a recent edit causes a problem, checkout and comparison tools help identify and recover a working state.

7.1 Compare Current Work Against Last Commit

Open Source Control.
Select a changed file.
Review the side-by-side diff to identify the exact lines that introduced the issue.

7.2 Checkout a Known-Good State

Open repository history in Positron.
Select a known-good commit or file revision.
Use Checkout (or equivalent restore action) to inspect or recover that prior state.
Re-test the repo and commit the fix on main.

This approach allows rapid diagnosis without introducing branch complexity.

8 File Size Guidance

GitHub enforces file size limits, and large files degrade repository performance.

Keep tracked files below 100 MB.
Prefer much smaller data files whenever possible.
If large files are necessary, consider using Git Large File Storage (LFS) or an external data hosting service instead of tracking them directly in Git.
- Link to Git LFS documentation: https://git-lfs.github.com/

9 Best Practices on Main

Pull or Sync before starting new edits.
Keep commits small and focused.
Use clear commit messages that describe the change.
Review diffs before every commit.

--- title: "Version Control with Git, R, and Positron" subtitle: "Positron-Only Workflow on the Main Branch" author: "Paul Love" date: now date-format: "YYYY-MM-DD HH:mm:ss z" format: html: toc: true toc-depth: 5 code-tools: true theme: readable highlight-style: tango smooth-scroll: true embed-resources: true --- ## Introduction This lesson teaches version control with Git and GitHub using only the Positron interface. The workflow stays on the `main` branch and uses cloning from an existing repository. **Prerequisites:** - Git installed on the computer - Positron installed on the computer - GitHub account - Git identity already configured (`user.name` and `user.email`) ## Core Concepts **Repository (repo):** A project folder tracked by Git, including file history. **Commit:** A saved snapshot of tracked changes. **Remote:** The GitHub copy of a repository. **Clone:** A local copy of a remote repository. **Pull:** Download remote changes to the local repository. **Push:** Upload local commits to the remote repository. **Sync in Positron:** A single action that combines pull and push. **Checkout:** Selecting a previous commit or file state to inspect differences and recover from current issues. ## Positron Setup Reminder Before this lesson starts, Git must already be configured on each machine with the correct name and email for commits. If Git identity is not configured, commit history attribution will be incorrect. To set Git identity, run the following commands in a terminal, replacing the name and email with your own: ```bash git config --global user.name "Your Name" git config --global user.email "myemail@example.com" ``` ## Sign In to GitHub in Positron (HTTPS) 1. Open Positron. 2. Open Accounts by clicking the person icon on the sidebar. 3. Choose GitHub and complete browser authentication. 4. Return to Positron and confirm the account is connected. ## Clone the Repository in Positron This lesson uses cloning only. Start the clone from the Positron welcome screen or from within the editor UI. 1. From the welcome screen - Click **New from Git** to start the clone flow. ![welcome screen screenshot](https://i.imgur.com/0NfcGA7.png) - In the "New Folder from Git" dialog enter the repository URL and choose a local destination folder. ![dialog screenshot](https://i.imgur.com/Y7cNwMv.png) - Important: Do NOT save repositories to cloud‑synced folders (Google Drive, iCloud, Dropbox). These services can interfere with Git file locking and produce confusing conflicts. Choose a local disk folder instead. - Click **OK** and allow Positron to open the cloned folder. 2. From the editor - Command Palette: run `Git: Clone` (Ctrl/Cmd+Shift+P) and paste the repository URL. - Enter a local destination and let Positron open the repository. 3. This establishes a local copy of the repository, with a connection to the remote on GitHub. The `main` branch is checked out by default. Repository URL used in this lesson: `https://github.com/recap-org/template-r-small` ## Source Control Workflow in Positron ### 1. Make a Small Edit Open `README.md`, add a short note, and save the file. ### 2. Review and Stage Changes 1. Open **Source Control** from the sidebar. 2. Select the changed file to open the diff view. 3. Stage the file with the **+** action. 4. For the purposes of this demonstration, all changes are staged in a single commit. In more complex projects, staging related changes separately can make for a clearer commit history. ### 3. Commit on Main 1. Enter a clear commit message, for example: `Update README with course note`. 2. Select **Commit**. ### 4. Synchronize with GitHub In Positron, **Sync** combines pull and push: - Pulls remote updates first (i.e., it downloads any changes from GitHub that may have been made since the last sync). - Pushes local commits second (i.e., it uploads the new commit to GitHub). This keeps `main` current on both local and remote copies. ## Using Checkout to Fix Current Problems When a recent edit causes a problem, checkout and comparison tools help identify and recover a working state. ### Compare Current Work Against Last Commit 1. Open **Source Control**. 2. Select a changed file. 3. Review the side-by-side diff to identify the exact lines that introduced the issue. ### Checkout a Known-Good State 1. Open repository history in Positron. 2. Select a known-good commit or file revision. 3. Use **Checkout** (or equivalent restore action) to inspect or recover that prior state. 4. Re-test the repo and commit the fix on `main`. This approach allows rapid diagnosis without introducing branch complexity. ## File Size Guidance GitHub enforces file size limits, and large files degrade repository performance. - Keep tracked files below 100 MB. - Prefer much smaller data files whenever possible. - If large files are necessary, consider using Git Large File Storage (LFS) or an external data hosting service instead of tracking them directly in Git. - Link to Git LFS documentation: https://git-lfs.github.com/ ## Best Practices on Main - Pull or Sync before starting new edits. - Keep commits small and focused. - Use clear commit messages that describe the change. - Review diffs before every commit.