1BAT(1) General Commands Manual BAT(1)
2
3
4
6 bat - a cat(1) clone with syntax highlighting and Git integration.
7
9 bat [OPTIONS] [FILE]...
10
11 bat cache [CACHE-OPTIONS] [--build|--clear]
12
14 bat prints the syntax-highlighted content of a collection of FILEs to
15 the terminal. If no FILE is specified, or when FILE is '-', it reads
16 from standard input.
17
18 bat supports a large number of programming and markup languages. It
19 also communicates with git(1) to show modifications with respect to the
20 git index. bat automatically pipes its output through a pager (by de‐
21 fault: less).
22
23 Whenever the output of bat goes to a non-interactive terminal, i.e.
24 when the output is piped into another process or into a file, bat will
25 act as a drop-in replacement for cat(1) and fall back to printing the
26 plain file contents.
27
28
30 General remarks: Command-line options like '-l'/'--language' that take
31 values can be specified as either '--language value', '--lan‐
32 guage=value', '-l value' or '-lvalue'.
33
34 -A, --show-all
35
36 Show non-printable characters like space, tab or newline. Use
37 '--tabs' to control the width of the tab-placeholders.
38
39 --nonprintable-notation <notation>
40
41 Specify how to display non-printable characters when using
42 --show-all.
43
44 Possible values:
45
46 caret Use character sequences like ^G, ^J, ^@, .. to identify
47 non-printable characters
48
49 unicode
50 Use special Unicode code points to identify non-printable
51 characters
52
53 -p, --plain
54
55 Only show plain style, no decorations. This is an alias for
56 '--style=plain'. When '-p' is used twice ('-pp'), it also dis‐
57 ables automatic paging (alias for '--style=plain --pag‐
58 ing=never').
59
60 -l, --language <language>
61
62 Explicitly set the language for syntax highlighting. The lan‐
63 guage can be specified as a name (like 'C++' or 'LaTeX') or pos‐
64 sible file extension (like 'cpp', 'hpp' or 'md'). Use
65 '--list-languages' to show all supported language names and file
66 extensions.
67
68 -H, --highlight-line <N:M>...
69
70 Highlight the specified line ranges with a different background
71 color. For example:
72
73 --highlight-line 40
74 highlights line 40
75
76 --highlight-line 30:40
77 highlights lines 30 to 40
78
79 --highlight-line :40
80 highlights lines 1 to 40
81
82 --highlight-line 40:
83 highlights lines 40 to the end of the file
84
85 --highlight-line 30:+10
86 highlights lines 30 to 40
87
88 --file-name <name>...
89
90 Specify the name to display for a file. Useful when piping data
91 to bat from STDIN when bat does not otherwise know the filename.
92 Note that the provided file name is also used for syntax detec‐
93 tion.
94
95 -d, --diff
96
97 Only show lines that have been added/removed/modified with re‐
98 spect to the Git index. Use '--diff-context=N' to control how
99 much context you want to see.
100
101 --diff-context <N>...
102
103 Include N lines of context around added/removed/modified lines
104 when using '--diff'.
105
106 --tabs <T>
107
108 Set the tab width to T spaces. Use a width of 0 to pass tabs
109 through directly
110
111 --wrap <mode>
112
113 Specify the text-wrapping mode (*auto*, never, character). The
114 '--terminal-width' option can be used in addition to control the
115 output width.
116
117 --terminal-width <width>
118
119 Explicitly set the width of the terminal instead of determining
120 it automatically. If prefixed with '+' or '-', the value will be
121 treated as an offset to the actual terminal width. See also:
122 '--wrap'.
123
124 -n, --number
125
126 Only show line numbers, no other decorations. This is an alias
127 for '--style=numbers'
128
129 --color <when>
130
131 Specify when to use colored output. The automatic mode only en‐
132 ables colors if an interactive terminal is detected. Possible
133 values: *auto*, never, always.
134
135 --italic-text <when>
136
137 Specify when to use ANSI sequences for italic text in the out‐
138 put. Possible values: always, *never*.
139
140 --decorations <when>
141
142 Specify when to use the decorations that have been specified via
143 '--style'. The automatic mode only enables decorations if an in‐
144 teractive terminal is detected. Possible values: *auto*, never,
145 always.
146
147 -f, --force-colorization
148
149 Alias for '--decorations=always --color=always'. This is useful
150 if the output of bat is piped to another program, but you want
151 to keep the colorization/decorations.
152
153 --paging <when>
154
155 Specify when to use the pager. To disable the pager, use '--pag‐
156 ing=never' or its alias, -P. To disable the pager permanently,
157 set BAT_PAGER to an empty string. To control which pager is
158 used, see the '--pager' option. Possible values: *auto*, never,
159 always.
160
161 --pager <command>
162
163 Determine which pager is used. This option will override the
164 PAGER and BAT_PAGER environment variables. The default pager is
165 'less'. To control when the pager is used, see the '--paging'
166 option. Example: '--pager "less -RF"'.
167
168 Note: By default, if the pager is set to 'less' (and no command-
169 line options are specified), 'bat' will pass the following com‐
170 mand line options to the pager: '-R'/'--RAW-CONTROL-CHARS',
171 '-F'/'--quit-if-one-screen' and '-X'/'--no-init'. The last op‐
172 tion ('-X') is only used for 'less' versions older than 530. The
173 '-R' option is needed to interpret ANSI colors correctly. The
174 second option ('-F') instructs less to exit immediately if the
175 output size is smaller than the vertical size of the terminal.
176 This is convenient for small files because you do not have to
177 press 'q' to quit the pager. The third option ('-X') is needed
178 to fix a bug with the '--quit-if-one-screen' feature in old ver‐
179 sions of 'less'. Unfortunately, it also breaks mouse-wheel sup‐
180 port in 'less'. If you want to enable mouse-wheel scrolling on
181 older versions of 'less', you can pass just '-R' (as in the ex‐
182 ample above, this will disable the quit-if-one-screen feature).
183 For less 530 or newer, it should work out of the box.
184
185 -m, --map-syntax <glob-pattern:syntax-name>...
186
187 Map a glob pattern to an existing syntax name. The glob pattern
188 is matched on the full path and the filename. For example, to
189 highlight *.build files with the Python syntax, use -m
190 '*.build:Python'. To highlight files named '.myignore' with the
191 Git Ignore syntax, use -m '.myignore:Git Ignore'. Note that the
192 right-hand side is the *name* of the syntax, not a file exten‐
193 sion.
194
195 --theme <theme>
196
197 Set the theme for syntax highlighting. Use '--list-themes' to
198 see all available themes. To set a default theme, add the
199 '--theme="..."' option to the configuration file or export the
200 BAT_THEME environment variable (e.g.: export BAT_THEME="...").
201
202 --list-themes
203
204 Display a list of supported themes for syntax highlighting.
205
206 --style <style-components>
207
208 Configure which elements (line numbers, file headers, grid bor‐
209 ders, Git modifications, ..) to display in addition to the file
210 contents. The argument is a comma-separated list of components
211 to display (e.g. 'numbers,changes,grid') or a pre-defined style
212 ('full'). To set a default style, add the '--style=".."' option
213 to the configuration file or export the BAT_STYLE environment
214 variable (e.g.: export BAT_STYLE=".."). Possible values: *de‐
215 fault*, full, auto, plain, changes, header, header-filename,
216 header-filesize, grid, rule, numbers, snip.
217
218 -r, --line-range <N:M>...
219
220 Only print the specified range of lines for each file. For exam‐
221 ple:
222
223 --line-range 30:40
224 prints lines 30 to 40
225
226 --line-range :40
227 prints lines 1 to 40
228
229 --line-range 40:
230 prints lines 40 to the end of the file
231
232 --line-range 30:+10
233 prints lines 30 to 40
234
235 -L, --list-languages
236
237 Display a list of supported languages for syntax highlighting.
238
239 -u, --unbuffered
240
241 This option exists for POSIX-compliance reasons ('u' is for 'un‐
242 buffered'). The output is always unbuffered - this option is
243 simply ignored.
244
245 -h, --help
246
247 Print this help message.
248
249 -V, --version
250
251 Show version information.
252
254 <FILE>...
255
256 Files to print and concatenate. Use a dash ('-') or no argument
257 at all to read from standard input.
258
260 cache - Modify the syntax-definition and theme cache.
261
263 bat can also be customized with a configuration file. The location of
264 the file is dependent on your operating system. To get the default path
265 for your system, call:
266
267 bat --config-file
268
269 Alternatively, you can use the BAT_CONFIG_PATH environment variable to
270 point bat to a non-default location of the configuration file.
271
272 To generate a default configuration file, call:
273
274 bat --generate-config-file
275
277 bat supports Sublime Text .sublime-syntax language files, and can be
278 customized to add additional languages to your local installation. To
279 do this, add the .sublime-syntax language files to `$(bat --config-
280 dir)/syntaxes` and run `bat cache --build`.
281
282 Example:
283
284 mkdir -p "$(bat --config-dir)/syntaxes"
285 cd "$(bat --config-dir)/syntaxes"
286
287 # Put new '.sublime-syntax' language definition files
288 # in this folder (or its subdirectories), for example:
289 git clone https://github.com/tellnobody1/sublime-purescript-syntax
290
291 # And then build the cache.
292 bat cache --build
293
294 Once the cache is built, the new language will be visible in `bat
295 --list-languages`.
296 If you ever want to remove the custom languages, you can clear the
297 cache with `bat cache --clear`.
298
299
301 Similarly to custom languages, bat supports Sublime Text .tmTheme
302 themes. These can be installed to `$(bat --config-dir)/themes`, and
303 are added to the cache with `bat cache --build`.
304
305
307 Much like less(1) does, bat supports input preprocessors via the
308 LESSOPEN and LESSCLOSE environment variables. In addition, bat at‐
309 tempts to be as compatible with less's preprocessor implementation as
310 possible.
311
312 To use the preprocessor, call:
313
314 bat --lessopen
315
316 Alternatively, the preprocessor may be enabled by default by adding the
317 '--lessopen' option to the configuration file.
318
319 To temporarily disable the preprocessor if it is enabled by default,
320 call:
321
322 bat --no-lessopen
323
324 For more information, see the "INPUT PREPROCESSOR" section of less(1).
325
326
328 For more information and up-to-date documentation, visit the bat repo:
329 https://github.com/sharkdp/bat
330
331
332
333 BAT(1)