LESSPIPE.SH(1) User Commands LESSPIPE.SH(1)
NAME
lesspipe.sh - a filter for less
SYNOPSIS
lesspipe.sh [FILE[s]]...
DESCRIPTION
The aim of lesspipe.sh is to enhance the output of less. The choice of
the rules to be applied to modify the output are based on the file
contents. The file extension is respected only as a last resort.
Usually lesspipe.sh is called as an input filter to less.
With the help of that filter less will display the uncompressed
contents of compressed (gzip, bzip2, compress, zstd, lz4, lzip, xz,
lzma or brotli) files. For files containing archives and directories, a
table of contents will be displayed (tar, ar, zip, 7-zip, rar, jar,
cpio, rpm, deb ms-cabinet, iso, appimage and snap formats). Many other
files will be reformatted for display. It includes pdf, dvi, markdown,
Office (MS and Openoffice) suites formats, NetCDF, matlab, device tree
blob, html, xml and media (image, audio and video) formats. This does
require helper programs being installed.
The filter can also be applied recursively to extract and display files
in archives on the fly. This works to a depth of 6 where applying a
decompression algorithm counts as a separate level.
If the file utility reports text with an encoding different from the
one used in the terminal then the text will be transformed using iconv
into the default encoding. This does assume the file command gets the
file encoding right, which can be wrong in some situations. An appended
colon to the file name does suppress the conversion.
When using the programs git, vim or mutt they can be enabled to read
non-text files by using lesspipe.sh. That is described in the Wiki at
https://github.com/wofr06/lesspipe/wiki.
FILTER ACTIVATION
The filter is called from less provided the environment variable
LESSOPEN is set properly. For ksh like shells (bash, zsh) the command
LESSOPEN="|lesspipe.sh %s"; export LESSOPEN
does activate the filter for less. Use the fully qualified path, if
lesspipe.sh is not in the search path. The command to set LESSOPEN can
also be displayed by calling lesspipe.sh without arguments. This can
even be used to set LESSOPEN directly:
eval `lesspipe.sh` (bash) or
lesspipe.sh|source /dev/stdin (zsh)
The above commands work only in the described manner if the file name
is lesspipe.sh. If it is installed under a different name then calling
it without an argument will work as a filter with LESSQUIET set and
expecting input from STDIN.
Having set the environment variable as described above, less :will then
display textual information for a wide range of file formats.
The filter is normally not called if input is piped to less as in
cat somefile | less
As described in the man page of less, the filtering in a pipe can
however be forced by starting LESSOPEN with the characters |-.
LESSOPEN starting with the two characters || to handle empty files and
command errors is implemented only partly, usually on failures of
commands within lesspipe.sh the error messages get displayed.
To suppress informal messages in the first line of the filter output
the ENV variable LESSQUIET can be set to a nonempty value.
To disengage the filter temporarily a colon can be appended to the file
name. If the file name contains a colon, then an equal sign should be
used instead.
HTML, XML and Perl POD Files
Files in the html, xml and perl pod format are always rendered.
Sometimes however the original contents of the file should be viewed
instead. As mentioned before that can be achieved by appending a colon
to the file name. If the correct file type (html, xml, pod) follows,
the output can get colorized (see also the section below).
Example: less index.html:html
If the binary xmq is installed, then xml is rendered differently, so
that the xml structure is better recognized. A similar display for html
contents using xmq is achieved by appending a colon to the file name.
To get the original html file contents, two colons are required in this
case.
OUTPUT COLORIZATION
The filter is able to do syntax highlighting for a wide variety of file
types. If installed, bat/batcat is used for coloring the output. If
not, pygmentize, source-highlight, vimcolor and code2color are tried in
turn. For bat/batcat the theme is set to ansi and the style is set to
plain which comes closer to the unfiltered output of less. These
settings can be changed in ~/.config/bat/config or by the environment
variables BAT_STYLE and BAT_THEME.
Among the colorizers a preferred one can be forced for coloring by
setting the ENV variable LESSCOLORIZER to the name of the colorizer.
For pygmentize and bat/batcat restricted option settings are allowed as
follows:
LESSCOLORIZER='pygmentize -O style=foo'
LESSCOLORIZER='bat --style=foo --theme=bar'
Syntax highlighting is activated, if the environment variable LESS
exists and contains the option -R or less is called with this option.
This guarantees that escape sequences get converted into colors and do
not garble the display. Using the option -r is not recommended, as the
screen layout may be wrong, if long lines are in the output.
Syntax highlighting can be switched off by appending a colon after the
file name, if the output was colorful. If the wrong language was chosen
for syntax highlighting, then another one can be forced by appending a
colon and a suffix to the file name.
In a pipe that method cannot be used. As a way out a last argument can
be added that gets inspected by lesspipe.sh. A single colon (disengage
filter) or :extension (force language) is possible as e.g with
command that generates c code | less - :c
When the conditions for syntax highlighting are met directory listings
and listings of tar file contents get colorized as well.
As less is used as a default browser in other programs the choice of
the colorizer can affect the output of those programs. For man, git,
and perldoc) lesspipe.sh does no filtering.
WATCHING GROWING FILES
As soon as lesspipe.sh calls a program to convert the input the ability
to watch growing files (using the F command within less) is lost. This
is usually wanted for log files like syslog. To temporarily disengage
lesspipe.sh a colon as the last argument for less needs to be added as
e.g in
less /var/log/syslog :
or less can be called with the +F argument, which is equivalent to F
within the pager:
less +F /var/log/syslog
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. On the other hand non growing log files can be
colorized using ccze. Its recognition as a log file is difficult if
not ending in .log but can be forced appending :.log to the file name
as e.g in
less /var/log/syslog:.log
ADVANCED USAGE
This version of lesspipe.sh allows you to view individual files
contained in a file archive, which itself may even be contained in
another archive.
The notation for viewing files in multifile archives is
less archive_file:contained_file
or even
less super_archive:archive_file:contained_file
To display the last file in the chain raw format, a colon (:) has to be
appended to the file name. If it does contain a colon, then the
alternate separator character equal sign (=) has to be used.
Again, this method of extracting and displaying files does not work if
less is called in an output pipe and LESSOPEN starts with the |-
characters. As already for syntax highlighting the solution is to use a
second argument that starts with a colon. Then the above command would
be written as
cat super_archive | less - :archive:contained_file
COMPLETING MECHANISM FOR ARCHIVE CONTENTS
With the provided lesscomplete (for zsh and bash), _less (for zsh) and
less_completion (for bash) files a tab completion for files in archives
can be accomplished. Entering a colon (:) or an equal sign (=) after
an archive file name and then pressing the tab key triggers the
completion mechanism. This also works in chained archives. The files
lesscomplete and less_completion have to be in one of the directories
listed in $PATH and the function _less for zsh in a directory listed by
$fpath. The less_completion script has to be sourced within a bash
initialization script, e.g. in ~/.bashrc. New directories such as
~/scripts and ~/.fpath can be added using the commands
PATH=~/scripts:$PATH and fpath=(~/.fpath $fpath)
USER DEFINED FILTERING
The lesspipe.sh filtering can be replaced or enhanced by a user
defined program. Such a program has to be called either .lessfilter
(and be placed in the users home directory), or lessfilter (and be
accessible from a directory mentioned in $PATH). It has to be
executable and has to end with an exit code 0, if the filtering was
done within that script. Otherwise, a nonzero exit code means the
filtering is left to lesspipe.sh.
This mechanism can be used to add filtering for new formats or e.g.
inhibit filtering for certain file types.
AUTHOR
Wolfgang Friebel
REPORTING BUGS
Report bugs to <wp.friebel AT gmail DOT com>.
COPYRIGHT
Copyright (C) 2005-2024 Wolfgang Friebel
This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
SEE ALSO
less(1)
A description of lesspipe.sh is also contained in the file README
contained in the source code package
lesspipe.sh March 2024 LESSPIPE.SH(1)
lesspipe 2.13 - Generated Sat May 11 08:42:55 CDT 2024