bat/README.md

228 lines
6.0 KiB
Markdown
Raw Normal View History

2018-05-22 21:54:34 +02:00
<p align="center">
<img src="doc/logo-header.svg" alt="bat - a cat clone with wings"><br>
2018-07-17 23:37:03 +02:00
<a href="https://travis-ci.org/sharkdp/bat"><img src="https://travis-ci.org/sharkdp/bat.svg?branch=master" alt="Build Status"></a>
2018-05-30 21:02:40 +02:00
<img src="https://img.shields.io/crates/l/bat.svg" alt="license">
2018-05-30 21:10:14 +02:00
<a href="https://crates.io/crates/bat"><img src="https://img.shields.io/crates/v/bat.svg?colorB=319e8c" alt="Version info"></a><br>
2018-05-22 21:54:34 +02:00
A <i>cat(1)</i> clone with syntax highlighting and Git integration.
</p>
2018-04-21 14:23:57 +02:00
2018-05-30 21:23:24 +02:00
<p align="center">
<a href="#syntax-highlighting">Key Features</a>
<a href="#how-to-use">How To Use</a>
<a href="#installation">Installation</a>
<a href="#customization">Customization</a>
<a href="#project-goals-and-alternatives">Project goals, alternatives</a>
</p>
2018-04-22 15:30:28 +02:00
### Syntax highlighting
2018-05-07 20:06:01 +02:00
`bat` supports syntax highlighting for a large number of programming and markup
languages:
2018-04-22 15:30:28 +02:00
2018-04-26 00:02:53 +02:00
![Syntax highlighting example](https://imgur.com/rGsdnDe.png)
2018-04-22 15:30:28 +02:00
### Git integration
2018-05-07 20:06:01 +02:00
`bat` communicates with `git` to show modifications with respect to the index
(see left side bar):
2018-04-26 00:02:53 +02:00
2018-04-26 00:03:25 +02:00
![Git integration example](https://i.imgur.com/2lSW4RE.png)
2018-04-22 16:15:07 +02:00
### Automatic paging
`bat` can pipe its own output to `less` if the output is too large for one screen.
### File concatenation
Oh.. you can also use it to concatenate files :wink:. Whenever
`bat` detects a non-interactive terminal, it will fall back to printing
the plain file contents.
2018-05-30 21:23:24 +02:00
## How to use
2018-05-09 00:33:49 +02:00
Display a single file on the terminal
```bash
2018-05-09 00:33:49 +02:00
> bat README.md
```
Display multiple files at once
```bash
2018-05-09 00:33:49 +02:00
> bat src/*.rs
```
2018-05-30 21:32:40 +02:00
Read from stdin, explicitly specify the language
2018-05-09 00:33:49 +02:00
```bash
2018-05-09 00:33:49 +02:00
> yaml2json .travis.yml | json_pp | bat -l json
```
```bash
2018-05-09 00:33:49 +02:00
> curl -s https://raw.githubusercontent.com/sharkdp/bat/master/src/main.rs | bat -l rs
```
2018-05-31 22:57:18 +02:00
As a replacement for `cat`:
```bash
bat > note.md # quickly create a new file
bat header.md content.md footer.md > document.md
bat -n main.rs # show line numbers (only)
2018-06-01 16:32:33 +02:00
bat f - g # output 'f', then stdin, then 'g'.
2018-05-31 22:57:18 +02:00
```
2018-05-09 00:33:49 +02:00
2018-04-22 16:15:07 +02:00
## Installation
2018-05-02 20:01:43 +02:00
### From binaries
2018-05-07 20:06:01 +02:00
Check out the [Release page](https://github.com/sharkdp/bat/releases) for
binary builds and Debian packages.
2018-04-26 00:02:53 +02:00
#### On Arch Linux
2018-06-08 11:34:57 +02:00
You can install via Pacman:
```bash
2018-06-08 11:34:57 +02:00
pacman -S bat
```
#### On FreeBSD
You can install a precompiled [`bat` package](https://www.freshports.org/textproc/bat) with pkg:
```bash
pkg install bat
```
or build it on your own from the FreeBSD ports:
```bash
cd /usr/ports/textproc/bat
make install
```
#### On macOS
You can install `bat` with [Homebrew](http://braumeister.org/formula/bat):
```bash
brew install bat
```
### From source
2018-08-18 21:30:12 +02:00
If you want to build to compile `bat` from source, you need Rust 1.26 or
2018-05-07 20:06:01 +02:00
higher. You can then use `cargo` to build everything:
```bash
2018-04-22 16:15:07 +02:00
cargo install bat
2018-04-26 00:02:53 +02:00
```
2018-04-30 16:03:33 +02:00
On macOS, you might have to install `cmake` (`brew install cmake`) in order for
some dependencies to be built.
2018-04-30 16:03:33 +02:00
## Customization
2018-05-30 21:32:40 +02:00
### Highlighting theme
Use `bat --list-themes` to get a list of all available themes for syntax
2018-07-23 21:58:06 +02:00
highlighting. To select the `TwoDark` theme, call `bat` with the
`--theme=TwoDark` option or set the `BAT_THEME` environment variable to
`TwoDark`. Use `export BAT_THEME="TwoDark"` in your shells startup file to
make the change permanent.
2018-05-30 21:32:40 +02:00
### Output style
You can use the `--style` option to control the appearance of `bat`s output.
You can use `--style=numbers,changes`, for example, to show only Git changes
and line numbers but no grid and no file header.
### Adding new syntaxes / language definitions
2018-05-30 21:32:40 +02:00
2018-05-07 20:06:01 +02:00
`bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)
library for syntax highlighting. `syntect` can read any
[Sublime Text `.sublime-syntax` file](https://www.sublimetext.com/docs/3/syntax.html)
and theme. To add new syntax definitions, do the following.
2018-04-30 16:03:33 +02:00
Create a folder with syntax definition files:
2018-05-02 22:21:56 +02:00
```bash
BAT_CONFIG_DIR="$(bat cache --config-dir)"
mkdir -p "$BAT_CONFIG_DIR/syntaxes"
cd "$BAT_CONFIG_DIR/syntaxes"
2018-04-30 16:03:33 +02:00
# Put new '.sublime-syntax' language definition files
# in this folder (or its subdirectories), for example:
git clone https://github.com/tellnobody1/sublime-purescript-syntax
2018-04-30 16:03:33 +02:00
```
Now use the following command to parse these files into a binary cache:
2018-05-02 22:21:56 +02:00
```bash
bat cache --init
```
Finally, use `bat --list-languages` to check if the new languages are available.
If you ever want to go back to the default settings, call:
```bash
bat cache --clear
2018-04-30 16:03:33 +02:00
```
### Adding new themes
This works very similar to how we add new syntax definitions.
First, create a folder with the new syntax highlighting themes:
```bash
BAT_CONFIG_DIR="$(bat cache --config-dir)"
mkdir -p "$BAT_CONFIG_DIR/themes"
cd "$BAT_CONFIG_DIR/themes"
# Download a theme in '.tmTheme' format, for example:
git clone https://github.com/greggb/sublime-snazzy
# Create a link to specify the new default theme
ln -sf "sublime-snazzy/Sublime Snazzy.tmTheme" Default.tmTheme
# Update the binary cache
bat cache --init
```
Finally, use `bat --list-themes` to check if the new themes are available.
**Note:** Unlike for syntax definitions, adding custom themes currently *removes all default
themes*. If you want to go back to the default themes, call `bat cache --clear`.
### Using a different pager
`bat` uses the pager that is specified in the `PAGER` environment variable. If this variable is not
set, `less` is used by default. If you want to use a different pager, you can either modify the
`PAGER` variable or set the `BAT_PAGER` environment variable to override what is specified in
`PAGER`. If you want to pass command-line arguments to the pager, you need to create a small shell
script as a wrapper, for example:
```bash
#!/bin/bash
less --tabs 4 -RF "$@"
```
## Project goals and alternatives
`bat` tries to achieve the following goals:
- Provide beautiful, advanced syntax highlighting
- Integrate with Git to show file modifications
- Be a drop-in replacement for (POSIX) `cat`
- Offer a user-friendly command-line interface
There are a lot of alternatives, if you are looking for similar programs. See
[this document](doc/alternatives.md) for a comparison.