Support

Using the RStudio Terminal

Follow

This feature is currently only available in RStudio preview, 1.1.331 or higher.

Introduction

The RStudio terminal provides access to the system shell from within the RStudio IDE. It supports xterm emulation, enabling use of full-screen terminal applications (e.g. text editors, terminal multiplexers) as well as regular command-line operations with line-editing and shell history.

There are many potential uses of the shell including advanced source control operations, execution of long-running jobs, remote logins, system administration of RStudio Servers, and the aforementioned full-screen terminal programs.

This article does not attempt to cover fundamentals on when and how to use a system shell. Instead, it focuses on the features, design, options, and limitations of the RStudio terminal feature itself.

Note, unlike most RStudio features, the nature of the terminal leads to several platform-specific differences. These primarily break down into two categories: Windows, and everything else (Mac, Linux, and Server). Appendix A provides a summary.

Getting Started

The Terminal tab is next to the Console tab. Click on the Terminal tab and a new terminal session will be created (if there isn't one already).

  • If the tab isn't visible, show it via Shift+Alt+T (Tools->Terminal->Move Focus to Terminal).
  • The full list of terminal-related RStudio commands and keyboard shortcuts is in Appendix B. Most terminal-related commands can be found on the Terminal dropdown menu in the terminal pane, and on the Tools->Terminal menu.

Here's a terminal with the output of simple command output:

2017-08-07-1_1_term-simple.png

The visual appearance of the terminal is controlled via the Tools->Global Options->Appearance settings. 

The xterm emulation enables use of full-screen programs. Here is Emacs running (after changing the RStudio Editor Theme to Merbivore):

2017-08-11_11-41-21-emacs.png 

Multiple Terminals

RStudio supports multiple terminal sessions. To start another terminal session, use the New Terminal command on the Terminal dropdown menu, or Shift+Alt+R.

2017-08-11_13-53-02-dropdown-new-v2.png

Each terminal session is independent, with its own system shell process and buffer. Switch between them by (1) using the arrows next to the drop-down menu, (2) clicking on the terminal's name in the drop-down, or (3) using the Previous Terminal/Next Terminal drop-down menu commands. The dropdown button shows the name of the currently selected terminal session ("Terminal 3" in the following screenshot):

 2017-08-11_13-57-17-nav-v2.png

Terminal Names

Terminal sessions have a default name, "Terminal 1", "Terminal 2", and so on. Rename the current terminal via the Rename Terminal command on the drop-down. For example, renaming "Terminal 3" to "Remote Session" in the previous example gives this:

2017-08-11_14-05-50_v2.png

Thus, in your workflow, you can create multiple terminals and give them meaningful names to simplify navigation. A collection of named terminals, or "terminal set", is generally associated with an RStudio project. For more details, see Terminal Architecture and Lifetime.

An alternative (or complementary) approach is to use a terminal multiplexer as described in Advanced - Using Tmux or Screen.

Execute in Terminal

When editing files in the RStudio editor, any selection (or the current line if nothing is selected) can be sent to the active terminal via Ctrl+Alt+Enter (also Cmd+Alt+Enter on the Mac). If a single-line was sent to the terminal the cursor will advance automatically to the next line, allowing single-stepping.

In following example, a simple Python source file was loaded, a Python interpreter started in the current terminal, and Ctrl+Alt+Enter used to step through the script:

2017-08-11-python.png

If a shell file is being edited (*.sh), Ctrl+Enter (plus Cmd+Enter on Mac) can be used to single-step, as can the Run toolbar button. This will also work on Windows, but no check is done that the shell-type loaded in the active terminal session matches the commands being sent.

2017-08-11-shell.png

Note that the Run Script button does the same as prior versions of RStudio, and will save and run the entire script via system() in the R Console. This button does not appear in Windows.

Busy Terminals

Programs running in a terminal do not block the rest of the RStudio user-interface, so work can continue working in RStudio even when one or more terminal sessions have a child process running.

A terminal with child processes is considered busy by RStudio, and will have (busy) next to its name, and the close [x] changes to a stop button:

2017-08-11_15-sleep.png

If there are busy terminal sessions, trying to exit RStudio (or any other operation that will stop the current R session) will give a warning. Proceeding will kill the running processes. Here's an example of trying to quit RStudio for Windows, with a busy PowerShell terminal session:

2017-08-11_quit.png

Important: on the Windows Desktop IDE, only terminal sessions using Command Prompt or PowerShell can do "busy detection". On Git-Bash or WSL (Windows Subsystem for Linux), terminals will never report as being busy, and thus there are no warnings about killing these even if they have processes running.

Closing Terminal Sessions

To close a terminal session, use the Close Terminal command on the Terminal dropdown menu, click the [x] on the far-right of the Terminal pane toolbar, or type exit from within the shell itself.

As discussed earlier, if a terminal is currently busy, the [x] changes to a stop button.

On all versions of RStudio except Windows Desktop, clicking the stop button will trigger the Interrupt Current Terminal command, sending an interrupt to the terminal; this may close the currently running program (the program itself decides what to do when receiving an interrupt), but will not close the terminal. On Windows, the stop button does not do anything.

Finally, if the terminal feature it not useful to your workflow, you can remove the tab altogether by clicking the [x] on the Terminal tab itself. This will close all running terminal sessions, including any custom-named terminal sessions. Subsequent instances of RStudio will not show the Terminal tab: to bring it back, use Shift+Alt+T (Tools->Terminal->Move Focus to Terminal).

Terminal Buffer

The terminal buffer keeps the last 1000 lines of output when running non-full-screen terminal programs. You can scroll through this buffer using the scrollbars (via the mouse) or a mouse-wheel if your system supports it. Full-screen programs typically have their own built-in buffers and navigation conventions.

Clearing the display with the native shell command (e.g. clear for a Posix-style shell, cls for a Windows Command Prompt, or Clear-Host for PowerShell) will only clear the visible portion of the buffer. To clear the entire buffer, use Ctrl+L when focus is in the terminal.

The mouse can be used to select text in the terminal so it can be copied & pasted elsewhere.

To send the entire terminal buffer to a new RStudio editor buffer, use the Copy Terminal to Editor command on the terminal drop-down menu.

Advanced - Terminal Architecture and Lifetime

Process Model

When a terminal session is started, it launches a shell process (e.g. bash).

This shell process runs as a child process of the R session process (rsession / rsession.exe) of the current RStudio instance.

This has an important implication: if the R session is suspended, closed, and/or restarted then the terminal shells, and their child processes, will be killed. This is why RStudio warns before this happens as described above in Busy Terminals.

In an RStudio Server environment, the terminal shells are therefore running under the same user account, and with the same privileges, as the R session, all of which takes place on the server and not on the device where the web browser is running. The security of those terminal shells is wrapped within the same security model as the R session.

On a desktop RStudio IDE, the terminal shells are running locally, with the same rights as user who launched RStudio, but they are running as children of the rsession process, the same as on an RStudio Server environment. This may be changed in a future release to optimize the performance and behavior of the terminal feature on desktop IDEs.

Terminal Persistence

RStudio mitigates the terminal's lifetime being tied to that of the R session by saving and restoring several aspects of the terminal session:

  • The list of open terminal sessions, and their Terminal Names.
  • Terminal Buffers (with limits as described)
  • Environment Variables (Mac / Linux / Server only, and does not include shell variables)
  • Current Working Directory (Mac / Linux / Server only)

The persisted terminal data is stored within a folder named console06 (ends with zero-six), beneath the project folder's .Rproj.user, (or for no-project, under ~/.rstudio-desktop, ~/.rstudio, or %appdata%/RStudio-Desktop, as applicable). Within that folder is INDEX001, a json file containing metadata about each terminal session, and separate files for each terminal buffer, and each set of environment variables, each named using the terminal session's internal identifier.

On RStudio Server Professional with multi-session support enabled, the console06 folder is located in a per-session location, instead of a per-project location.

The format and location of these files is subject to change, but knowing their location and purpose can be handy for troubleshooting.

Terminal Restoration

When RStudio starts up, it loads the previously persisted metadata, initially repopulating the dropdown list of known terminals. Terminal shells are not restarted until the user makes a particular terminal session visible. At that point the shell is restarted, and the buffer and environment restored (where supported).

This mechanism will not restore previously running processes other than the terminal shell. If a long-running operation was killed (including full-screen programs) by an action that required stopping the R session, then work within that process could have been lost.

Note: Terminals configured to use Windows Command-Prompt or PowerShell will not have their buffers restored; they will always restart with a clean buffer.

Command history within the shell is handled by the shell; RStudio does not do anything to persist or restore shell command history.

Advanced - Environment Variables

Within a terminal session, the following environment variable is set on all platforms.

  • RSTUDIO=1

The following are only set on Mac, Linux, and Server (shown with example values):

  • RSTUDIO_TERM=C36329F1 (unique id for current terminal)
  • RSTUDIO_PROJ_NAME=mypackage (base name of current project)
  • RSTUDIO_SESSION_ID=E2F866DC (unique id of current r session)

This can be helpful in doing advanced shell customization.

Advanced - Using Tmux or Screen (Mac/Linux/Server)

Terminal multiplexers such as tmux or screen can facilitate keeping terminal sessions alive even when the R session is restarted (in addition to the other benefits of their use).

RStudio does not directly support these, so it is up to you or your administrator to install and configure (and learn to use) a terminal multiplexer. This section is to give ideas on how you might make use of them with RStudio.

Here is a basic example of configuring tmux to automatically creates a project-specific session in the terminal. You would have to adjust it for your system and desired goals. For example, if you are on a multi-session Server environment, you might want to include the $RSTUDIO_SESSION_ID in the name of the tmux session. Similarly, if you want to combine using tmux and multiple RStudio terminal sessions within an RStudio project, you could also scope the tmux sessions via $RSTUDIO_TERM.

Go to Tools->Global Options->Terminal. Specify a Custom terminal, give the full path to the shell, and have it load a custom startup file (.rstudio-bashrc, contents shown below the screenshot; the name of the file has no special significance).

Under Process Termination, tell the shell not to warn about processes on a whitelist. This lets you restart R without being warned if a shell is running that process. Since tmux will keep the session alive, and RStudio will reconnect when you revisit the terminal tab, the warning is not needed.

2017-08-13-tmux.png

The .rstudio-bashrc file contains the following commands, which will try to attach to a tmux session based on the name of the current project, and create one if it does not exist. It also loads the (Mac-specific) default bash profile. Obviously, adjust to your environment as needed.

source /private/etc/bashrc
tmux attach -t rstudio-$RSTUDIO_PROJ_NAME 2> /dev/null || tmux new -s rstudio-$RSTUDIO_PROJ_NAME

Again, RStudio does not have any special handling of tmux, screen, or any other terminal multiplexer. The example given above, on a multi-user server, could quickly lead to a large number of running tmux sessions. Management of these has to happen independent of RStudio.

Appendix A - Platform Specifics

Here is a summary of the major platform differences, as of RStudio 1.1.331.

Windows Desktop IDE

[+] shows a Windows-IDE specific feature
[x] shows a feature not supported by Windows IDE

  • [+] Choose between Git-Bash, Command Prompt (32 and 64-bit, if available), PowerShell (32 and 64-bit, if available), and Windows Subsystem for Linux (WSL), if available.
  • [x] Custom shell via path to executable
  • [x] "Busy-detection" for Git-Bash or WSL shells.
  • [x] Capture and restore environment variables
  • [x] Sending the pseudo-terminal interrupt via the Stop Sign button.
  • [x] Reloading of terminal buffer for Command Prompt or PowerShell terminals
  • [x] Local terminal echo

Appendix B - Commands and Keyboard Shortcuts

Command Shortcut Drop-down Tools/Terminal Description
Clear Terminal
Buffer

Ctrl+Shift+L

(also Ctrl+L
when terminal
has focus)

Yes Yes Clears full terminal buffer
Close Terminal   Yes Yes Close current terminal
session
Copy Terminal to
Editor
  Yes Yes Send terminal buffer to
a new editor document
Move Focus to
Terminal
Shift+Alt+T No Yes
(also on
View menu)
Move keyboard focus to
Terminal pane
New Terminal Shift+Alt+R Yes Yes Create new terminal
session
Next Terminal Ctrl+Alt+F12 Yes Yes Move forward through
terminal session list
Previous Terminal Ctrl+Alt+F11 Yes Yes Move backwards through terminal session list
Rename Terminal   Yes

Yes

Rename current terminal session
Send Selection to
Terminal

Ctrl+Alt+Enter

(also Ctrl+Enter
when editing a
.sh file)

No No
(on Code menu)
Send text from editor to current terminal
Terminal
Diagnostics
  No Yes Use when requested by RStudio support
Open Shell    

No

(on Tools and Version Control menus)

On Server, same as Move Focus to Terminal,
on Desktop IDE, opens
native terminal app

Appendix C - Options (All Platforms)

Note that many terminal options require starting a new terminal session before it takes effect.

Tools->Global Options->Terminal

  • Connect with WebSockets: terminals will try to use WebSockets to talk to the shell process
  • Close Terminal when shell exits: should a terminal session's buffer be automatically closed when the shell exits?

Tools->Global Options->Appearance

  • Visual appearance of the terminal emulator

Tools-Global Options->Code->Display

  • Blinking cursor: does the terminal cursor blink?

Appendix D - Options (Mac/Linux/Server-Only)

 Tools->Global Options->Terminal

  • New terminals open with Bash (default): shells use "/usr/bin/env bash -l"
  • New terminals open with Custom: specify full path and options for the terminal shell
  • Local terminal echo: immediately echo keyboard input to the terminal, then reconcile with echo from the server; auto-disabled when running a full-screen program
  • Save and restore environment variables: runs a hidden command to capture and preserve terminal environment variables; may need to be disabled with some custom shell configurations, and relies on HISTCONTROL=ignoredups (or ignorespace) to prevent hidden commands from showing up in shell history
  • Ask before killing processes Always (default): if the shell has any child processes, RStudio will warn before killing the shell
  • Ask before killing processes Never: RStudio never warns before killing a shell, even if it has child processes
  • Ask before killing processes Always except for whitelist: Same as "Always" except if one of the processes listed (default is tmux or screen) is running, then same as "Never".

Appendix E - Options (Windows-Only)

 Tools->Global Options-Terminal

  • New Terminals open with Git Bash: Use the git-bash shell found with Git for Windows, if installed
  • New Terminals open with Command Prompt: Use the standard Windows command prompt (both 32 and 64-bit options will be presented if system supports 64-bit)
  • New Terminals open with PowerShell: Use the Windows PowerShell, if available
  • New Terminals open with Bash (Windows Subsystem for Linux): requires 64-bit Windows-10, and must be separately installed

[End of document]

Comments