PISTOL(1)

📦
version 0.6.0 · 2 versions
, in nixpkgs unstable

🎀 NAME 🎀

PISTOL(1) is the manual for pistol — a general purpose file previewer designed for terminal file browsers. bestie, it’s giving “terminal file browser BFF” and we’re obsessed. 💅✨

🌸 INTRODUCTION 🌸

okay so Pistol features native preview support for almost any archive file and text files along with syntax highlighting. no cap. 🫶

the native preview support table is lowkey iconic — the columns are File/MIME Type and Notes on implementation:

now, in case Pistol encounters a MIME type it doesn’t know how to handle natively and you haven’t configured a program to handle it, it’ll print a general description of the file type it encountered. like, it’s not gonna leave you hanging. 🫶

for example, the preview for an executable might be:

ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=a34861a1ae5358dc1079bc239df9dfe4830a8403, for GNU/Linux 3.2.0, not stripped

this feature is available out of the box just like the previews for the common mime types mentioned above. literally zero extra setup for this part. 💖

🌈 USAGE 🌈

run this and Pistol will spill the help text:

$ pistol --help
Usage: pistol OPTIONS <file> [<extras> ...]

OPTIONS

-V, --version               Print version date and exit
-c, --config <config file>  configuration file to use (defaults to ~/.config/pistol/pistol.conf on Linux)
-h, --help                  print help and exit

ARGUMENTS

file                        the file to preview
extras                      extra arguments passed to the command

quick vibe check on those flags:

  • -V, --version — print version date and exit. 🗓️
  • -c, --config <config file> — configuration file to use (defaults to ~/.config/pistol/pistol.conf on Linux). 🛠️
  • -h, --help — print help and exit. 🆘

and the arguments:

  • file — the file to preview. 👀
  • extras — extra arguments passed to the command. 🧩

🫶 Integrations 🫶

🧭 Ranger / Lf 🧭

