Git + RStudio Tutorial

Imagine you have a piece of code, and you’re keen on tracking its changes without losing the original version. The conventional method involves saving scripts as new files, often labeled with indicators like ‘v0’ or a timestamp. Git offers a more seamless way to version your code without the hassle of managing different version files manually. It not only tracks changes made to your files but also equips you with tools to document those changes. While Git’s initial development focused on code versioning, it’s versatile enough to handle versioning of smaller datasets. GitHub and GitLab support various text file formats (e.g., csv, fasta), making them ideal for versioning those as well.

2. Setup

If everything went well we are all set for using git in rstudio by following the following instruction manual: rstudio git setup

3. Git Vocabulary

  • Repository (repo): The project folder + full history.
  • Commit: A snapshot of your work with a message.
  • Stage: Select files you want to include in a commit.
  • Push: Upload your local commits to the online repo.
  • Pull: Download commits from the online repo.
  • Remote: The online copy (e.g., GitHub, Gitlab).
  • Branch: a parallel workspace for isolated development.
  • Merge: combining that workspace back into the main project.
  • Merge conflict: When Git can’t auto-merge differences.

4. Creating a Project with Git

Option A: Start a New Project with Git

  1. File > New Project
  2. Choose a new or existing directory
  3. Check Create a git repository

With this option git is enabled. However, git is just used locally.

Option B: Clone an Existing Repository

  1. File > New Project > Version Control > Git
  2. Paste the repo URL
  3. Select a local location and click Create Project

With this option git is enable and able to interact with the remote.

Exercise: Create Your First Repository

  1. Create an empty remote git repository (github / gitlab).
  2. Clone the repository using option B.
  3. Run renv::init() to add an r project environment
  4. modify the .gitignore file and add renv/library

5. Basic Git Workflow

Now that we have a git setup for a project we can learn how versioning with git works.

5.1 Pull

Click Pull in RStudio to ensure your local files are up‑to‑date. Pull downloads the latest commits from the repo.

5.2 Stage and Commit

  1. Tick the file(s) to stage
  2. Use Diff button to inspect changes
  3. Write a clear message
  4. Click Commit

Changes are highlighted in red (removal) and green (addition).

5.3 Push

Send your commits to the remote repository.

Exercise 1: Create Your First Commit

  1. To your previously created git-enabled project
  2. Add a code directory and create a README.md
  3. Stage → Commit → Push the new quarto document
  4. Go to GitHub / Gitlab and check the history

Goal: See your commit appear on GitHub / Gitlab.

Exercise 2: Make Multiple Commits

  1. Add four titles to the README.md
    # introduction
    # directory structure
    # data and code description
    # usage
  2. Commit with meaning description of the change
  3. Add a placeholder text in the subsection “introduction”
  4. Commit with meaning description of the change
  5. Add a placeholder table in the subsection “data and code description”
  6. Commit with meaning description of the change
  7. Add an image in the subsection “introduction”
  8. Commit with meaning description of the change
  9. Push

Goal: Familiarize with commit → push. Learn that multiple commits can be made before changes are pushed.

Exercise 3: View History Online

  1. Go to GitHub / Gitlab → Commits tab
  2. Inspect messages and diffs
  3. Click the directory / folder icon on the right, to explore the repository at different commits.

Goal: Understand how your work appears remotely. Understand that you have a snapshot of your complete repository for every commit.

6. Protecting Secrets

Never commit:

  • passwords
  • API keys
  • database credentials
  • full config.yml

It might happen that you need to access external or private data repositories or databases with credentials. If that is the case, never save your credentials in your r scripts. Instead, you can create a config.yml file in the root directory.

default:
  database1:
    driver: 'RPostgres::Postgres()'
    server: 'server.address.com'
    uid: 'username'
    pwd: 'password'
    port: 5432
  APIKEY:
    key: 'api-key'
    url: 'api.access.point.com'

Then, add the config.yml to .gitignore. This ensures that credentials are not shared in scripts.

Use .gitignore:

config.yml
.Renviron

To use the configurations use the config::get() function.

