---
title: "Version Control"
date-meta: 2022-12-12
---

Version control helps software teams manage changes to source code over time. Version control software keeps track of every modification to the code in a special kind of database. If a mistake is made, developers can turn back the clock and compare earlier versions of the code to help fix the mistake while minimizing disruption to all team members. Version control systems have been around for a long time but continue to increase in popularity with data science workflows.

RStudio has integrated support for version control. If you are new to version control, see a deeper overview in: [Happy Git and Github for the useR](https://happygitwithr.com/)

## Requirements

RStudio supports the following open source version control systems:

-   [Git](http://git-scm.com/)

-   [Subversion](http://subversion.apache.org/)

To use version control with RStudio, first ensure that Git and/or Subversion tools are installed on your workstation (details below).

Version control is most useful when used with a remote repository. Remote repositories are typically managed by your company or are hosted in the cloud (e.g., [Github](https://github.com/) or [GitLab](https://about.gitlab.com/)). Make sure you have credentials to access these systems. If you only want to learn how to use version control, you can manage a standalone system on your workstation but you will not be able to share code with others.

You should also become familiar with using [RStudio Projects](../code/projects.html) (which are required for version control features to be enabled).

## Installation

Prior to using RStudio's version control features you will need to ensure that you have Git and/or Subversion installed on your system. The following describes how to do this for various platforms.

### Git

Prior to using Git with RStudio you should install it using the appropriate method for your platform as indicated at <https://git-scm.com/download/>.

An excellent resource for learning more about Git and how to use it is the [Pro Git](https://git-scm.com/book/en/v2) online book. Another good resource for learning about git is the [Git Bootcamp](https://help.github.com/articles/set-up-git/) provided by GitHub.

### Subversion

Prior to using Subversion with RStudio you should install it using the appropriate method for your platform as indicated at <https://subversion.apache.org/packages.html>.

An excellent resource for learning more about Subversion and how to use it is the [Red Bean](http://svnbook.red-bean.com/) online book.

## Getting Started

Once a Version Control system has been installed, it needs to be activated on the system by following these steps:

1.  From the **Tools** menu, click **Global Options**

2.  Click on the **Git/SVN** tab

3.  Click **Enable version control interface for RStudio projects**

4.  If necessary, enter the path for the Git or SVN executable where provided. A SSH key can be created or added for SSH if necessary.

![](images/version-control-options.png){fig-alt="A screenshot of the Git/SVN tab in Global Options displaying an active Git executable."}

If you are using RStudio Server, by default RStudio Server will look at the PATH for the first Git executable it finds, and sets that as the default. If you have a specific version that you want to set for all users, the easiest option is to make sure it's the first available on the PATH system-wide.

Alternately, in Posit Workbench (previously RStudio Server Pro/RStudio Workbench), you can set the default Git version system-wide by setting the `git_exe_path` option in your system rstudio-prefs.json file. See here for more:\
<https://docs.posit.co/ide/server-pro/r-sessions.html#customizing-session-settings>\
<https://docs.posit.co/ide/server-pro/session-user-settings.html>

RStudio's version control features are tied to the use of [Projects](../code/projects.html) (which are a way of dividing work into multiple contexts, each with their own working directory). The steps required to use version control with a project vary depending on whether the project is new or existing as well as whether it is already under version control.

### Integrations

Once version control such as Git has been enabled for the current RStudio Project, a few visual elements are added, specifically the **Git/Version control dropdown** and the **Git/Version Control tab**.

::: {.callout-note}
If you've installed Git for version control but the Git pane doesn't display, you may need to perform the steps outlined in the section [Git is installed, but the Git pane doesn't appear].
:::

![](images/rstudio-vcs-pane-labeled.png){fig-alt="A screenshot of the RStudio interface, highlighting the Git tab in the Environments pane."}

The **Git menu dropdown** provides Commit, Pull/Push Branch, History and Project Setup.

![](images/git-drop-down.png){width="350" fig-alt="A screenshot of the git dropdown."}

The **Git tab** within the **Environment pane** provides a number of useful commands such as "Diff", "Commit", the Push/Pull arrows, View history 'clock', or selecting a specific branch.

![](images/git-tab.png){fig-alt="A screenshot of the Git tab in RStudio, showing a few files that can be added to staging."}

Once you are finished with your local work and are ready to Commit your changes, selecting **Commit** in either the **Git** drop-down menu or **Git** tab opens the **Review Changes** pop-up to select files for staging, add a commit message, and eventually push the commit.

![](images/git-commit-pane.png){fig-alt="A screenshot of the Review Changes pop-up, indicating the files for staging and the ability to commit, push and pull changes."}

## Using version control

There are several options for using version control, depending on whether you are starting a new project or working on an existing project.

### Using a directory already under version control

If you have an existing directory which is already under Git or Subversion version control then you can create a new RStudio project for that directory and then version control features will be automatically enabled. To do this:

1.  Execute the **New Project** command (from the Project menu)

2.  Choose to create a new project from an **Existing Directory**

3.  Select the appropriate directory and then click **Create Project**

A new project will be created for the directory and RStudio's version control features will then be available for that directory.

### Creating a new project based on a remote Git or Subversion repository

If you have an existing remote Git or Subversion repository that you want to use as the basis for an RStudio project you should:

1.  Execute the **New Project** command (from the Project menu)

2.  Choose to create a new project from **Version Control**

3.  Choose **Git** or **Subversion** as appropriate

4.  Provide the repository URL (and other appropriate options) and then click **Create Project**

The remote repository will be cloned into the specified directory and RStudio's version control features will then be available for that directory.

### Adding version control to an existing project

**Directions for remote repositories**

Subversion directories are always paired with an external repository, so cannot be configured for version control without also configuring the external connection. In addition, we recommend that Git repositories always be configured with a remote repository in order to protect your data and maintain a separate backup.

If you have an existing directory that you want to add version control to, you should consult the documentation for Git or Subversion concerning how to initialize a repository (both local commands as well as commands required to connect it to a remote server). See the resources linked above for more on connecting your project to a remote repository.

Once you've configured your project with your repository, RStudio will detect that the project has been added and RStudio's version control features will then be available for that directory.

**Directions for Git (local)**

Git repositories can be created in purely local mode (if for example you want to track changes locally but aren't concerned with collaborating and/or syncing between multiple workstations). To add a git repository to an existing project:

1.  Execute the **Project Options** command (from the Project menu)

2.  Choose **Version Control** options

3.  Change the version control system from (None) to **Git**

4.  Confirm that you wish to initialize a new Git repository

A Git repository will be created for the project and you'll be prompted to restart RStudio to enable version control features for the project.

## Additional Topics

### Using the Shell

RStudio provides an interface to the most common version control operations including managing changelists, diffing files, committing, and viewing history. While these features cover basic everyday use of Git and Subversion, you may also occasionally need to use the system shell to access all of their underlying functionality.

RStudio includes functionality to make it more straightforward to use the shell with projects under version control. This includes:

-   On all platforms, you can use the **Terminal** to open a new system shell with the working directory already initialized to your project's root directory.

-   On Windows when using Git, the Shell command will open Git Bash, which is a port of the bash shell to Windows specially configured for use with Git for Windows (note you can disable this behavior and use the standard Windows command prompt instead using Options -\> Version Control).

-   On Windows when using Subversion, RStudio opens a shell with a PATH configured to use a version of ssh.exe which ships with RStudio (required for svn+ssh connections, see below).

-   When running over the web, RStudio provides a web-based shell dialog.

### SSH

Version control repositories can typically be accessed using a variety of protocols (including http and https). Many repositories can also be accessed using SSH (this is the mode of connection for many hosting services including GitHub and R-Forge).

In many cases the authentication for an SSH connection is done using public/private SSH key pairs. This type of authentication requires two steps:

1.  Generate a public/private key pair

2.  Provide the public key to the hosting provider (e.g. GitHub or R-Forge)

To make working with SSH key pairs more straightforward the RStudio Version Control options panel can be used to both create new SSH public/private key pairs as well as view and copy the current SSH public key.

Linux and Mac OSX both include SSH as part of the base system. Windows 11 also includes SSH as an optional Windows component, as does the standard Windows distribution of Git (Git for Windows, referenced above).

### Git Commit Signing

Git commit signing is a process used to verify the authenticity and integrity of commits within a Git repository. The **Git/SVN** Global Options pop-up in RStudio includes a **Sign git commits** check box. When it is selected, git will attempt to sign all future commits.

If commit signing is globally enabled via `git config --global commit.gpgsign true` it is not necessary to select the check box.

::: {.callout-important}
You are responsible for configuring git commit signing and ensuring the associated key is unlocked. Otherwise, you will receive an error if you attempt to sign a commit via the **Review Changes** pop-up. Please consult the git documentation for details on how to configure commit signing for your platform.
:::

![](images/git-sign-commit.png){fig-alt="A screenshot of the Global Options pop-up, highlighting the Sign git commits check box."}

## Troubleshooting

### Git is installed, but the Git pane doesn't appear

The Git pane may not display if you're working in a folder that your user does not have ownership of, such as a shared project. This is due to a security feature in git `2.35.2` that disables git repos created in directories the user does not own. You can verify that this is blocking the Git pane from displaying by submitting a git command in the terminal:

``` bash
$ git status
fatal: detected dubious ownership in repository at '/home/posit-user/my-project-folder'
To add an exception for this directory, call:

        git config --global --add safe.directory /home/posit-user/my-project-folder
```

You can mark the offending directory as safe by following the suggested action above and then closing and re-opening the project in RStudio.

Additionally, the Git pane will not appear if Git is not activated for the current project in the project options. To enable Git for the project:

1.  Open the Tools menu and select Project Options.

2.  Navigate to the Git/SVN tab.

3.  In the dropdown field labeled Version control system, change the selection from (None) to Git.

4.  Restart RStudio and check if the Git pane appears.
