code-minimap: rendering a source file as a picture in the terminal

A minimap as text art, not as an image

code-minimap describes itself as a high performance code minimap render, and this tool is for generating text minimaps. The output is not a picture in the graphical sense, it is a block-character rendering of the file's structure, produced in the terminal.

The usage example shows the shape of it. A file is given on the command line, with a horizontal and a vertical scale:

$ code-minimap src/core.rs -H 0.6 -V 0.5

and the result is a stack of lines of braille and block characters that trace the shape of the source. The point of the two scale parameters is that a minimap is a thumbnail: the horizontal scale compresses the file along the line axis and the vertical scale compresses it across lines, and the result is a picture whose geometry resembles the code without being legible as code.

The features list is short: small and fast, memory efficient, freely zoomable, and multi-platform support with prebuilt binaries for Linux, macOS, Windows and ARM. The intended use is stated in the first line of the README, and it is a specific one: you can use it to implement an IDE-like minimap plugin for a terminal text editor, and minimap.vim is named as the example.

That framing matters for what the tool is and is not. A terminal minimap is a visual anchor for a scrolling editor, a way to see where you are in a long file at a glance. It is not a code visualisation, not a dependency graph and not a heatmap. The output is decorative in the strict sense, and that is why a renderer can be fast enough to run on every keystroke.

A library with the CLI behind a feature flag

The package manifest is where the design shows, and it is worth reading before you install anything.

There is a library target, named code_minimap with the path src/lib.rs, and a separate binary target named code-minimap with the path src/bin/code-minimap/main.rs. The features section has a default of application, and the comment on that feature is explicit: it is required for building the code-minimap application and should be disabled when depending on code-minimap as a library.

So the CLI is not a thin wrapper bolted onto a library, it is an optional feature of it, and the application feature pulls in clap and clap_complete, the command line parser and its shell completion generator, both of which are also listed as build dependencies because the completions are generated at build time. The completions/ directory in the repository is the output of that.

The runtime dependencies are minimal: anyhow for error handling and itertools, and nothing else. The release profile is tuned for speed, with lto set to true and codegen-units set to 1, both of which trade build time for runtime performance, which is the right trade for a program whose whole purpose is to be fast.

The package also declares a build script, build.rs, which is the mechanism for the completion generation, and the repository carries a rust-toolchain.toml, a .rustfmt.toml and a .pre-commit-config.yaml, so the toolchain, the formatting and the commit hooks are all pinned in the repository rather than left to the contributor.

Install paths for five ecosystems

The distribution story is unusually broad, and it is worth picking the line that matches your platform rather than building from source unless you have a reason to.

On Linux there are three. Arch Linux, from the AUR:

yay -S code-minimap

Alpine Linux, from the testing repository:

apk add code-minimap

Gentoo, from the GURU project repository:

emerge --ask code-minimap

On macOS there is Homebrew:

brew install code-minimap

or MacPorts:

sudo port install code-minimap

On Windows there is scoop, and the extras bucket has to be added first:

scoop bucket add extras
scoop install code-minimap

For any platform, prebuilt binaries for various architectures are on the GitHub releases page, and there is a note worth reading there: if you run into dependency related errors, try the musl version, which is statically linked. That is a fix for a specific class of problem on minimal Linux images where the glibc the binary expects is not the one present.

From source, the package is on crates.io and cargo can install it:

cargo install --locked code-minimap

And if you want the latest version rather than the published one, the README says to clone the repository and run cargo build --release.

Note the --locked flag on the crates.io install. It makes cargo use the exact dependency versions in the lockfile rather than resolving fresh ones, which is the difference between a reproducible build and one that picks up a new patch release of a transitive dependency.

What the benchmarks actually measure

The benchmark section is unusually complete for a small tool, and it is worth reading with the caveats in mind.

The first case is the tool's own source file, src/core.rs, measured with hyperfine using 10 warmup runs:

$ hyperfine -w 10 'code-minimap src/core.rs'
Benchmark #1: code-minimap src/core.rs
  Time (mean ± σ):       0.2 ms ±   0.1 ms    [User: 0.4 ms, System: 0.3 ms]
  Range (min … max):     0.2 ms …   1.1 ms    1560 runs

