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 -p, --plain
40 Only show plain style, no decorations. This is an alias for
42 '--style=plain'. When '-p' is used twice ('-pp'), it also dis‐
43 ables automatic paging (alias for '--style=plain
44 --pager=never').
45 -l, --language <language>
47 Explicitly set the language for syntax highlighting. The lan‐
49 guage can be specified as a name (like 'C++' or 'LaTeX') or pos‐
50 sible file extension (like 'cpp', 'hpp' or 'md'). Use
51 '--list-languages' to show all supported language names and file
52 extensions.
53 -H, --highlight-line <N:M>...
55 Highlight the specified line ranges with a different background
57 color. For example:
58 --highlight-line 40
60 highlights line 40
61 --highlight-line 30:40
63 highlights lines 30 to 40
64 --highlight-line :40
66 highlights lines 1 to 40
67 --highlight-line 40:
69 highlights lines 40 to the end of the file
70 --highlight-line 30:+10
72 highlights lines 30 to 40
73 --file-name <name>...
75 Specify the name to display for a file. Useful when piping data
77 to bat from STDIN when bat does not otherwise know the filename.
78 Note that the provided file name is also used for syntax detec‐
79 tion.
80 -d, --diff
82 Only show lines that have been added/removed/modified with re‐
84 spect to the Git index. Use '--diff-context=N' to control how
85 much context you want to see.
86 --diff-context <N>...
88 Include N lines of context around added/removed/modified lines
90 when using '--diff'.
91 --tabs <T>
93 Set the tab width to T spaces. Use a width of 0 to pass tabs
95 through directly
96 --wrap <mode>
98 Specify the text-wrapping mode (*auto*, never, character). The
100 '--terminal-width' option can be used in addition to control the
101 output width.
102 --terminal-width <width>
104 Explicitly set the width of the terminal instead of determining
106 it automatically. If prefixed with '+' or '-', the value will be
107 treated as an offset to the actual terminal width. See also:
108 '--wrap'.
109 -n, --number
111 Only show line numbers, no other decorations. This is an alias
113 for '--style=numbers'
114 --color <when>
116 Specify when to use colored output. The automatic mode only en‐
118 ables colors if an interactive terminal is detected. Possible
119 values: *auto*, never, always.
120 --italic-text <when>
122 Specify when to use ANSI sequences for italic text in the out‐
124 put. Possible values: always, *never*.
125 --decorations <when>
127 Specify when to use the decorations that have been specified via
129 '--style'. The automatic mode only enables decorations if an in‐
130 teractive terminal is detected. Possible values: *auto*, never,
131 always.
132 -f, --force-colorization
134 Alias for '--decorations=always --color=always'. This is useful
136 if the output of bat is piped to another program, but you want
137 to keep the colorization/decorations.
138 --paging <when>
140 Specify when to use the pager. To disable the pager, use '--pag‐
142 ing=never' or its alias, -P. To disable the pager permanently,
143 set BAT_PAGER to an empty string. To control which pager is
144 used, see the '--pager' option. Possible values: *auto*, never,
145 always.
146 --pager <command>
148 Determine which pager is used. This option will override the
150 PAGER and BAT_PAGER environment variables. The default pager is
151 'less'. To control when the pager is used, see the '--paging'
152 option. Example: '--pager "less -RF"'.
153 Note: By default, if the pager is set to 'less' (and no command-
155 line options are specified), 'bat' will pass the following com‐
156 mand line options to the pager: '-R'/'--RAW-CONTROL-CHARS',
157 '-F'/'--quit-if-one-screen' and '-X'/'--no-init'. The last op‐
158 tion ('-X') is only used for 'less' versions older than 530. The
159 '-R' option is needed to interpret ANSI colors correctly. The
160 second option ('-F') instructs less to exit immediately if the
161 output size is smaller than the vertical size of the terminal.
162 This is convenient for small files because you do not have to
163 press 'q' to quit the pager. The third option ('-X') is needed
164 to fix a bug with the '--quit-if-one-screen' feature in old ver‐
165 sions of 'less'. Unfortunately, it also breaks mouse-wheel sup‐
166 port in 'less'. If you want to enable mouse-wheel scrolling on
167 older versions of 'less', you can pass just '-R' (as in the ex‐
168 ample above, this will disable the quit-if-one-screen feature).
169 For less 530 or newer, it should work out of the box.
170 -m, --map-syntax <glob-pattern:syntax-name>...
172 Map a glob pattern to an existing syntax name. The glob pattern
174 is matched on the full path and the filename. For example, to
175 highlight *.build files with the Python syntax, use -m
176 '*.build:Python'. To highlight files named '.myignore' with the
177 Git Ignore syntax, use -m '.myignore:Git Ignore'. Note that the
178 right-hand side is the *name* of the syntax, not a file exten‐
179 sion.
180 --theme <theme>
182 Set the theme for syntax highlighting. Use '--list-themes' to
184 see all available themes. To set a default theme, add the
185 '--theme="..."' option to the configuration file or export the
186 BAT_THEME environment variable (e.g.: export BAT_THEME="...").
187 --list-themes
189 Display a list of supported themes for syntax highlighting.
191 --style <style-components>
193 Configure which elements (line numbers, file headers, grid bor‐
195 ders, Git modifications, ..) to display in addition to the file
196 contents. The argument is a comma-separated list of components
197 to display (e.g. 'numbers,changes,grid') or a pre-defined style
198 ('full'). To set a default style, add the '--style=".."' option
199 to the configuration file or export the BAT_STYLE environment
200 variable (e.g.: export BAT_STYLE=".."). Possible values: *de‐
201 fault*, full, auto, plain, changes, header, header-filename,
202 header-filesize, grid, rule, numbers, snip.
203 -r, --line-range <N:M>...
205 Only print the specified range of lines for each file. For exam‐
207 ple:
208 --line-range 30:40
210 prints lines 30 to 40
211 --line-range :40
213 prints lines 1 to 40
214 --line-range 40:
216 prints lines 40 to the end of the file
217 --line-range 30:+10
219 prints lines 30 to 40
220 -L, --list-languages
222 Display a list of supported languages for syntax highlighting.
224 -u, --unbuffered
226 This option exists for POSIX-compliance reasons ('u' is for 'un‐
228 buffered'). The output is always unbuffered - this option is
229 simply ignored.
230 -h, --help
232 Print this help message.
234 -V, --version
236 Show version information.
238
240 <FILE>...
241 Files to print and concatenate. Use a dash ('-') or no argument
243 at all to read from standard input.
244
246 cache - Modify the syntax-definition and theme cache.
247
249 bat can also be customized with a configuration file. The location of
250 the file is dependent on your operating system. To get the default path
251 for your system, call:
252 bat --config-file
254 Alternatively, you can use the BAT_CONFIG_PATH environment variable to
256 point bat to a non-default location of the configuration file.
257 To generate a default configuration file, call:
259 bat --generate-config-file
261
263 bat supports Sublime Text .sublime-syntax language files, and can be
264 customized to add additional languages to your local installation. To
265 do this, add the .sublime-syntax language files to `$(bat --config-
266 dir)/syntaxes` and run `bat cache --build`.
267 Example:
269 mkdir -p "$(bat --config-dir)/syntaxes"
271 cd "$(bat --config-dir)/syntaxes"
272 # Put new '.sublime-syntax' language definition files
274 # in this folder (or its subdirectories), for example:
275 git clone https://github.com/tellnobody1/sublime-purescript-syntax
276 # And then build the cache.
278 bat cache --build
279 Once the cache is built, the new language will be visible in `bat
281 --list-languages`.
282 If you ever want to remove the custom languages, you can clear the
283 cache with `bat cache --clear`.
284
287 Similarly to custom languages, bat supports Sublime Text .tmTheme
288 themes. These can be installed to `$(bat --config-dir)/themes`, and
289 are added to the cache with `bat cache --build`.
290
292 For more information and up-to-date documentation, visit the bat repo:
293 https://github.com/sharkdp/bat
294 BAT(1)