Alacritty, the OpenGL terminal emulator written in Rust, has landed support for scrollback in version 0.2.0! At the same time, scrolling performance has improved, and we are beginning to version our releases and maintain a changelog.

This post provides instructions for getting v0.2.0 of Alacritty, adding configuration needed for scrollback, benchmarks for the scrolling feature, and a brief discussion of versioning Alacritty.

Overview

• Compile and Configure Alacritty v0.2.0
• Check out benchmarks of scrolling and alt-screen performance
• Alacritty versioning
• Upcoming features
• Giving thanks to a few people who had an outsized impact on delivering a quality version of scrollback.

Getting Alacritty with Scrollback

To get started with scrollback, you’ll need Alacritty v0.2.0 and some additional configuration.

Compiling v0.2.0

The officially supported way to get Alacritty is, for now, building from source. Please follow the instructions in the README and make sure to git checkout v0.2.0.

Update your configuration

There’s two changes you’ll need to make to your configuration. First, add the scrolling section which includes things like how much history to store, how many lines to scroll per mouse wheel interval, and whether to automatically return to the most recent lines when new data is output.

scrolling:
  # How many lines of scrollback to keep,
  # '0' will disable scrolling.
  history: 10000

  # Number of lines the viewport will move for every line
  # scrolled when scrollback is enabled (history > 0).
  multiplier: 3

  # Faux Scrolling
  #
  # The `faux_multiplier` setting controls the number
  # of lines the terminal should scroll when the alternate
  # screen buffer is active. This is used to allow mouse
  # scrolling for applications like `man`.
  #
  # To disable this completely, set `faux_multiplier` to 0.
  faux_multiplier: 3

  # Automatically scroll to the bottom when new text is written
  # to the terminal.
  auto_scroll: false

Next, there are a number of new keybinding actions available.

• ScrollPageUp - Scroll up 1 viewport worth of lines
• ScrollPageDown - Scroll down 1 viewport worth of lines
• ScrollToTop - Scrolls to the oldest line in history
• ScrollToBottom - Scroll back to the origin, typically a shell prompt
• ClearHistory - Clear scrolling history outside of the current screen

For convenience, you can just paste in the following bindings to the key_bindings section of your configuration,

  - { key: PageUp,   mods: Shift,   action: ScrollPageUp   }
  - { key: PageDown, mods: Shift,   action: ScrollPageDown }
  - { key: End,      mods: Shift,   action: ScrollToBottom }
  - { key: Home,     mods: Shift,   action: ScrollToTop    }

and these optional key-bindings to match iTerm and Terminal.app behavior on macOS.

  - { key: K,        mods: Command, action: ClearHistory   }
  - { key: K,        mods: Command, chars: "\x0c"          }

Benchmarks

A big concern from the community around introducing scrollback into Alacritty was that performance would suffer. To guide our development efforts, we wrote a tool called vtebench which is a tool for benchmarking terminal emulators. Using vtebench, we are able to test use cases like scrolling through a large text file, scrolling through a large text file as if in vim or tmux, and also processing large amounts of screen updates as in vim or tmux.

In the following sections are data for each of these three benchmarks with some commentary around what exactly the benchmark is exercising. Each benchmark is presented twice, once for a macOS environment and once for a Linux environment and comparing against common terminals of the respective platform.

The hardware used for generating the data in these benchmarks was

• macOS - An early 2015 MacBook Pro with 3.1 GHz Intel Core i7 and Intel Iris Graphics 6100.
• Linux - i7-6700k/R9 390 running X11/i3+compton with Mesa version 18.1.6 and Linux 4.18.3.

In all cases, the vtebench output was piped into a file, and then “executed” by running time cat <file>. Three runs were made to warm caches, fill buffers, etc. The reported numbers are the result of averaging 10 runs following the three warm-up runs. The exact vtebench commands used to generate test files follow charts at the end of each section.

Note that through all of the benchmarks, Alacritty is able to maintain a buttery smooth 60fps.

Scrolling

The scrolling benchmark is essentially the yes command which outputs a repetitive series of y\n over and over. This data allows us to zero in on performance of adding new lines of output and managing the scrollback buffer.

Alacritty is over 9x faster than the next terminal emulator on macOS for scrolling, and performance has improved 5x since the previous release.

Alacritty is about 2.5% faster than the next terminal emulator on Linux for scrolling, and performance has improved by 31% since the last release.

The vtebench invocation for generating the test file is as follows.

vtebench -w $(tput cols) -h $(tput lines) -b 10000000 \
    scrolling > bench.bin

Scrolling in Region