The second is the whole of the Rust standard library source from release 1.46.0, concatenated into one file with fd and cat, which comes to 1,153,225 lines and 37 MB, and takes 322.7 ms. The third is a synthetic worst case, ten million lines of base64 output from /dev/urandom, 735 MB, at 2.941 s.

The test environment is stated, which is more than most projects do: binary version 0.3.0, Arch Linux x86_64, kernel 5.8.10-arch1-1, and an Intel i9-9900K at 5.000 GHz.

Two caveats apply. The binary measured is version 0.3.0 while the current release is 0.6.8, so these numbers describe an older build and should be read as an order of magnitude rather than a current figure. And the measurements are wall clock on one desktop CPU, so the interesting property is not any absolute millisecond but the shape: a 37 MB source file renders in about a third of a second, and a 735 MB file in under three, which is roughly linear in input size. That linearity is what makes it usable as something you run on every buffer change.

Also worth noting is that these are the project's own numbers. They come from the README, they are not independently verified, and the hardware is a single well specified machine.

How it becomes an editor plugin

The relationship with the editor is the part that determines the architecture, and the README is explicit about it: the tool is for generating text minimaps, and you can use it to implement an IDE-like minimap plugin for a terminal text editor, with minimap.vim given as the example, and linked as a related project and described as a blazing fast minimap for vim.

The division of labour is clean. The Rust program reads a file and writes a rendered picture to standard output, and the editor plugin is responsible for showing it in a window, keeping it in sync with the buffer, and updating it as the file changes. That is why the tool takes a path argument and nothing else, and why the two scale parameters are the only things you need to get a usable picture.

This shape also explains the performance focus. If the renderer is invoked on every keystroke, its cost is paid continuously and its startup time counts as much as its throughput. A small binary with no runtime dependency, built with fat LTO and a single codegen unit, is a reasonable answer to that, and so is the availability of statically linked musl builds for the case where the startup cost is dominated by dynamic linking.

The library target exists for the same reason. Rather than shelling out, an editor integration can link the renderer and call it directly, which removes process startup from the loop entirely. The repository's examples directory contains simple.rs and write_to_string.rs, which suggests the library can produce either a rendered string or a direct write.

Where code-minimap is the wrong tool

The first limitation is that the output is text art in a terminal, which means it is unavailable to anyone whose interface is graphical, and it is limited by the cell size of the terminal. A modern editor with a real minimap pane, or an IDE, does the same job with a rasterised image that scales to the panel and can be clicked. If your development happens in a graphical editor, this tool is decoration you cannot use.

The second limitation is the input model. The tool renders a file from disk, so the file has to be written before it can be minimapped. In an editor plugin that means the buffer must be flushed to disk, or the plugin must feed the renderer some other way, and a plugin that minimaps unsaved buffers needs the library path rather than the CLI. The README does not describe how minimap.vim handles the unsaved case, and that is the detail that would decide whether an integration is pleasant.

The third limitation is that the picture is not readable. A minimap is a thumbnail, and this one is a thumbnail in terminal cells, so the horizontal scale parameter of 0.6 means each character covers more than one column of the source, and the vertical scale of 0.5 means each character row covers two lines. Reading anything from it is not the point, and expecting structure to be legible at those scales is a misreading of what the tool produces.

The real alternative, and the one most people should compare against, is the minimap your editor already has, or a graphics-mode minimap in a terminal emulator that supports images, which several do. The difference in approach is that code-minimap needs no graphics stack, no font metrics, no image protocol support and no image decoder, and it works over SSH in a plain terminal, which is exactly the case where the graphical options are unavailable. That is a narrow advantage, and if you are not in that case, the built-in minimap is better. The remaining alternative is to write your own renderer against the library, which is the point of the library target, and which is a reasonable thing to do if you want a minimap in a terminal emulator that can do real graphics.

Editorial conclusion

Adopt code-minimap if you want an IDE-style minimap in a terminal editor and are willing to depend on a Rust binary, or if you want to embed a minimap renderer in your own tool through the library. Do not adopt it if you need a graphical minimap in a full IDE, since the output is text, and do not expect it to scale past the large-file case the benchmarks cover, because the whole file is parsed and rendered. Before you integrate it, read the usage output rather than the README flags, since the tool exposes detailed options through --help, and check that the zoom parameters suit your terminal, because the rendering resolution is set in characters and the picture is not meant to be read literally.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. wfxr/code-minimap on GitHub