git.iko.soy/bat
on c7cce07 help sign in
bat/README.md
274 lines 7.5 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.6.0_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### On macOS
122You can install `bat` with [Homebrew](http://braumeister.org/formula/bat):
124```bash
125brew install bat
126```
128### From binaries
130Check out the [Release page](https://github.com/sharkdp/bat/releases) for
131prebuilt versions of `bat` for many different architectures.
133### From source
135If you want to build `bat` from source, you need Rust 1.26 or
136higher. You can then use `cargo` to build everything:
138```bash
139cargo install bat
140```
142On macOS, you might have to install `cmake` (`brew install cmake`) in order for
143some dependencies to be built.
145## Customization
147### Highlighting theme
149Use `bat --list-themes` to get a list of all available themes for syntax
150highlighting. To select the `TwoDark` theme, call `bat` with the
151`--theme=TwoDark` option or set the `BAT_THEME` environment variable to
152`TwoDark`. Use `export BAT_THEME="TwoDark"` in your shells startup file to
153make the change permanent.
155### Output style
157You can use the `--style` option to control the appearance of `bat`s output.
158You can use `--style=numbers,changes`, for example, to show only Git changes
159and line numbers but no grid and no file header.
161### Adding new syntaxes / language definitions
163`bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)
164library for syntax highlighting. `syntect` can read any
165[Sublime Text `.sublime-syntax` file](https://www.sublimetext.com/docs/3/syntax.html)
166and theme. To add new syntax definitions, do the following.
168Create a folder with syntax definition files:
170```bash
171BAT_CONFIG_DIR="$(bat cache --config-dir)"
173mkdir -p "$BAT_CONFIG_DIR/syntaxes"
174cd "$BAT_CONFIG_DIR/syntaxes"
176# Put new '.sublime-syntax' language definition files
177# in this folder (or its subdirectories), for example:
178git clone https://github.com/tellnobody1/sublime-purescript-syntax
179```
181Now use the following command to parse these files into a binary cache:
183```bash
184bat cache --init
185```
187Finally, use `bat --list-languages` to check if the new languages are available.
189If you ever want to go back to the default settings, call:
191```bash
192bat cache --clear
193```
195### Adding new themes
197This works very similar to how we add new syntax definitions.
199First, create a folder with the new syntax highlighting themes:
200```bash
201BAT_CONFIG_DIR="$(bat cache --config-dir)"
203mkdir -p "$BAT_CONFIG_DIR/themes"
204cd "$BAT_CONFIG_DIR/themes"
206# Download a theme in '.tmTheme' format, for example:
207git clone https://github.com/greggb/sublime-snazzy
209# Update the binary cache
210bat cache --init
211```
213Finally, use `bat --list-themes` to check if the new themes are available.
215### Using a different pager
217`bat` uses the pager that is specified in the `PAGER` environment variable. If this variable is not
218set, `less` is used by default. If you want to use a different pager, you can either modify the
219`PAGER` variable or set the `BAT_PAGER` environment variable to override what is specified in
220`PAGER`. If you want to pass command-line arguments to the pager, you need to create a small shell
221script as a wrapper, for example:
223```bash
224#!/bin/bash
226less --tabs 4 -RF "$@"
227```
229## Troubleshooting
231### Terminals & colors
233`bat` handles terminals *with* and *without* truecolor support. However, the colors in the syntax
234highlighting themes are not optimized for 8-bit colors and it is therefore strongly recommended
235that you use a terminal with 24-bit truecolor support (`terminator`, `konsole`, `iTerm2`, ...).
236See [this article](https://gist.github.com/XVilka/8346728) for more details and a full list of
237terminals with truecolor support.
239Make sure that your truecolor terminal sets the `COLORTERM` variable to either `truecolor` or
240`24bit`. Otherwise, `bat` will not be able to determine whether or not 24-bit escape sequences
241are supported (and fall back to 8-bit colors).
243## Development
245```bash
246# Recursive clone to retrieve all submodules
247git clone --recursive https://github.com/sharkdp/bat
249# Build (debug version)
250cd bat
251cargo build
253# Run unit tests and integration tests
254cargo test
256# Install (release version)
257cargo install
259# Build a bat binary with modified syntaxes and themes
260bash assets/create.sh
261cargo install -f
262```
264## Project goals and alternatives
266`bat` tries to achieve the following goals:
268- Provide beautiful, advanced syntax highlighting
269- Integrate with Git to show file modifications
270- Be a drop-in replacement for (POSIX) `cat`
271- Offer a user-friendly command-line interface
273There are a lot of alternatives, if you are looking for similar programs. See
274[this document](doc/alternatives.md) for a comparison.