1BAT(1) General Commands Manual BAT(1)
2
6 bat - a cat(1) clone with syntax highlighting and Git integration.
7
9 bat [OPTIONS] [FILE]...
10 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 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 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
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 -A, --show-all
35 Show non-printable characters like space, tab or newline. Use
37 '--tabs' to control the width of the tab-placeholders.
38 --nonprintable-notation <notation>
40 Specify how to display non-printable characters when using
42 --show-all.
43 Possible values:
45 caret Use character sequences like ^G, ^J, ^@, .. to identify
47 non-printable characters
48 unicode
50 Use special Unicode code points to identify non-printable
51 characters
52 -p, --plain
54 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 -l, --language <language>
61 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 -H, --highlight-line <N:M>...
69 Highlight the specified line ranges with a different background
71 color. For example:
72 --highlight-line 40
74 highlights line 40
75 --highlight-line 30:40
77 highlights lines 30 to 40
78 --highlight-line :40
80 highlights lines 1 to 40
81 --highlight-line 40:
83 highlights lines 40 to the end of the file
84 --highlight-line 30:+10
86 highlights lines 30 to 40
87 --file-name <name>...
89 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 -d, --diff
96 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 --diff-context <N>...
102 Include N lines of context around added/removed/modified lines
104 when using '--diff'.
105 --tabs <T>
107 Set the tab width to T spaces. Use a width of 0 to pass tabs
109 through directly
110 --wrap <mode>
112 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 --terminal-width <width>
118 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 -n, --number
125 Only show line numbers, no other decorations. This is an alias
127 for '--style=numbers'
128 --color <when>
130 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 --italic-text <when>
136 Specify when to use ANSI sequences for italic text in the out‐
138 put. Possible values: always, *never*.
139 --decorations <when>
141 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 -f, --force-colorization
148 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 --paging <when>
154 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 --pager <command>
162 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 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 -m, --map-syntax <glob-pattern:syntax-name>...
186 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 --theme <theme>
196 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 --list-themes
203 Display a list of supported themes for syntax highlighting.
205 --style <style-components>
207 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 -r, --line-range <N:M>...
219 Only print the specified range of lines for each file. For exam‐
221 ple:
222 --line-range 30:40
224 prints lines 30 to 40
225 --line-range :40
227 prints lines 1 to 40
228 --line-range 40:
230 prints lines 40 to the end of the file
231 --line-range 30:+10
233 prints lines 30 to 40
234 -L, --list-languages
236 Display a list of supported languages for syntax highlighting.
238 -u, --unbuffered
240 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 -h, --help
246 Print this help message.
248 -V, --version
250 Show version information.
252
254 <FILE>...
255 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 bat --config-file
268 Alternatively, you can use the BAT_CONFIG_PATH environment variable to
270 point bat to a non-default location of the configuration file.
271 To generate a default configuration file, call:
273 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 Example:
283 mkdir -p "$(bat --config-dir)/syntaxes"
285 cd "$(bat --config-dir)/syntaxes"
286 # 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 # And then build the cache.
292 bat cache --build
293 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
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
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 To use the preprocessor, call:
313 bat --lessopen
315 Alternatively, the preprocessor may be enabled by default by adding the
317 '--lessopen' option to the configuration file.
318 To temporarily disable the preprocessor if it is enabled by default,
320 call:
321 bat --no-lessopen
323 For more information, see the "INPUT PREPROCESSOR" section of less(1).
325
328 For more information and up-to-date documentation, visit the bat repo:
329 https://github.com/sharkdp/bat
330 BAT(1)