VTerm

A terminal emulator that makes your life easier.

Note: We are still in beta version. Core features are pretty stable; more features to come, code clean-up and documentation todo.md.

Table of contents

• VTerm
  • Features
  • Getting Started
    • Ubuntu [20.04, 18.04]
    • Debian [10]
    • Fedora
    • Arch
  • Building VTerm
    • Dependencies
    • Building from source
  • Shell Integration
  • Commands and shortcuts
  • Configuration
  • FAQ
    • Is VTerm VTE-based?
    • Is VTerm a fork of Termite?
  • Contributions

Features

• Highly customizable: an easy to write configuration file with various options with sane defaults. [Jump to configuration section]
• Advanced Tabs support:
  • Smart tabs shortcuts e.g. alternate tab, numbered tabs.
  • Configurable tab showing policy.
  • Configurable new tab placement.
  • Configurable new tab directory.
  • Tab bar styling.
• VIM-like keyboard shortcuts: yiw, yy, w, $, visual line and block modes and all the other good stuff, see full list.
• Prompt up/down: ever got lost in a long command output trying to read the previous command? No more! Scroll to previous/next prompt directly.
• Clickable links: see a link or a mailto? Just click it!
• Focus-aware background: configurable background color and transparency based on terminal focus status so it is easy to identify currently focused terminal.
• Bidirectional text support: no more messed-up text that is written in right-to-left languages.
• Well commented & structured code: want to contribute? Feeling an urge to hack your own terminal? Take a look at the code! It was written with community contributions in-mind.
• Lots more: fullscreen, zoom-in/zoom-out, support for terminal images (i.e. using Überzug).

Getting Started

Ubuntu [20.04, 18.04]

First install meson >= 0.50.0 [Install].

Then:

(
# Install dependencies
sudo apt-get install -y cmake pkg-config libgtk-3-dev libpcre2-dev \
    libglib3.0-cil-dev libgnutls28-dev build-essential 

# clone VTerm
git clone --recursive https://github.com/man9ourah/vterm.git;
cd vterm;

# Ubuntu 20.04 have the new fribidi in apt
if [ "$(lsb_release -sr)" == "20.04" ]; then
    sudo apt-get install -y libfribidi-dev

    # Build & install VTerm without rpath set
    meson build && cd build && sudo ninja install;
else
    # Install fribidi
    git clone https://github.com/fribidi/fribidi .deps/fribidi;
    pushd .deps/fribidi;
        meson -Ddocs=false build;
        cd build;
        sudo ninja install;
    popd;

    # Build & install VTerm with rpath set
    meson -Dset_install_rpath=true build && cd build && sudo ninja install;
fi
)

For Ubuntu 16.04 and before, you will face issues with old dependencies versions [Please submit a PR if you have successfully installed VTerm in Ubuntu 16.04 or older versions].

Debian [10]

First install meson >= 0.50.0 [Install].

Then:

(
# Install dependencies
sudo apt-get install -y cmake pkg-config libgtk-3-dev libpcre2-dev \
    libglib3.0-cil-dev libgnutls28-dev build-essential libfribidi-dev;

# clone VTerm
git clone --recursive https://github.com/man9ourah/vterm.git;
cd vterm;

# Build & install VTerm
meson build && cd build && sudo ninja install;
)

Fedora

TODO: [Please contribute if you installed on Fedora]

Arch

TODO: [Please contribute if you installed on Arch]

Building VTerm

Dependencies

• meson >= 0.50.0 Install.
• ninja Install.
• pkg-config Install.
• cmake Install.
• GTK3 Install.
• PCRE2 Install.
• GNU Fribidi Install (Optional): Used for bidirectional language support. You can disable by adding -Dvte-vterm:fribidi=false to meson.
• GNUTLS Install (Optional): Used to encrypt data written to the disk, i.e. terminal buffer. You can disable by adding -Dvte-vterm:gnutls=false to meson.
• Systemd Install (Optional): Disabled by default; used to spawn child shell processes into its own systemd scopes. You can enable by adding -Dvte-vterm:_systemd=true to meson.

You think this list is incomplete? Please make a PR or open an issue.

Building from source

Having all dependencies met, you just need the following line for building and installations:

meson build && cd build && sudo ninja install

This will build VTerm in build/ and install only 4 files to your system:

• vterm to /usr/local/bin.
• vte.sh to /usr/local/etc/profile.d/.
• vte-urlencode-cwd to /usr/local/libexec.
• vte-spawn-.scope.conf to /usr/local/lib/systemd/user/vte-spawn-.scope.d.

You can change the prefix /usr/local using meson options.

You can disable Fribidi, GNUTLS, and Systemd dependencies using meson options as well. For example, to disable Fribidi the meson configure command will be:

meson -Dvte-vterm:fribidi=false build

Shell Integration

