16 |
17 | ### Syntax highlighting
18 |
19 | `bat` supports syntax highlighting for a large number of programming and markup
20 | languages:
21 |
22 | 
23 |
24 | ### Git integration
25 |
26 | `bat` communicates with `git` to show modifications with respect to the index
27 | (see left side bar):
28 |
29 | 
30 |
31 | ### Automatic paging
32 |
33 | `bat` can pipe its own output to `less` if the output is too large for one screen.
34 |
35 | ### File concatenation
36 |
37 | Oh.. you can also use it to concatenate files :wink:. Whenever
38 | `bat` detects a non-interactive terminal, it will fall back to printing
39 | the plain file contents.
40 |
41 | ## How to use
42 |
43 | Display a single file on the terminal
44 |
45 | ```bash
46 | > bat README.md
47 | ```
48 |
49 | Display multiple files at once
50 |
51 | ```bash
52 | > bat src/*.rs
53 | ```
54 |
55 | Read from stdin, explicitly specify the language
56 |
57 | ```bash
58 | > yaml2json .travis.yml | json_pp | bat -l json
59 | ```
60 |
61 | ```bash
62 | > curl -s https://raw.githubusercontent.com/sharkdp/bat/master/src/main.rs | bat -l rs
63 | ```
64 |
65 | As a replacement for `cat`:
66 |
67 | ```bash
68 | bat > note.md # quickly create a new file
69 |
70 | bat header.md content.md footer.md > document.md
71 |
72 | bat -n main.rs # show line numbers (only)
73 |
74 | bat f - g # output 'f', then stdin, then 'g'.
75 | ```
76 |
77 | ## Installation
78 |
79 | ### On Ubuntu
80 | *... and other Debian-based Linux distributions.*
81 |
82 | Download the latest `.deb` package from the [release page](https://github.com/sharkdp/bat/releases)
83 | and install it via:
84 | ``` bash
85 | sudo dpkg -i bat_0.6.0_amd64.deb # adapt version number and architecture
86 | ```
87 |
88 | ### On Arch Linux
89 |
90 | You can install [the `bat` package](https://www.archlinux.org/packages/community/x86_64/bat/)
91 | from the official sources:
92 |
93 | ```bash
94 | pacman -S bat
95 | ```
96 |
97 | ### On Void Linux
98 |
99 | You can install `bat` via xbps-install:
100 | ```
101 | xbps-install -S bat
102 | ```
103 |
104 | ### On FreeBSD
105 |
106 | You can install a precompiled [`bat` package](https://www.freshports.org/textproc/bat) with pkg:
107 |
108 | ```bash
109 | pkg install bat
110 | ```
111 |
112 | or build it on your own from the FreeBSD ports:
113 |
114 | ```bash
115 | cd /usr/ports/textproc/bat
116 | make install
117 | ```
118 |
119 | ### On macOS
120 |
121 | You can install `bat` with [Homebrew](http://braumeister.org/formula/bat):
122 |
123 | ```bash
124 | brew install bat
125 | ```
126 |
127 | ### From binaries
128 |
129 | Check out the [Release page](https://github.com/sharkdp/bat/releases) for
130 | prebuilt versions of `bat` for many different architectures.
131 |
132 | ### From source
133 |
134 | If you want to build `bat` from source, you need Rust 1.26 or
135 | higher. You can then use `cargo` to build everything:
136 |
137 | ```bash
138 | cargo install bat
139 | ```
140 |
141 | On macOS, you might have to install `cmake` (`brew install cmake`) in order for
142 | some dependencies to be built.
143 |
144 | ## Customization
145 |
146 | ### Highlighting theme
147 |
148 | Use `bat --list-themes` to get a list of all available themes for syntax
149 | highlighting. To select the `TwoDark` theme, call `bat` with the
150 | `--theme=TwoDark` option or set the `BAT_THEME` environment variable to
151 | `TwoDark`. Use `export BAT_THEME="TwoDark"` in your shells startup file to
152 | make the change permanent.
153 |
154 | ### Output style
155 |
156 | You can use the `--style` option to control the appearance of `bat`s output.
157 | You can use `--style=numbers,changes`, for example, to show only Git changes
158 | and line numbers but no grid and no file header.
159 |
160 | ### Adding new syntaxes / language definitions
161 |
162 | `bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)
163 | library for syntax highlighting. `syntect` can read any
164 | [Sublime Text `.sublime-syntax` file](https://www.sublimetext.com/docs/3/syntax.html)
165 | and theme. To add new syntax definitions, do the following.
166 |
167 | Create a folder with syntax definition files:
168 |
169 | ```bash
170 | BAT_CONFIG_DIR="$(bat cache --config-dir)"
171 |
172 | mkdir -p "$BAT_CONFIG_DIR/syntaxes"
173 | cd "$BAT_CONFIG_DIR/syntaxes"
174 |
175 | # Put new '.sublime-syntax' language definition files
176 | # in this folder (or its subdirectories), for example:
177 | git clone https://github.com/tellnobody1/sublime-purescript-syntax
178 | ```
179 |
180 | Now use the following command to parse these files into a binary cache:
181 |
182 | ```bash
183 | bat cache --init
184 | ```
185 |
186 | Finally, use `bat --list-languages` to check if the new languages are available.
187 |
188 | If you ever want to go back to the default settings, call:
189 |
190 | ```bash
191 | bat cache --clear
192 | ```
193 |
194 | ### Adding new themes
195 |
196 | This works very similar to how we add new syntax definitions.
197 |
198 | First, create a folder with the new syntax highlighting themes:
199 | ```bash
200 | BAT_CONFIG_DIR="$(bat cache --config-dir)"
201 |
202 | mkdir -p "$BAT_CONFIG_DIR/themes"
203 | cd "$BAT_CONFIG_DIR/themes"
204 |
205 | # Download a theme in '.tmTheme' format, for example:
206 | git clone https://github.com/greggb/sublime-snazzy
207 |
208 | # Update the binary cache
209 | bat cache --init
210 | ```
211 |
212 | Finally, use `bat --list-themes` to check if the new themes are available.
213 |
214 | ### Using a different pager
215 |
216 | `bat` uses the pager that is specified in the `PAGER` environment variable. If this variable is not
217 | set, `less` is used by default. If you want to use a different pager, you can either modify the
218 | `PAGER` variable or set the `BAT_PAGER` environment variable to override what is specified in
219 | `PAGER`. If you want to pass command-line arguments to the pager, you need to create a small shell
220 | script as a wrapper, for example:
221 |
222 | ```bash
223 | #!/bin/bash
224 |
225 | less --tabs 4 -RF "$@"
226 | ```
227 |
228 | ## Troubleshooting
229 |
230 | ### Terminals & colors
231 |
232 | `bat` handles terminals *with* and *without* truecolor support. However, the colors in the syntax
233 | highlighting themes are not optimized for 8-bit colors and it is therefore strongly recommended
234 | that you use a terminal with 24-bit truecolor support (`terminator`, `konsole`, `iTerm2`, ...).
235 | See [this article](https://gist.github.com/XVilka/8346728) for more details and a full list of
236 | terminals with truecolor support.
237 |
238 | Make sure that your truecolor terminal sets the `COLORTERM` variable to either `truecolor` or
239 | `24bit`. Otherwise, `bat` will not be able to determine whether or not 24-bit escape sequences
240 | are supported (and fall back to 8-bit colors).
241 |
242 | ## Development
243 |
244 | ```bash
245 | # Recursive clone to retrieve all submodules
246 | git clone --recursive https://github.com/sharkdp/bat
247 |
248 | # Build (debug version)
249 | cd bat
250 | cargo build
251 |
252 | # Run unit tests and integration tests
253 | cargo test
254 |
255 | # Install (release version)
256 | cargo install
257 |
258 | # Build a bat binary with modified syntaxes and themes
259 | bash assets/create.sh
260 | cargo install -f
261 | ```
262 |
263 | ## Project goals and alternatives
264 |
265 | `bat` tries to achieve the following goals:
266 |
267 | - Provide beautiful, advanced syntax highlighting
268 | - Integrate with Git to show file modifications
269 | - Be a drop-in replacement for (POSIX) `cat`
270 | - Offer a user-friendly command-line interface
271 |
272 | There are a lot of alternatives, if you are looking for similar programs. See
273 | [this document](doc/alternatives.md) for a comparison.
274 |
--------------------------------------------------------------------------------
/doc/logo-header.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
44 | 
45 | 