config::get()
db_credentials <- config::get('database1')
uid <- db_credentials$uid # username 
pwd <- db_credentials$pw # password

Exercise 4: Add sensitive files to .gitignore

  1. Create the above config.yml file in the root of the project directory
  2. Check the Git pane and see if the config.yml file appears
  3. Edit the .gitignore file by adding config.yml and save the changes
  4. Verify that config.yml disappears from the Git pane

Goal: Learn how to keep credentials out of Git. Learn how to use .gitignore.

7. Branches

A branch is a parallel line of development.

Use them for:

  • New features
  • Experiments
  • Bug fixes

Example Workflow

git checkout -b feature-test
git push -u origin feature-test
# work and commit
git checkout main
git merge feature-test

Exercise 5: Create and Merge a Branch

  1. Create a branch in rstudio
  2. Change a file
  3. Commit the changes
  4. Go online and make a merge

Goal: Understand isolated development.

Exercise 6: Merge Conflict

  1. Edit the same line differently on two branches
  2. Try merging

Goal: See conflict markers and resolve them.

8. Versions, Tags, and Releases (Recovering Older Versions)

Git’s ability to “travel back in time” is one of its most powerful features. Users often don’t realize how simple this is — so this section explains it clearly and visually.

8.1 Viewing the Project History

Every commit is a complete snapshot of the repository at that moment. You can explore the entire history using:
- RStudio → Git pane → History
- GitHub → Commits tab
- Terminal → git log --oneline

From the history view, you can inspect:
- Added lines (green)
- Removed lines (red)
- Commit messages
- Who made the change
- When it happened

8.2 Time Travel: Checking Out an Old Version

If you need to revisit a previous state of the project:

git checkout <commit-hash>

This lets you explore the repo as it was at that moment.
You can run code, inspect files, or export them.

⚠️ This puts you in a “detached HEAD” state — a temporary view.
To return to normal:

git checkout main

8.3 Downloading That Old Version (GitHub / Gitlab)

On GitHub / Gitlab:

1. Go to Commits
2. Click the desired commit
3. Choose Browse files at that commit
4. Click Download ZIP

This makes retrieving old versions extremely accessible.

8.4 Tags: Marking Important Versions

Tags are labels you attach to specific commits. They are perfect for marking an important status of the repository. Between two important versions there might be a lot of intermediate small commits. With tags you could mark the more important changes.

They are perfect for:
- “version 1.0”
- “submitted to journal”
- “analysis stable version”
- “pre-CRAN release”
- “dataset used for publication”

Create a tag

git tag -a v1.0 -m "First stable version"
git push origin v1.0

Or create tags via Github / Gitlab.

8.5 Releases (Tags + Documentation)

GitHub / Gitlab lets you turn tags into Releases, which include:

- version notes
- downloadable ZIPs or artifacts
- links to the commit

This is ideal for:
- sharing versions publicly
- reproducible research
- distributing datasets
- training materials

Creating a release

  1. Go to Releases
  2. Click Draft a new release
  3. Select a tag or create a new one
  4. Add notes
  5. Publish

Exercise 7: Explore History

  1. Open Git → History in RStudio
  2. Pick a past commit
  3. Inspect its diff
  4. Find which lines changed

Goal: Understand change tracking.

Exercise 8: Time Travel

  1. Copy a commit hash from the history
  2. Run:
git checkout <hash>
  1. Inspect project at that moment
  2. Return to main:
git checkout main

Goal: Learn to navigate past states.

Exercise 9: Create a Tag

git tag -a v0.1 -m "Initial milestone"
git push origin v0.1

Goal: Mark a reproducible project version.

Exercise 10: Make a Release on Github / Gitlab

  1. Push a tag
  2. Go to Releases → Draft new release
  3. Add notes & publish

Goal: Publish a stable version.

9. Daily workflow

  • Start of the day: pull

  • Commit and push changes throughout the day

  • Make “tags” for significant version changes

  • End of the day: push

    Be careful with:

  • If you make changes in the remote (github / gitlab), make sure to first push local changes

  • If you work with branches, make sure not to make modifications to the branch in which you want to merge (usually “main”)