mirror of https://github.com/sharkdp/bat.git
274 lines
7.2 KiB
Markdown
274 lines
7.2 KiB
Markdown
<p align="center">
|
|
<img src="doc/logo-header.svg" alt="bat - a cat clone with wings"><br>
|
|
<a href="https://travis-ci.org/sharkdp/bat"><img src="https://travis-ci.org/sharkdp/bat.svg?branch=master" alt="Build Status"></a>
|
|
<img src="https://img.shields.io/crates/l/bat.svg" alt="license">
|
|
<a href="https://crates.io/crates/bat"><img src="https://img.shields.io/crates/v/bat.svg?colorB=319e8c" alt="Version info"></a><br>
|
|
A <i>cat(1)</i> clone with syntax highlighting and Git integration.
|
|
</p>
|
|
|
|
<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>
|
|
|
|
### Syntax highlighting
|
|
|
|
`bat` supports syntax highlighting for a large number of programming and markup
|
|
languages:
|
|
|
|
|
|
|
|
### Git integration
|
|
|
|
`bat` communicates with `git` to show modifications with respect to the index
|
|
(see left side bar):
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
## How to use
|
|
|
|
Display a single file on the terminal
|
|
|
|
```bash
|
|
> bat README.md
|
|
```
|
|
|
|
Display multiple files at once
|
|
|
|
```bash
|
|
> bat src/*.rs
|
|
```
|
|
|
|
Read from stdin, explicitly specify the language
|
|
|
|
```bash
|
|
> yaml2json .travis.yml | json_pp | bat -l json
|
|
```
|
|
|
|
```bash
|
|
> curl -s https://raw.githubusercontent.com/sharkdp/bat/master/src/main.rs | bat -l rs
|
|
```
|
|
|
|
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)
|
|
|
|
bat f - g # output 'f', then stdin, then 'g'.
|
|
```
|
|
|
|
## Installation
|
|
|
|
### On Ubuntu
|
|
*... and other Debian-based Linux distributions.*
|
|
|
|
Download the latest `.deb` package from the [release page](https://github.com/sharkdp/bat/releases)
|
|
and install it via:
|
|
``` bash
|
|
sudo dpkg -i bat_0.6.0_amd64.deb # adapt version number and architecture
|
|
```
|
|
|
|
### On Arch Linux
|
|
|
|
You can install [the `bat` package](https://www.archlinux.org/packages/community/x86_64/bat/)
|
|
from the official sources:
|
|
|
|
```bash
|
|
pacman -S bat
|
|
```
|
|
|
|
### On Void Linux
|
|
|
|
You can install `bat` via xbps-install:
|
|
```
|
|
xbps-install -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 binaries
|
|
|
|
Check out the [Release page](https://github.com/sharkdp/bat/releases) for
|
|
prebuilt versions of `bat` for many different architectures.
|
|
|
|
### From source
|
|
|
|
If you want to build `bat` from source, you need Rust 1.26 or
|
|
higher. You can then use `cargo` to build everything:
|
|
|
|
```bash
|
|
cargo install bat
|
|
```
|
|
|
|
On macOS, you might have to install `cmake` (`brew install cmake`) in order for
|
|
some dependencies to be built.
|
|
|
|
## Customization
|
|
|
|
### Highlighting theme
|
|
|
|
Use `bat --list-themes` to get a list of all available themes for syntax
|
|
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.
|
|
|
|
### 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
|
|
|
|
`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.
|
|
|
|
Create a folder with syntax definition files:
|
|
|
|
```bash
|
|
BAT_CONFIG_DIR="$(bat cache --config-dir)"
|
|
|
|
mkdir -p "$BAT_CONFIG_DIR/syntaxes"
|
|
cd "$BAT_CONFIG_DIR/syntaxes"
|
|
|
|
# Put new '.sublime-syntax' language definition files
|
|
# in this folder (or its subdirectories), for example:
|
|
git clone https://github.com/tellnobody1/sublime-purescript-syntax
|
|
```
|
|
|
|
Now use the following command to parse these files into a binary cache:
|
|
|
|
```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
|
|
```
|
|
|
|
### 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
|
|
|
|
# Update the binary cache
|
|
bat cache --init
|
|
```
|
|
|
|
Finally, use `bat --list-themes` to check if the new themes are available.
|
|
|
|
### 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 "$@"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Terminals & colors
|
|
|
|
`bat` handles terminals *with* and *without* truecolor support. However, the colors in the syntax
|
|
highlighting themes are not optimized for 8-bit colors and it is therefore strongly recommended
|
|
that you use a terminal with 24-bit truecolor support (`terminator`, `konsole`, `iTerm2`, ...).
|
|
See [this article](https://gist.github.com/XVilka/8346728) for more details and a full list of
|
|
terminals with truecolor support.
|
|
|
|
Make sure that your truecolor terminal sets the `COLORTERM` variable to either `truecolor` or
|
|
`24bit`. Otherwise, `bat` will not be able to determine whether or not 24-bit escape sequences
|
|
are supported (and fall back to 8-bit colors).
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Recursive clone to retrieve all submodules
|
|
git clone --recursive https://github.com/sharkdp/bat
|
|
|
|
# Build (debug version)
|
|
cd bat
|
|
cargo build
|
|
|
|
# Run unit tests and integration tests
|
|
cargo test
|
|
|
|
# Install (release version)
|
|
cargo install
|
|
|
|
# Build a bat binary with modified syntaxes and themes
|
|
bash assets/create.sh
|
|
cargo install -f
|
|
```
|
|
|
|
## 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.
|