RStudio projects make it straightforward to divide your work into multiple contexts, each with their own working directory, workspace, history, and source documents.
RStudio projects are associated with R working directories. You can create an RStudio project:
- In a brand new directory
- In an existing directory where you already have R code and data
- By cloning a version control (Git or Subversion) repository
To create a new project use the Create Project command (available on the Projects menu and on the global toolbar):
When a new project is created RStudio:
- Creates a project file (with an .Rproj extension) within the project directory. This file contains various project options (discussed below) and can also be used as a shortcut for opening the project directly from the filesystem.
- Creates a hidden directory (named .Rproj.user) where project-specific temporary files (e.g. auto-saved source documents, window-state, etc.) are stored. This directory is also automatically added to .Rbuildignore, .gitignore, etc. if required.
- Loads the project into RStudio and display its name in the Projects toolbar (which is located on the far right side of the main toolbar)
Working with Projects
There are several ways to open a project:
- Using the Open Project command (available from both the Projects menu and the Projects toolbar) to browse for and select an existing project file (e.g. MyProject.Rproj).
- Selecting a project from the list of most recently opened projects (also available from both the Projects menu and toolbar).
- Double-clicking on the project file within the system shell (e.g. Windows Explorer, OSX Finder, etc.).
When a project is opened within RStudio the following actions are taken:
- A new R session (process) is started
- The .Rprofile file in the project's main directory (if any) is sourced by R
- The .RData file in the project's main directory is loaded (if project options indicate that it should be loaded).
- The .Rhistory file in the project's main directory is loaded into the RStudio History pane (and used for Console Up/Down arrow command history).
- The current working directory is set to the project directory.
- Previously edited source documents are restored into editor tabs
- Other RStudio settings (e.g. active tabs, splitter positions, etc.) are restored to where they were the last time the project was closed.
Quitting a Project
When you are within a project and choose to either Quit, close the project, or open another project the following actions are taken:
- .RData and/or .Rhistory are written to the project directory (if current options indicate they should be)
- The list of open source documents is saved (so it can be restored next time the project is opened)
- Other RStudio settings (as described above) are saved.
- The R session is terminated.
Working with Multiple Projects at Once
You can work with more than one RStudio project at a time by simply opening each project in its own instance of RStudio. There are two ways to accomplish this:
- Use the Open Project in New Window command located on the Project menu.
- Opening multiple project files via the system shell (i.e. double-clicking on the project file).
There are several options that can be set on a per-project basis to customize the behavior of RStudio. You can edit these options using the Project Options command on the Project menu:
Note that the General project options are all overrides of existing global options. To inherit the default global behavior for a project you can specify (Default) as the option value.
- Restore .RData into workspace at startup — Load the .RData file (if any) found in the initial working directory into the R workspace (global environment) at startup. If you have a very large .RData file then unchecking this option will improve startup time considerably.
- Save workspace to .RData on exit — Ask whether to save .RData on exit, always save it, or never save it. Note that if the workspace is not dirty (no changes made) at the end of a session then no prompt to save occurs even if Ask is specified.
- Always save history (even when not saving .RData) — Make sure that the .Rhistory file is always saved with the commands from your session even if you choose not to save the .RData file when exiting.
- Index R source files — Determines whether R source files within the project directory are indexed for code navigation (i.e. go to file/function, go to function definition). Normally this should remain enabled, however if you have a project directory with thousands of files and are concerned about the overhead of monitoring and indexing them you can disable indexing here.
- Insert spaces for tab — Determine whether the tab key inserts multiple spaces rather than a tab character (soft tabs). Configure the number of spaces per soft-tab.
- Text encoding — Specify the default text encoding for source files. Note that source files which don't match the default encoding can still be opened correctly using the File : Reopen with Encoding menu command.
Version control system
Specify the version control system to use with this project. Note that RStudio automatically detects the presence of version control for projects by scanning for a .git or .svn directory. Therefore it isn't normally necessary to change this setting. You may want to change the setting for the following reasons:
- You have both a .git and .svn directory within the project and wish to specify which version control system RStudio should bind to.
- You have no version control setup for the project and you want to add a local git repository (equivalent to executing
git initfrom the project root directory).
- Origin — Read-only display of the remote origin (if any) for the project version control repository.