| 1 |
.TH LESSPIPE.SH "1" "December 2025" "lesspipe.sh" "User Commands" |
| 2 |
.SH NAME |
| 3 |
lesspipe.sh \- a filter for less |
| 4 |
.SH SYNOPSIS |
| 5 |
.B lesspipe.sh |
| 6 |
[\fIFILE[s]\fR]... |
| 7 |
.SH DESCRIPTION |
| 8 |
.PP |
| 9 |
The aim of \fBlesspipe.sh\fP is to enhance the output of \fBless\fP. The choice |
| 10 |
of the rules to be applied to modify the output are based on the file contents. |
| 11 |
The file extension is respected only as a last resort. |
| 12 |
Usually \fBlesspipe.sh\fP is called as an input filter to \fBless\fP. |
| 13 |
.PP |
| 14 |
With the help of that filter \fBless\fP |
| 15 |
will display the uncompressed contents of compressed (\fIgzip, bzip2, |
| 16 |
compress, zstd, lz4, lzip, xz, lzma, zlib or brotli\fP) files. For files |
| 17 |
containing archives and directories, a table of contents will be displayed |
| 18 |
(\fItar, ar, zip, 7-zip, rar, jar, cpio, rpm, deb ms-cabinet, iso, dmg, |
| 19 |
appimage and snap formats\fP). |
| 20 |
Many other files will be reformatted for display. It includes |
| 21 |
\fIpdf, dvi, markdown, Office (MS and Openoffice)\fP suites formats, |
| 22 |
\fINetCDF, matlab, device tree blob, html, xml\fP and \fImedia (image, audio and |
| 23 |
video)\fP formats. This does require helper programs being installed. |
| 24 |
.PP |
| 25 |
The filter can also be applied recursively to extract and display |
| 26 |
files in archives on the fly. This works to a depth of 6 where applying a |
| 27 |
decompression algorithm counts as a separate level. |
| 28 |
.PP |
| 29 |
If the file utility reports text with an encoding different from the one |
| 30 |
used in the terminal then the text will be transformed using \fIiconv\fP into |
| 31 |
the default encoding. This does assume the \fIfile\fP command gets the file |
| 32 |
encoding right, which can be wrong in some situations. An appended colon |
| 33 |
to the file name does suppress the conversion. |
| 34 |
.PP |
| 35 |
When using the programs \fBgit\fP, \fBvim\fP or \fBmutt\fP they can be |
| 36 |
enabled to read non-text files by using lesspipe.sh. That is described in |
| 37 |
the Wiki at \fIhttps://github.com/wofr06/lesspipe/wiki\fP. |
| 38 |
.SH FILTER ACTIVATION |
| 39 |
The filter is called from \fBless\fP provided the environment variable |
| 40 |
\fBLESSOPEN\fP is set properly. For ksh like shells (\fIbash, zsh\fP) |
| 41 |
the command |
| 42 |
.RS |
| 43 |
.I LESSOPEN="|lesspipe.sh %s"; export LESSOPEN |
| 44 |
.RE |
| 45 |
does activate the filter for less. Use the fully qualified path, if |
| 46 |
\fBlesspipe.sh\fP is not in the search path. The command to set \fBLESSOPEN\fP |
| 47 |
can also be displayed by calling \fBlesspipe.sh\fP without arguments. |
| 48 |
This can even be used to set \fBLESSOPEN\fP directly: |
| 49 |
.EX |
| 50 |
.RS |
| 51 |
.I eval `lesspipe.sh` |
| 52 |
(bash) or |
| 53 |
.I lesspipe.sh|source /dev/stdin |
| 54 |
(zsh) |
| 55 |
.RE |
| 56 |
.EE |
| 57 |
The above commands work only in the described manner if the file name is |
| 58 |
\fBlesspipe.sh\fP. |
| 59 |
If it is installed under a different name then calling it without an argument |
| 60 |
will work as a filter with \fBLESSQUIET\fP set and expecting input from STDIN. |
| 61 |
.PP |
| 62 |
Having set the environment variable as described above, \fBless\fP |
| 63 |
will then display textual information for a wide range of file formats. |
| 64 |
.PP |
| 65 |
The filter is normally not called if input is piped to less as in |
| 66 |
.RS |
| 67 |
.I cat somefile | less |
| 68 |
.RE |
| 69 |
As described in the man page of less, the filtering in a pipe can however |
| 70 |
be forced by starting \fBLESSOPEN\fP with the characters \fI|-\fP. |
| 71 |
.PP |
| 72 |
If commands within \fBlesspipe.sh\fP do fail, in some cases the error messages |
| 73 |
get displayed, this is a regarded buggy behavior and should be reported. |
| 74 |
.PP |
| 75 |
To suppress informal messages in the first line of the filter output the |
| 76 |
ENV variable \fBLESSQUIET\fP can be set to a nonempty value. |
| 77 |
.PP |
| 78 |
To disengage the filter temporarily a colon can be appended to the file name. |
| 79 |
If the file name contains a colon, then an equal sign should be used instead. |
| 80 |
.SH HTML, XML and Perl POD Files |
| 81 |
Files in the \fIhtml\fP, \fIxml\fP and \fIperl pod\fP format are always |
| 82 |
rendered. Sometimes however the original contents of the file should be viewed |
| 83 |
instead. As mentioned before that can be achieved by appending a colon to the |
| 84 |
file name. If the correct file type (\fIhtml\fP, \fIxml\fP, \fIpod\fP) follows, |
| 85 |
the output can get colorized (see also the section below). |
| 86 |
.PP |
| 87 |
.RS |
| 88 |
Example: \fBless\fP \fIindex.html:html\fP |
| 89 |
.RE |
| 90 |
.PP |
| 91 |
If the binary \fIxmq\fP is installed, then \fIxml\fP is rendered differently, |
| 92 |
so that the xml structure is better recognized. A similar display for |
| 93 |
\fIhtml\fP contents using \fIxmq\fP is achieved by appending a colon to the |
| 94 |
file name. To get the original html file contents, two colons are |
| 95 |
required in this case. |
| 96 |
.SH OUTPUT COLORIZATION |
| 97 |
The filter is able to do syntax highlighting for a wide variety of |
| 98 |
file types. If installed, \fInvimpager\fP is used for |
| 99 |
colorizing the output. If not, \fIbat\fP/\fIbatcat\fP, \fIpygmentize\fP, |
| 100 |
\fIsource-highlight\fP, \fIvimcolor\fP and \fIcode2color\fP are tried in turn. |
| 101 |
For bat/batcat the theme is set to \fIansi\fP and the style is set to |
| 102 |
\fIplain\fP which comes closer to the unfiltered output of \fBless\fP. |
| 103 |
These settings can be changed in \fI~/.config/bat/config\fP or by the |
| 104 |
environment variables \fBBAT_STYLE\fP and \fBBAT_THEME\fP. |
| 105 |
.PP |
| 106 |
Among the colorizers |
| 107 |
a preferred one can be forced for colorizing by setting the ENV variable |
| 108 |
\fBLESSCOLORIZER\fP to the name of the colorizer. For \fIpygmentize\fP and |
| 109 |
\fIbat\fP/\fIbatcat\fP restricted option settings are allowed as follows: |
| 110 |
.EX |
| 111 |
.RS |
| 112 |
.I LESSCOLORIZER='pygmentize -O style=foo' # -P allowed as well |
| 113 |
.I LESSCOLORIZER='bat --style=foo --theme=bar' # default: theme=ansi, style=plain |
| 114 |
.RE |
| 115 |
.EE |
| 116 |
Syntax highlighting is activated, if the environment variable \fBLESS\fP |
| 117 |
exists and contains the option \fI-R\fP |
| 118 |
or less is called with this option. This guarantees that escape sequences |
| 119 |
get converted into colors and do not garble the display. Using the option |
| 120 |
\fI-r\fP is not recommended, as the screen layout may be wrong, if long |
| 121 |
lines are in the output. |
| 122 |
.PP |
| 123 |
Syntax highlighting can be switched off by |
| 124 |
appending a colon after the file name, if the output was colorful. If the |
| 125 |
wrong language was chosen for syntax highlighting, then another one can be |
| 126 |
forced by appending a colon and a suffix to the file name. |
| 127 |
The list of suffixes and supported languages can be printed using the following colorizer commands: |
| 128 |
.EX |
| 129 |
.RS |
| 130 |
.I bat --list-languages |
| 131 |
.I batcat --list-languages |
| 132 |
.I pygmentize -L lexers |
| 133 |
.I source-highlight --lang-list |
| 134 |
.I code2color -h |
| 135 |
.I vimcolor -L (both for vimcolor and nvimpager) |
| 136 |
.RE |
| 137 |
.EE |
| 138 |
.PP |
| 139 |
In a pipe that method cannot be used. As a way out a last argument can be added |
| 140 |
that gets inspected by \fBlesspipe.sh\fP. |
| 141 |
A single colon (disengage filter) or :extension (force language) is possible as e.g with |
| 142 |
.RS |
| 143 |
.I command that generates c code | less - :c |
| 144 |
.RE |
| 145 |
.PP |
| 146 |
When the conditions for syntax highlighting are met directory listings and |
| 147 |
listings of tar file contents get colorized as well. |
| 148 |
.PP |
| 149 |
As \fBless\fP is used as a default browser in other programs (e.g. \fIman\fP, |
| 150 |
\fIgit\fP, and \fIperldoc\fP) \fBlesspipe.sh\fP may be engaged and alter |
| 151 |
the output of those programs. |
| 152 |
.SH WATCHING GROWING FILES |
| 153 |
As soon as \fBlesspipe.sh\fP |
| 154 |
calls a program to convert the input the ability to watch growing files |
| 155 |
(using the F command within less) is lost. This is usually wanted for log |
| 156 |
files like syslog. To temporarily disengage \fBlesspipe.sh\fP |
| 157 |
a colon as the last argument for \fBless\fP needs to be added as e.g in |
| 158 |
.RS |
| 159 |
.I \fBless\fP /var/log/syslog : |
| 160 |
.RE |
| 161 |
or \fBless\fP |
| 162 |
can be called with the +F argument, which is equivalent to F within the pager: |
| 163 |
.RS |
| 164 |
.I \fBless\fP +F /var/log/syslog |
| 165 |
.RE |
| 166 |
Appending a colon to the file name does not work, as then the filter has to be engaged to at least remove that colon and use cat for the original file. |
| 167 |
.SH ADVANCED USAGE |
| 168 |
This version of \fBlesspipe.sh\fP |
| 169 |
allows you to view individual files contained in a file archive, which itself |
| 170 |
may even be contained in another archive. |
| 171 |
.PP |
| 172 |
The notation for viewing files in multifile archives is |
| 173 |
.RS |
| 174 |
.B less |
| 175 |
\fIarchive_file\fP:\fIcontained_file\fP |
| 176 |
.RE |
| 177 |
or even |
| 178 |
.RS |
| 179 |
.B less |
| 180 |
\fIsuper_archive\fP:\fIarchive_file\fP:\fIcontained_file\fP |
| 181 |
.RE |
| 182 |
To display the last file in the chain raw format, a colon (\fI:\fP) has to be |
| 183 |
appended to the file name. If it does contain a colon, then the alternate |
| 184 |
separator character equal sign (\fI=\fP) has to be used. |
| 185 |
.PP |
| 186 |
Again, this method of extracting and displaying files does not work if |
| 187 |
\fBless\fP is called in an output pipe and \fBLESSOPEN\fP starts with the |
| 188 |
\fB|-\fP characters. As already for syntax highlighting the solution is to use |
| 189 |
a second argument that starts with a colon. Then the above command would |
| 190 |
be written as |
| 191 |
.RS |
| 192 |
\fBcat \fIsuper_archive\fP | \fBless\fP - :\fIarchive\fP:\fIcontained_file\fP |
| 193 |
.RE |
| 194 |
.PP |
| 195 |
.SH COMPLETING MECHANISM FOR ARCHIVE CONTENTS |
| 196 |
With the provided \fIlesscomplete\fP file (for \fBzsh\fP and \fBbash\fP) and the |
| 197 |
\fI_less\fP (for \fBzsh\fP) and \fIless\fP (for \fBbash\fP) files generated |
| 198 |
during installation a tab completion for files in archives can be accomplished. |
| 199 |
Entering a colon (:) or an equal sign (=) after an archive |
| 200 |
file name and then pressing the tab key triggers the completion mechanism. |
| 201 |
This also works in chained archives. |
| 202 |
The files required for the completion algorithm get installed in directories |
| 203 |
according the choices made during the installation (configure script). |
| 204 |
|
| 205 |
The file \fIlesscomplete\fP |
| 206 |
has to be in one of the directories listed in \fB$PATH\fP and the function \fI_less\fP for \fBzsh\fP in a directory listed by \fI$fpath\fP. The file \fIless\fP |
| 207 |
with completion instructions for bash has to be sourced within a bash |
| 208 |
initialization script, e.g. in \fI~/.bashrc\fP. New directories such as |
| 209 |
\fI~/scripts\fP and \fI~/.fpath\fP (for zsh) can be added |
| 210 |
using the commands |
| 211 |
.RS |
| 212 |
\fBPATH\fP=\fI~/scripts:$PATH\fP # (lesspipe.sh, less) and |
| 213 |
\fBfpath\fP=\fI(~/.fpath $fpath)\fP # (_less, zsh only) |
| 214 |
.RE |
| 215 |
.PP |
| 216 |
In \fBzsh\fP, \fIcompinit\fP has to be called and the menucomplete option has to be |
| 217 |
set if not yet done. That can be achieved with the commands |
| 218 |
.EX |
| 219 |
.RS |
| 220 |
\fIautoload compinit\fP |
| 221 |
\fIcompinit -Uz\fP |
| 222 |
\fIsetopt menucomplete\fP |
| 223 |
.RE |
| 224 |
.EE |
| 225 |
.PP |
| 226 |
In \fBbash\fP, the \fIbash-completion\fP (usually a package with that name) |
| 227 |
has to be installed |
| 228 |
.SH USER DEFINED FILTERING |
| 229 |
The lesspipe.sh filtering can be replaced or enhanced by a user defined |
| 230 |
program. Such a program has to be called either \fB.lessfilter\fP (and be |
| 231 |
placed in the users home directory), or \fBlessfilter\fP (and be accessible |
| 232 |
from a directory mentioned in \fB$PATH\fP). |
| 233 |
It has to be executable and has to end with an exit code 0, if the filtering |
| 234 |
was done within that script. Otherwise, a nonzero exit code means the filtering |
| 235 |
is left to lesspipe.sh. |
| 236 |
.PP |
| 237 |
This mechanism can be used to add filtering for new formats or e.g. inhibit |
| 238 |
filtering for certain file types. A sample .lessfilter could look as follows: |
| 239 |
|
| 240 |
.EX |
| 241 |
.I #!/usr/bin/env bash |
| 242 |
.I |
| 243 |
.I case "$1" in |
| 244 |
.I *.md|*.MD|*.mkd|*.markdown|*.rst) |
| 245 |
.I # if the python module rich.markdown is not found then |
| 246 |
.I # the exit code is not null and lesspipe.sh is called |
| 247 |
.I python3 -m rich.markdown -c "$1";; |
| 248 |
.I *.html|*.htm) |
| 249 |
.I # call your favorite html beautifier, cat -b is just a boring example |
| 250 |
.I cat -b "$1";; |
| 251 |
.I *) |
| 252 |
.I exit 1;; |
| 253 |
.I esac |
| 254 |
|
| 255 |
.EE |
| 256 |
.SH AUTHOR |
| 257 |
Wolfgang Friebel |
| 258 |
.SH "REPORTING BUGS" |
| 259 |
Report bugs to <wp.friebel AT gmail DOT com>. |
| 260 |
.SH COPYRIGHT |
| 261 |
Copyright \(co 2005-2025 Wolfgang Friebel |
| 262 |
.br |
| 263 |
This is free software; see the source for copying conditions. There is NO |
| 264 |
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| 265 |
.SH "SEE ALSO" |
| 266 |
less(1) |
| 267 |
.PP |
| 268 |
A description of \fBlesspipe.sh\fP |
| 269 |
can also be found in the file README contained in the source code package |