This benchmark is evaluating scrolling performance within a “scrolling region”. Even if you haven’t heard this term before, you’ve almost certainly experienced a scrolling region when working in a terminal. tmux uses a scrolling region to keep its status bar fixed while terminal output flows. Similarly, vim uses a scrolling region to keep its status bar fixed while scrolling through a file.

As you can see, scrolling regions are common, and it’s important to keep them performant. This is also a potential performance pitfall since it changes how data is moved around in the screen / scrollback buffer.

Alacritty is over 4.5x faster than the next terminal emulator on macOS for scrolling in a region, and performance has improved by a similar margin since the previous release.

Alacritty is about 1.5% faster than the next terminal emulator on Linux for scrolling in a region, and performance has improved by 30% since the last release.

The vtebench invocation for generating the test file is as follows.

vtebench -w $(tput cols) -h $(tput lines) -b 10000000 \
    scrolling-in-region --lines-from-bottom 1 > bench.bin

Random alt-screen writes

The final benchmark is intended to emulate working within a vim buffer or drawing in a tmux pane. In this scenario, a random location on the screen is selected, a random color is chosen, and some amount of text is drawn, over and over.

Alacritty is about 2.5x faster than the next terminal emulator on macOS for alt screen random writes despite a marginal performance drop due to scrollback.

Alacritty is 62% faster than the next terminal emulator on Linux for alt screen random writes despite a marginal performance drop due to scrollback.

Interestingly, this is the one place where Alacritty performance was reduced compared to the pre-scrollback version. This was a direct result of a trade for a major scrolling performance optimization, and given that our alt-screen write performance is still great, we were happy to accept this trade-off.

The vtebench invocation for generating the test file is as follows.

vtebench -w $(tput cols) -h $(tput lines) -b 50000000 -c \
    alt-screen-random-write > bench.bin

Versioning

Alacritty has historically relied simply on git revisions as our “versioning” scheme. Since launching, Alacritty has found its way into several package managers, and a common problem that packagers have run into is knowing the right time to publish a new version.

We’re beginning to address that today with the v0.2.0 release of Alacritty. Going forward, larger features like scrollback will increment the minor version number; bug fixes, minor improvements, and dependency updates will be incrementing the patch version. This is to say, we’ll be following semver.

Changelog

Maintaining a changelog has been a common request from users, and versioned releases enable us to keep one. We will be following the conventions outlined by keep a changelog.

Upcoming Features

The project is busier than ever before, and there’s a bunch of exciting features coming down the pipeline:

• Support for Windows (#1374) is next on the list. We are looking forward to getting this in-tree ASAP. Thanks @zacps for making this happen!
• Proper underline support and the introduction of strikethrough (#1078) have been a long time in the making. The underline portion of this is particularly exciting since Alacritty currently cheats and draws underscores.
• Glutin and winit upgrades. These updates always manage to fix a bunch of bugs or otherwise improve input and windowing.
• Binaries! With the advent of versioning, the project will start shipping precompiled binaries for popular platforms.
• So much more. There’s a ton of open PRs on the project that have been delayed to make way for scrollback. With scrollback finally shipping, it’s time to play catch-up.

Giving Thanks

There are many people who have had a big impact on Alacritty getting a high quality implementation of scrollback, and I would like to take a moment to thank them.

• @neon64: The work @neon64 did was excellent, and the number of people I’ve seen on Twitter and GitHub claiming they use that branch every day is a testament to that. Ultimately, I felt a different approach was a better fit for the project, but I can say with great certainty that the final implementation was dramatically improved through the initial pathfinding work done by @neon64.
• @chrisduerr: Chris joined the project nearly a year ago, and he’s had an absolutely massive impact on the project. I’m incredibly thankful to have him as a contributor; he has been extremely active in everything from committing code, maintaining the issue tracker, responding to PRs, and nudging me to actually do some work. On scrollback specifically, Chris has done a ton of work on everything from bug fixes, drilling into performance problems, improving perf through patches, and an absolute ton of testing.
• Everyone in the community who has tested scrollback, participated in issue or PR discussion, or simply registered interest in the feature. The original scrollback issue has over 400 thumbs up which made this one of the most demanded features of all time for the project.
• Finally, I would like to thank you for being patient while this feature baked. OSS is 100% a volunteer effort, and sometimes personal life and work responsibilities take priority. It’s been a long time since scrollback was initially proposed, and now it’s finally landing over 1.5 years since launch. Thank you for your patience in allowing us to deliver a polished and performant feature.

I’m hoping to write about Alacritty a bit more going forward. There’s so much to discuss around future plans, interesting implementation details, feature sketches, and so on. If you’re on Twitter and want to hear about project news as it develops, you can follow @i_am_jwilm.

This post is being discussed on Hacker News and r/rust.

Thank you for reading!