TerminalView

THIS PLUGIN IS DEAD!

I am no longer using Sublime Text and do not have the time to support this plugin. There is a new alternative called Terminus (https://github.com/randy3k/Terminus) which is active at the time of writing.

A Linux/macOS plugin for Sublime Text 3 that allows for terminals inside editor views.

The plugin uses a pseudo-terminal to start the underlying shell which means it supports

• Interactive applications (less, man, ipython, ssh, etc.)
• Auto-completion
• Terminal shortcuts (ctrl+c, etc.)
• Basically everything you would expect from a terminal

In addition it also supports

• Integration with the Sublime Text build system
• Shell colors (8 color support for now - development for 256 is planned)
• Scrollback history
• Copy/Pasting
• Static syntax highlighting (as an addition to shell colors)
• Integration with other plugins

Note, if you encounter any issues please check the "Common problems" section at the bottom for a solution.

Dependencies

To run this plugin you need

• Linux-based OS
• Sublime Text 3 (build 3092 or newer)
• bash (this is not required but recommended, see "Changing shell" below for details)

Installation

To install from https://packagecontrol.io/packages/TerminalView

1. Open the command palette (ctrl+shift+p by default) and find "Package Control: Install Package"
2. Search for TerminalView and hit enter to install.

To install manually from github run

git clone https://github.com/Wramberg/TerminalView.git $HOME/.config/sublime-text-3/Packages/TerminalView

Usage

Simply bring up your command palette (ctrl+shift+p by default) and search for "Terminal View: Open Bash". This opens a terminal using 'bash -l' as shell. By default there is no keybinding for opening a terminal view but you can bind a key in your keymap to the terminal_view_open command:

{ "keys": ["ctrl+alt+t"], "command": "terminal_view_open" },

which does the same. All configuration for TerminalView is available through the command palette by searching for "Terminal View". Alternatively, it can also be accessed through the menu: Preferences->Package Settings->TerminalView. The configuration includes

• Keybindings
• Settings
• Palette commands
• Color scheme

These are all discussed further in the remainder of this readme.

Keybindings

The following keys are forwarded to the shell by default:

• All single characters and numbers
• All signs (create an issue if some are missing)
• Arrow keys
• home, end, delete, insert, pageup, pagedown
• escape, tab, space, backspace, enter
• Any ctrl+<char> combination except ctrl+k (see below if you want this to go to the shell instead of ST3)
• Any alt+<char> combination
• Any ctrl+<arrow key> combination

Note that ctrl+<sign> combinations are not forwarded as they depend on keyboard layout. The keybindings can be configured through the menu or the command palette.

If some of the keybindings are not working they are probably shadowed by keybindings in your user keymap. To fix this find the missing keybindings in the default keymap and copy them into your user keymap. For example, if you have bound alt+f in your user keymap you need to insert the following in your user keymap:

{"keys": ["alt+f"], "command": "terminal_view_keypress", "args": {"key": "f", "alt": true}, "context": [{"key": "setting.terminal_view"}]},

Similarly, if you want to override some of the default TerminalView keybindings like e.g. ctrl+w move the following into your user keymap

{ "keys": ["ctrl+w"], "command": "close" },

Lastly TerminalView also includes a few utility keybindings:

Shortcut	Description
ctrl + shift + c	Copy the selection/line in the terminal into the clipboard
ctrl + shift + v	Paste the contents of the clipboard into the terminal
alt + mouse wheel up / mouse wheel down	Scroll back/forward in terminal history (only works on Linux - see #28 for details)
shift + pageup / pagedown	Scroll back/forward in terminal history
ctrl + shift + t / n	Open a new file
ctrl + shift + w / q	Close the terminal view
ctrl + shift + up / down / left / right	Move the ST3 cursor (not the terminal cursor)
ctrl + shift + home / end	Move the ST3 cursor to beginning/end of line
escape	If ST3 cursor is located elsewhere than the terminal cursor move it back - otherwise send escape to shell.

Note that standard ST3 keybindings for selection are not shadowed which mean you can use shift + keys for selection in the terminal in case you prefer to use the keyboard. These keybindings do not move the actual terminal cursor however so whenever the terminal is updated the cursor will snap back to its point of origin.

Settings

The settings are available in the menu or through the command palette. The settings include options for adjusting colors, scrollback history and margins (to avoid scrollbars). Simply copy the settings you want to change into your user settings.

Changing shell

If you want to use another shell it is highly recommended to do this through bash with the -c command line argument. You can control the shell command through the cmd argument to the terminal_view_open command. In addition, you can also alter the title of the terminal view to reflect which shell is running.

If you e.g. want to run an IPython shell when hitting ctrl+alt+t, add the following to your keymap file:

{ "keys": ["ctrl+alt+t"], "command": "terminal_view_open", "args": {"cmd": "/bin/bash -l -c /usr/bin/ipython", "title": "Terminal (IPython)"}},

If you really want to avoid using bash you can also run your shell directly:

{ "keys": ["ctrl+alt+t"], "command": "terminal_view_open", "args": {"cmd": "/usr/bin/ipython", "title": "Terminal (IPython)"}},

but this is experimental. Some future development regarding this is planned, but at the moment only bash is tested.

When you are done you can close the terminal by closing the view (ctrl+shift+q or ctrl+shift+w as default) or exiting the shell (by e.g. hitting ctrl+d).

Palette Commands

Additional palette commands can be added through the menu or the command palette. These are simply included as an alternative to keybindings.

Color scheme

The color scheme is used for both dynamic coloring (colors set by the shell) and static coloring (colors set by syntax highlighting). The color scheme itself can be tweaked by copying the default color scheme into the user color scheme file. Both of these files are available in the menu or through the command palette.

Syntax highlighting

The plugin supports user provided syntax highlighting for static coloring. To use this feature create a <name>.sublime-syntax file in your Packages/User folder. The packages folder can accessed through the menu: Preferences->Browse Packages. The content of the file depends entirely on your needs - see https://www.sublimetext.com/docs/3/syntax.html for details. As an example consider the following which highlights the prompt in bash.

%YAML 1.2
---
name: TerminalViewBash
hidden: true
file_extensions:
  - terminal_view
scope: text.terminal_view
contexts:
  main:
    - match: '\w+@[A-z,\-_]+(?=:)'
      scope: terminalview.black_green
    - match: '([A-z,\-_/~0-9.]+\$)'
      scope: terminalview.black_blue

The matching could be improved upon but it will do for the purpose of this example. Note that the scope names are chosen so they match with scopes that are already defined in the color scheme. To change the color scheme see the "color scheme" section above. In this example the syntax file was saved as bash.sublime-syntax under the Packages/User folder. To use it when opening a bash terminal pass it to the terminal_view_open command with the syntax argument:

{ "keys": ["ctrl+alt+t"], "command": "terminal_view_open", "args": {"cmd": "/bin/bash -l", "title": "Bash Terminal", "syntax": "bash.sublime-syntax"}},

There are currently no syntax-files provided with the plugin so users must create their own. Note that any colors set by shell (except the black/white default) override colors set by the syntax highlighting.

Project switching and ST3 startup

When switching projects or (re)starting ST3 the plugin restarts all terminals views. Unfortunately, there is no obvious way of restoring earlier sessions so the views are completely reset.

Integrating with Sublime Text build system

In a Sublime Text build system, you can use the terminal_view_exec command as a "target" key. This allows you to parse input to the command you are running which is not possible in the standard build system.

For example, consider this .sublime-project:

{
  "build_systems":
  [
    {
      "name": "My Build",
      "shell_cmd": "c++ program.c -o program",
      "working_dir" "$project_path"
      "variants":
      [
        {
          "name": "Run program",
          "shell_cmd": "./program",
          "working_dir": "$project_path"
        }
      ]
    }
  ],
  // Irrelevant code omitted
}

When you click on Tools -> Build With... in the menu, you may select the My Build - Run program variant. This opens an output panel and runs your program. Unfortunately, if the program requires input from the user it cannot be provided. To solve this you can change the variant to:

{
  "name": "Run program",
  "target": "terminal_view_exec",
  "shell_cmd": "./program",
  "working_dir": "$project_path"
}

This runs your program inside a TerminalView instead where you can interact with it.

Integration with other plugins

TerminalView supports integration with other plugins through the terminal_view_send_string and terminal_view_exec commands. The former can be used to send a string to a running terminal while the latter opens a new terminal. For example, to run 'ls' in a terminal that is already open run

window.run_command("terminal_view_send_string", {"string": "ls\n"})

To run a command in a new terminal run

window.run_command("terminal_view_exec", {"cmd": "a.out"})

For details refer to the source code for now.

List of plugins that integrate with TerminalView

The following is a list of known plugins that integrate with TerminalView.

• SendCode by randy3k (https://github.com/randy3k/SendCode)
• ShellVE by bfelder (https://github.com/bfelder/ShellVE)

Common problems

List of common problems you may encounter when using this plugin.

A keybinding is not working even though it is listed in the keybindings section

This is most likely because you have the key bound to something else in your user keymap file. To make it work find the missing keybinding in the TerminalView keymap and copy it to your user keymap. For details see the keybindings section above.

The terminal is responsive but acts weird (prints weird sequences, cursor located in the wrong place, etc.)

Ensure you do not have a bash_profile file or similar that changes the value of the TERM environment variable. This is set to "linux" by the plugin and must stay that way. You can check it by calling env | grep TERM inside the terminal view in ST3. If the TERM value is correct feel free to open an issue for further investigation.

The terminal is sluggish and/or uses a lot of memory

You may have other plugins that conflict with TerminalView. TerminalView does a lot of modifications to the buffer which can conflict with plugins like e.g. GotoLastEditEnhanced. In this particular case a history of all modifications are saved causing unbound memory usage. Please test TerminalView in isolation to see if the issue persists.

Acknowledgments

The pyte terminal emulator (https://github.com/selectel/pyte) is an integral part of this plugin and deserves some credit for making this plugin possible.

During development the SublimePTY plugin (https://github.com/wuub/SublimePTY) was a good source of inspiration for some of the problems that occurred. You can probably find a few bits and pieces from it in this plugin.

For testing stubs and general test structure the Javatar plugin (https://github.com/spywhere/Javatar) was a good point of origin.