git.iko.soy/bat
on b39e28d help sign in
bat/README.md
378 lines 12 kB history raw
1<p align="center">
2 <img src="doc/logo-header.svg" alt="bat - a cat clone with wings"><br>
3 <a href="https://travis-ci.org/sharkdp/bat"><img src="https://travis-ci.org/sharkdp/bat.svg?branch=master" alt="Build Status"></a>
4 <a href="https://ci.appveyor.com/project/sharkdp/bat"><img src="https://ci.appveyor.com/api/projects/status/cptsmtbiwbnr2vhf?svg=true"></a>
5 <img src="https://img.shields.io/crates/l/bat.svg" alt="license">
6 <a href="https://crates.io/crates/bat"><img src="https://img.shields.io/crates/v/bat.svg?colorB=319e8c" alt="Version info"></a><br>
7 A <i>cat(1)</i> clone with syntax highlighting and Git integration.
8</p>
10<p align="center">
11 <a href="#syntax-highlighting">Key Features</a> •
12 <a href="#how-to-use">How To Use</a> •
13 <a href="#installation">Installation</a> •
14 <a href="#customization">Customization</a> •
15 <a href="#project-goals-and-alternatives">Project goals, alternatives</a>
16</p>
18### Syntax highlighting
20`bat` supports syntax highlighting for a large number of programming and markup
21languages:
23![Syntax highlighting example](https://imgur.com/rGsdnDe.png)
25### Git integration
27`bat` communicates with `git` to show modifications with respect to the index
28(see left side bar):
30![Git integration example](https://i.imgur.com/2lSW4RE.png)
32### Automatic paging
34`bat` can pipe its own output to `less` if the output is too large for one screen.
36### File concatenation
38Oh.. you can also use it to concatenate files :wink:. Whenever
39`bat` detects a non-interactive terminal, it will fall back to printing
40the plain file contents.
42## How to use
44Display a single file on the terminal
46```bash
47> bat README.md
48```
50Display multiple files at once
52```bash
53> bat src/*.rs
54```
56Read from stdin, explicitly specify the language
58```bash
59> yaml2json .travis.yml | json_pp | bat -l json
60```
62```bash
63> curl -s https://raw.githubusercontent.com/sharkdp/bat/master/src/main.rs | bat -l rs
64```
66As a replacement for `cat`:
68```bash
69bat > note.md # quickly create a new file
71bat header.md content.md footer.md > document.md
73bat -n main.rs # show line numbers (only)
75bat f - g # output 'f', then stdin, then 'g'.
76```
78## Installation
80### On Ubuntu
81*... and other Debian-based Linux distributions.*
83Download the latest `.deb` package from the [release page](https://github.com/sharkdp/bat/releases)
84and install it via:
85``` bash
86sudo dpkg -i bat_0.7.1_amd64.deb # adapt version number and architecture
87```
89### On Arch Linux
91You can install [the `bat` package](https://www.archlinux.org/packages/community/x86_64/bat/)
92from the official sources:
94```bash
95pacman -S bat
96```
98### On Void Linux
100You can install `bat` via xbps-install:
101```
102xbps-install -S bat
103```
105### On FreeBSD
107You can install a precompiled [`bat` package](https://www.freshports.org/textproc/bat) with pkg:
109```bash
110pkg install bat
111```
113or build it on your own from the FreeBSD ports:
115```bash
116cd /usr/ports/textproc/bat
117make install
118```
120### Via Ansible
122You can install `bat` with [Ansible](https://www.ansible.com/):
124```bash
125# Install role on local machine
126ansible-galaxy install aeimer.install_bat
127```
129```yaml
130---
131# Playbook to install bat
132- host: all
133 roles:
134 - aeimer.install_bat
135```
137- [Ansible Galaxy](https://galaxy.ansible.com/aeimer/install_bat)
138- [GitHub](https://github.com/aeimer/ansible-install-bat)
140This should work with the following distributions:
141- Debian/Ubuntu
142- ARM (eg. Raspberry PI)
143- Arch Linux
144- Void Linux
145- FreeBSD
146- MacOS
148### On macOS
150You can install `bat` with [Homebrew](http://braumeister.org/formula/bat):
152```bash
153brew install bat
154```
156### On Windows
158You can download prebuilt binaries from the [Release page](https://github.com/sharkdp/bat/releases),
159or install it with [scoop](https://scoop.sh/):
161```bash
162scoop install bat
163```
165[See below](#using-bat-on-windows) for notes.
167### From binaries
169Check out the [Release page](https://github.com/sharkdp/bat/releases) for
170prebuilt versions of `bat` for many different architectures.
172### From source
174If you want to build `bat` from source, you need Rust 1.26 or
175higher. You can then use `cargo` to build everything:
177```bash
178cargo install bat
179```
181You may have to install `cmake` and the `libz` development package
182(`libz-dev` or `libz-devel`) in order for the build to succeed.
184## Customization
186### Highlighting theme
188Use `bat --list-themes` to get a list of all available themes for syntax
189highlighting. To select the `TwoDark` theme, call `bat` with the
190`--theme=TwoDark` option or set the `BAT_THEME` environment variable to
191`TwoDark`. Use `export BAT_THEME="TwoDark"` in your shell's startup file to
192make the change permanent.
194### Output style
196You can use the `--style` option to control the appearance of `bat`s output.
197You can use `--style=numbers,changes`, for example, to show only Git changes
198and line numbers but no grid and no file header. Use the `BAT_STYLE` environment
199variable to make these changes permanent.
201### Adding new syntaxes / language definitions
203`bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)
204library for syntax highlighting. `syntect` can read any
205[Sublime Text `.sublime-syntax` file](https://www.sublimetext.com/docs/3/syntax.html)
206and theme. To add new syntax definitions, do the following.
208Create a folder with syntax definition files:
210```bash
211BAT_CONFIG_DIR="$(bat cache --config-dir)"
213mkdir -p "$BAT_CONFIG_DIR/syntaxes"
214cd "$BAT_CONFIG_DIR/syntaxes"
216# Put new '.sublime-syntax' language definition files
217# in this folder (or its subdirectories), for example:
218git clone https://github.com/tellnobody1/sublime-purescript-syntax
219```
221Now use the following command to parse these files into a binary cache:
223```bash
224bat cache --init
225```
227Finally, use `bat --list-languages` to check if the new languages are available.
229If you ever want to go back to the default settings, call:
231```bash
232bat cache --clear
233```
235### Adding new themes
237This works very similar to how we add new syntax definitions.
239First, create a folder with the new syntax highlighting themes:
240```bash
241BAT_CONFIG_DIR="$(bat cache --config-dir)"
243mkdir -p "$BAT_CONFIG_DIR/themes"
244cd "$BAT_CONFIG_DIR/themes"
246# Download a theme in '.tmTheme' format, for example:
247git clone https://github.com/greggb/sublime-snazzy
249# Update the binary cache
250bat cache --init
251```
253Finally, use `bat --list-themes` to check if the new themes are available.
255### Using a different pager
257`bat` uses the pager that is specified in the `PAGER` environment variable. If this variable is not
258set, `less` is used by default. If you want to use a different pager, you can either modify the
259`PAGER` variable or set the `BAT_PAGER` environment variable to override what is specified in
260`PAGER`.
262If you want to pass command-line arguments to the pager, you need to create a small shell
263script as a wrapper, for example
265```bash
266#!/bin/bash
268less --tabs 4 -R "$@"
269```
270(put this in a file `~/.bat-pager.sh`, make it executable `chmod +x ~/.bat-pager.sh` and use
271`export BAT_PAGER="$HOME/.bat-pager.sh"` in your shells `rc` file)
273**Note**: By default, if the pager is set to `less`, `bat` will pass the following command line
274options to the pager: `-R`/`--RAW-CONTROL-CHARS`, `-F`/`--quit-if-one-screen` and `-X`/`--no-init`.
275The first (`-R`) is needed to interpret ANSI colors correctly. The second option (`-F`) instructs
276less to exit immediately if the output size is smaller than the vertical size of the terminal.
277This is convenient for small files because you do not have to press `q` to quit the pager. The
278third option (`-X`) is needed to fix a bug with the `--quit-if-one-screen` feature in old versions
279of `less`. Unfortunately, it also breaks mouse-wheel support in `less`. If you want to enable
280mouse-wheel scrolling, you can either pass just `-R` (as in the example above, this will disable
281the quit-if-one-screen feature), or you can use a recent version of `less` and pass `-RF` which
282will hopefully enable both quit-if-one-screen and mouse-wheel scrolling.
284If scrolling still doesn't work for you, you can try to pass the `-S` option in addition.
286## Using `bat` on Windows
288`bat` mostly works out-of-the-box on Windows, but a few features may need extra configuration.
290### Paging
292Windows only includes a very limited pager in the form of `more`. You can download a Windows binary
293for `less` [from its homepage](http://www.greenwoodsoftware.com/less/download.html) or [through
294Chocolatey](https://chocolatey.org/packages/Less). To use it, place the binary in a directory in
295your `PATH` or [define an environment variable](#using-a-different-pager).
297### Colours
299Windows 10 natively supports colours in both `conhost.exe` (Command Prompt) and PowerShell since
300[v1511](https://en.wikipedia.org/wiki/Windows_10_version_history#Version_1511_(November_Update)), as
301well as in newer versions of bash. On earlier versions of Windows, you can use
302[Cmder](http://cmder.net/), which includes [ConEmu](https://conemu.github.io/).
304**Note:** The Git and MSYS versions of `less` do not correctly interpret colours on Windows. If you
305don’t have any other pagers installed, you can disable paging entirely by passing `--paging=never`
306or by setting `BAT_PAGER` to an empty string.
308### Cygwin
310`bat` on Windows does not natively support Cygwin's unix-style paths (`/cygdrive/*`). When passed an absolute cygwin path as an argument, `bat` will encounter the following error: `The system cannot find the path specified. (os error 3)`
312This can be solved by creating a wrapper or adding the following function to your `.bash_profile` file:
314```shell
315bat() {
316 local index
317 local args=("$@")
318 for index in $(seq 0 ${#args[@]}) ; do
319 case "${args[index]}" in
320 -*) continue;;
321 *) [ -e "${args[index]}" ] && args[index]="$(cygpath --windows "${args[index]}")";;
322 esac
323 done
324 command bat "${args[@]}"
326```
328## Troubleshooting
330### Terminals & colors
332`bat` handles terminals *with* and *without* truecolor support. However, the colors in the syntax
333highlighting themes are not optimized for 8-bit colors and it is therefore strongly recommended
334that you use a terminal with 24-bit truecolor support (`terminator`, `konsole`, `iTerm2`, ...).
335See [this article](https://gist.github.com/XVilka/8346728) for more details and a full list of
336terminals with truecolor support.
338Make sure that your truecolor terminal sets the `COLORTERM` variable to either `truecolor` or
339`24bit`. Otherwise, `bat` will not be able to determine whether or not 24-bit escape sequences
340are supported (and fall back to 8-bit colors).
342### Line numbers and grid are hardly visible
344Please try a different theme (see `bat --list-themes` for a list). The `OneHalfDark` and
345`OneHalfLight` themes provide grid and line colors that are brighter.
347## Development
349```bash
350# Recursive clone to retrieve all submodules
351git clone --recursive https://github.com/sharkdp/bat
353# Build (debug version)
354cd bat
355cargo build
357# Run unit tests and integration tests
358cargo test
360# Install (release version)
361cargo install
363# Build a bat binary with modified syntaxes and themes
364bash assets/create.sh
365cargo install -f
366```
368## Project goals and alternatives
370`bat` tries to achieve the following goals:
372- Provide beautiful, advanced syntax highlighting
373- Integrate with Git to show file modifications
374- Be a drop-in replacement for (POSIX) `cat`
375- Offer a user-friendly command-line interface
377There are a lot of alternatives, if you are looking for similar programs. See
378[this document](doc/alternatives.md) for a comparison.