Debian Codegraph @

upstream/fedora-44/man1/lesspipe.1

raw
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