The meson installation will install the file vte.sh to /usr/local/profile.d/ by default. This script needs to be sourced at the beginning of your shell sessions for the integration to work. You can either move /usr/local/etc/profile.d/vte.sh to /etc/profile.d if you are using a login shell and your environment automatically source the files under that directory, or simply add the following line somewhere in your ~/.zshrc or ~/.bashrc files:

source /usr/local/etc/profile.d/vte.sh

VTerm uses a shell integration script for mainly two things:

• Marking command prompts lines for easier scrolling.
• Tracking current working directory for new tab opening.

You can simply ignore the shell integration without affecting your terminal behavior, but you will miss out on those two features.

Commands and shortcuts

VTerm have three modes:

• Insert mode. The default mode.
• Normal mode. User input is not forwarded to child application, and most commands work here. This is like Normal mode in VIM, and Copy mode in tmux.
• Visual modes. Three visual modes available. Enables you to select characters, blocks, or lines.

General Shortcuts

Keyboard shortcuts that works in all modes:

Key	Function
Tabs
ctrl-shift-t	Opens a new tab
ctrl-shift-l	Switch to the next tab
ctrl-pageDown
ctrl-shift-h	Switch to the previous tab
ctrl-pageUp
ctrl-shift-^	Switch to the last tab (alternate tab)
ctrl-shift-1	Swtich to the first tab (quick access)
ctrl-shift-2	Switch to the second tab (quick access)
ctrl-shift-3	Switch to the third tab (quick access)
ctrl-shift-w	Close current tab
ctrl-shift-k	Move tab to the right
ctrl-shift-pageDown
ctrl-shift-j	Move tab to the left
ctrl-shift-pageUp
Copy and search
ctrl-shift-c	Copy selected text
ctrl-shift-v	Paste text
ctrl-shift-?	Search up
ctrl-shift-/	Search down
ctrl-shift-n	Next search result
Navigation
ctrl-shift-o	Scroll one prompt up
ctrl-shift-i	Scroll one prompt down
shift-pageUp	Scroll one page up
shift-pageDown	Scroll one page down
Mode switching
ctrl-shift-space	Switch to normal mode
ctrl-shift-Left	Switch to visual mode and select one char left
ctrl-shift-Right	Switch to visual mode and select one char right
Zoom
ctrl-shift-+	Zoom-in
ctrl--	Zoom-out
ctrl-=	Scale font size back to 1
F11	Full screen

Normal & Visual Modes Commands

Commands for normal and visual modes. This in addition to arrows and hjkl movements.

Key	Function
Mode switching
v	Visual mode
V	Visual line mode
ctrl-v	Visual block mode
Enter	Exit one mode backword
q
Esc
Navigation
H	Go to top of screen
L	Go to bottom of screen
M	Go to middle of screen
w	Move one word to the right
ctrl-Right
b	Move one word to the left
ctrl-Left
W	Move one statement to the right
shift-Right
B	Move one statement to the left
shift-Left
e	Move to the end of current word
E	Move to the end of current statement
Home	Go to beginning of line
0
End	Go to end of line
$
Yanking
yy	Copy current line
yw	Copy from this char to end of word
yiw	Copy this whole word
yW	Copy from this char to end of statement
yiW	Copy this whole statement
Search
?	Search up
/	Search down
n	Next search result
N	Previous search result

VTerm was built so that it is easy to add more commands & shortcuts. If you have an idea for a new command, please let us know.

Configuration

VTerm is very configurable. The default configuration file contains all possible configuration options as well as their default values. We suggest copying the default config file to ~/.config/vterm/vterm.conf and edit it there. Simply reopen VTerm to update the configuration options.

Tab bar Styling

VTerm wants you to be able to customize everything! Although this feature is not user friendly (yet), you can customize the tab bar style using a CSS file that will be applied to the tab bar GTK object. To give an example, see notebook_style.css. The result of which is:

FAQ

• Is VTerm VTE-based?

Yes, but not the upstream vte. VTerm uses its own version of vte to add support for lots of features like the command prompt marking and the normal & visual modes cursors. However, unlike most (all?) other vte based terminals, VTerm is statically linked to its own version of libvte; so it is not a runtime requirement. This makes it much easier to install in systems where other vte-based terminals exists.

• Is VTerm a fork of Termite?

Termite is great! But no, VTerm is not a fork of Termite. VTerm definitely was inspired by it, but the two do things in totally different manners.

1. Unlike Termite, VTerm's version of libvte is much more integrated into the new features of VTerm. Termite's version of libvte is only exposing inner states functions, which is limiting at best.
2. Unlike Termite, VTerm is statically linked to libvte.
3. Unlike Termite, VTerm provides much more customizability.
4. Unlike Termite, VTerm provides tab support.
5. Unlike Termite, VTerm is written with community contributions in mind.

Contributions

ALL Contributions are welcomed! However, to better coordinate the efforts, please take a look at the todo.md file and let us know by opening an issue. If you are reporting a bug, please open an issue.

Author

Mansour Alharthi [Email][Twitter].