you can use Pistol as a file previewer in Ranger (https://ranger.github.io/) and Lf (https://github.com/gokcehan/lf). yup, both. 💅

for Ranger, set your preview_script in your rc.conf as follows:

set preview_script ~/.go/bin/pistol

the same goes for Lf, but in lfrc:

set previewer ~/.go/bin/pistol

🔍 fzf 🔍

if you use fzf (https://github.com/junegunn/fzf) to search for files, you can tell it to use pistol as the previewer. cute, right? 🎀

for example, the following command edits with your $EDITOR selected python file(s) using pistol as a previewer:

$EDITOR "$(find -name '*.py' | fzf --preview='pistol {}')"

this is the previewer glow-up your file search deserved. ✨🦋

💖 CONFIGURATION 💖

okay so even though Pistol previews files of certain MIME types by default, it does not force you to use those internal previewers for those MIME types. You can change this behaviour by writing a configuration file in ~/.config/pistol/pistol.conf (or $XDG_CONFIG_HOME/pistol/pistol.conf). On GNU systems, the syntax is as explained below.

Note: On OS X, this location defaults to ~/Library/Application Support/pistol/pistol.conf, as the XDG specification imposes.

✨ Syntax ✨

You can configure preview commands according to file path or mime type regex. The first word is always interpreted first as a mime type regex, such as text/*.

If a line is not matched but the first word is exactly fpath, then the 2nd argument is interpreted as a file path regex, such as /var/src/.*/README.md.

On every line, whether you used fpath or not, the next arguments are the command's arguments, where %pistol-filename% is substituted by pistol to the file at question. You'll see more examples in the following sections.

Both regular expressions (for file paths and for mime types) are interpreted by the built-in library's regexp.match (https://golang.org/pkg/regexp/#Match). Please refer to this link (https://golang.org/pkg/regexp/syntax) for the full reference regarding syntax.

🎀 Matching Mime Types 🎀

You can inspect the MIME type of any file on a GNU/Linux OS and on Mac OS with the command file --mime-type <file>.

For example, say you wish to replace Pistol's internal text previewer with that of bat's (https://github.com/sharkdp/bat), you'd put the following in your pistol.conf:

text/* bat --paging=never --color=always %pistol-filename%

Naturally, your configuration file overrides the internal previewers.

Here's another example which features w3m (http://w3m.sourceforge.net/) as an HTML previewer:

text/html w3m -T text/html -dump %pistol-filename%

And here's an example that leverages ls for printing directories' contents:

inode/directory ls -l --color %pistol-filename%

🦋 Matching File Path 🦋

For example, say you wish to preview all files that reside in a certain ./bin directory with bat's (https://github.com/sharkdp/bat) syntax highlighting for bash. You could use:

fpath /var/src/my-bash-project/bin/[^/]+$ bat --map-syntax :bash --paging=never --color=always %pistol-filename%

🌸 A Note on RegEx matching 🌸

When Pistol parses your configuration file, as soon as it finds a match — be it a file path match or a mime type match — it stops parsing it and it invokes the command written on the rest of the line. Therefore, if you wish to use the examples from above which use w3m and bat, you'll need to put w3m's line before bat's line. Since otherwise, text/* will be matched first and text/html won't be checked at all.

Similarly, you'd probably want to put fpath lines at the top.

Of course, this is a mere example — the same may apply to any regular expressions you'd choose to match against.

For a list of the internal regular expressions tested against when Pistol reverts to its native previewers, read the file internal_writers/map.go (https://github.com/doronbehar/pistol/blob/master/internal_writers/map.go#L8-L12).

More examples can be found in this WiKi (https://github.com/doronbehar/pistol/wiki/Config-examples) page.

💅 Quoting and Shell Piping 💅

Pistol is pretty dumb when it parses your config — it splits all line by spaces, meaning that e.g:

application/json jq '.' %pistol-filename%

This will result in an error by jq (https://github.com/stedolan/jq):

jq: error: syntax error, unexpected INVALID_CHARACTER, expecting $end (Unix shell quoting issues?) at <top-level>, line 1:
'.'
jq: 1 compile error

Indicating that jq got a literal '.'. When you run in your shell jq '.' file.json you don't get an error because your shell is stripping the quotes around .. However, Pistol is not smarter than your shell, because if you'd try for example:

application/json jq '.[] | .' %pistol-filename%

That would be equivalent to running in the typical shell:

jq "\'.[]" "|" ".'" file.json

That's because Pistol doesn't consider your quotes as interesting instructions, it just splits words by spaces. Hence, to overcome this disability, you can use:

application/json sh: jq '.' %pistol-filename%

Thanks to the sh: keyword at the beginning of the command's definition, the rest of the line goes straight as a single argument to sh -c.

You can worry not about quoting / escaping the rest of the line — it's not like when you run e.g sh -c 'command' in your shell where you need to make sure single quotes are escaped or not used at all inside command.

More over, with sh: you can use shell pipes:

fpath .*.md$ sh: bat --paging=never --color=always %pistol-filename% | head -8

🔥 Passing arbitrary extra arguments to commands 🔥

Pistol is capable of passing extra arguments to commands if the config says so. The arguments %pistol-extra0%, %pistol-extra1% and so on, are substituted by the extra arguments given to pistol, if these present in invocation and if they are present in the config. Example usage:

With this config:

fpath /problematic-bz2/.*.bz2 bzip2 %pistol-filename% %pistol-extra0%
fpath /working-bz2/.*.bz2     bzip2 %pistol-filename%

Running:

pistol /problematic-bz2/example.bz2 --test

Will run bzip2 while testing the integrity of the compressed file. However, running:

pistol /working-bz2/example.bz2 --test

Will not pass the --test argument to bzip, due to %pistol-extra0 not present in the config for the files at /working-bz2. This feature is mainly present for usage with Lf (https://github.com/gokcehan/lf) and Ranger (https://ranger.github.io/) which can pass width height and x, y coordinates for image previews.

Here's an example usage for image previews that works with Lf: [1]

image/.* pv %pistol-filename% %pistol-extra0% %pistol-extra1% %pistol-extra2% %pistol-extra3%

🌈 Environmental Variables 🌈

🍓 Preview Chunk Size 🍓

To prevent pistol from choking on too large text files, it reads by default only the first 100KB of the text files it gets, before passing them to chroma. This also applies to compressed text files.

This limitation is meant to prevent draining the system's memory, since pistol is supposed to be a preview program, not a $PAGER. If you need to see more then 100 KB of a text file, open an editor, or use less. To modify this preview data size, to (e.g) 1MB, set:

export PISTOL_CHROMA_SIZE=1000000
Warning: given a size limit $s$, chroma seems to require $8 \cdot s$ memory to process a file of size $\leq s$.

🧚 Chroma Formatters 🧚

In chroma's terminology, the term formatter refers to the way the given file is presented in the terminal. These include:

  • terminal — The default formatter that uses terminal control codes to change colors between every key word. This formatter has 8 colors and it's the default.
  • terminal256 — Same as terminal but with 256 colors available.
  • terminal16m — Same as terminal but with 24 Bits colors i.e True-Color.

Other formatters include json, and html but I'd be surprised if you'll find them useful for Pistol's purpose.

To tell Pistol to use a specific formatter, set PISTOL_CHROMA_FORMATTER in your environment, e.g:

export PISTOL_CHROMA_FORMATTER=terminal16m

Recent versions of Lf (https://github.com/gokcehan/lf) support 256 colors (https://github.com/gokcehan/lf/pull/93) in its preview window. AFAIK, [2], Ranger (https://ranger.github.io/) supports 8 colors and Lf's color256 isn't enabled by default.

Therefore, I decided that it'll be best to keep this variable unset in your general environment. If you do set color256 in your lfrc, you may feel free to set PISTOL_CHROMA_FORMATTER in your environment.

💜 Chroma Styles 💜

Like formatter, the term style refers to the set of colors used to print a given file. The chroma project documents all styles here (https://xyproto.github.io/splash/docs/all.html) and here (https://xyproto.github.io/splash/docs/longer/all.html).

The default style used by Pistol is pygments. To tell Pistol to use a specific style set PISTOL_CHROMA_STYLE in your environment, e.g:

export PISTOL_CHROMA_STYLE=monokai

😭 DEBUGGING 😭

Can't figure out why Pistol acts the way he does? You can run pistol with:

env PISTOL_DEBUG=1 pistol test-file

And you should be able to see messages that may give you a clue.

👑 NEWS 👑

See previous releases (https://github.com/doronbehar/pistol/releases).

⭐ NOTES ⭐

okay bestie, that's the whole page 💅 source/version: Pistol; date: 1980-01-01; manual: PISTOL(1) 🎀

📦 where this page comes from