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-08-29 18:51:47 +02:00
|
|
|
|
<a href="https://ci.appveyor.com/project/sharkdp/bat"><img src="https://ci.appveyor.com/api/projects/status/cptsmtbiwbnr2vhf?svg=true"></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
|
|
|
|
|
2018-05-09 00:12:25 +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
|
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```bash
|
2018-05-09 00:33:49 +02:00
|
|
|
|
> bat README.md
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Display multiple files at once
|
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```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
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```bash
|
2018-05-09 00:33:49 +02:00
|
|
|
|
> yaml2json .travis.yml | json_pp | bat -l json
|
|
|
|
|
```
|
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```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-08-28 20:55:15 +02:00
|
|
|
|
### On Ubuntu
|
|
|
|
|
*... and other Debian-based Linux distributions.*
|
2018-05-02 20:01:43 +02:00
|
|
|
|
|
2018-08-28 20:55:15 +02:00
|
|
|
|
Download the latest `.deb` package from the [release page](https://github.com/sharkdp/bat/releases)
|
|
|
|
|
and install it via:
|
|
|
|
|
``` bash
|
2018-09-12 22:01:01 +02:00
|
|
|
|
sudo dpkg -i bat_0.6.2_amd64.deb # adapt version number and architecture
|
2018-08-28 20:55:15 +02:00
|
|
|
|
```
|
2018-04-26 00:02:53 +02:00
|
|
|
|
|
2018-08-28 21:04:41 +02:00
|
|
|
|
### On Arch Linux
|
2018-05-01 00:04:40 +02:00
|
|
|
|
|
2018-08-28 20:55:15 +02:00
|
|
|
|
You can install [the `bat` package](https://www.archlinux.org/packages/community/x86_64/bat/)
|
|
|
|
|
from the official sources:
|
2018-05-01 00:04:40 +02:00
|
|
|
|
|
|
|
|
|
```bash
|
2018-06-08 11:34:57 +02:00
|
|
|
|
pacman -S bat
|
2018-05-01 00:04:40 +02:00
|
|
|
|
```
|
|
|
|
|
|
2018-08-28 20:55:15 +02:00
|
|
|
|
### On Void Linux
|
|
|
|
|
|
|
|
|
|
You can install `bat` via xbps-install:
|
|
|
|
|
```
|
|
|
|
|
xbps-install -S bat
|
|
|
|
|
```
|
|
|
|
|
|
2018-08-28 21:04:41 +02:00
|
|
|
|
### On FreeBSD
|
2018-05-16 19:13:13 +02:00
|
|
|
|
|
|
|
|
|
You can install a precompiled [`bat` package](https://www.freshports.org/textproc/bat) with pkg:
|
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```bash
|
2018-05-16 19:13:13 +02:00
|
|
|
|
pkg install bat
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
or build it on your own from the FreeBSD ports:
|
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```bash
|
2018-05-16 19:13:13 +02:00
|
|
|
|
cd /usr/ports/textproc/bat
|
|
|
|
|
make install
|
|
|
|
|
```
|
|
|
|
|
|
2018-08-28 21:04:41 +02:00
|
|
|
|
### On macOS
|
2018-05-10 12:35:07 +02:00
|
|
|
|
|
|
|
|
|
You can install `bat` with [Homebrew](http://braumeister.org/formula/bat):
|
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```bash
|
2018-05-10 12:35:07 +02:00
|
|
|
|
brew install bat
|
|
|
|
|
```
|
|
|
|
|
|
2018-09-01 00:59:30 +02:00
|
|
|
|
### On Windows
|
|
|
|
|
|
2018-09-03 23:41:35 +02:00
|
|
|
|
You can download pre-built binaries from the [Release page](https://github.com/sharkdp/bat/releases),
|
2018-09-04 08:25:24 +02:00
|
|
|
|
or install it with [scoop](https://scoop.sh/):
|
2018-09-03 23:41:35 +02:00
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
scoop install bat
|
|
|
|
|
```
|
2018-09-01 00:59:30 +02:00
|
|
|
|
|
2018-09-08 10:31:33 +02:00
|
|
|
|
[See below](#using-bat-on-windows) for notes.
|
|
|
|
|
|
2018-08-28 20:55:15 +02:00
|
|
|
|
### From binaries
|
|
|
|
|
|
|
|
|
|
Check out the [Release page](https://github.com/sharkdp/bat/releases) for
|
|
|
|
|
prebuilt versions of `bat` for many different architectures.
|
|
|
|
|
|
2018-04-30 15:40:51 +02:00
|
|
|
|
### From source
|
|
|
|
|
|
2018-08-28 20:55:15 +02:00
|
|
|
|
If you want to build `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:
|
2018-04-25 20:49:49 +02:00
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```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
|
|
|
|
|
2018-05-07 20:03:56 +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
|
2018-09-12 21:57:54 +02:00
|
|
|
|
and line numbers but no grid and no file header. Use the `BAT_STYLE` environment
|
|
|
|
|
variable to make these changes permanent.
|
2018-05-30 21:32:40 +02:00
|
|
|
|
|
2018-08-19 10:49:09 +02:00
|
|
|
|
### 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)
|
2018-08-19 10:49:09 +02:00
|
|
|
|
and theme. To add new syntax definitions, do the following.
|
2018-04-30 16:03:33 +02:00
|
|
|
|
|
2018-08-19 10:49:09 +02:00
|
|
|
|
Create a folder with syntax definition files:
|
2018-05-02 22:21:56 +02:00
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```bash
|
2018-05-08 19:48:10 +02:00
|
|
|
|
BAT_CONFIG_DIR="$(bat cache --config-dir)"
|
|
|
|
|
|
2018-05-16 21:22:16 +02:00
|
|
|
|
mkdir -p "$BAT_CONFIG_DIR/syntaxes"
|
|
|
|
|
cd "$BAT_CONFIG_DIR/syntaxes"
|
2018-04-30 16:03:33 +02:00
|
|
|
|
|
2018-08-19 10:49:09 +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
|
|
|
|
```
|
|
|
|
|
|
2018-08-19 10:49:09 +02:00
|
|
|
|
Now use the following command to parse these files into a binary cache:
|
2018-05-02 22:21:56 +02:00
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```bash
|
2018-05-08 19:48:10 +02:00
|
|
|
|
bat cache --init
|
|
|
|
|
```
|
|
|
|
|
|
2018-08-19 10:49:09 +02:00
|
|
|
|
Finally, use `bat --list-languages` to check if the new languages are available.
|
2018-05-30 20:40:02 +02:00
|
|
|
|
|
2018-05-08 19:48:10 +02:00
|
|
|
|
If you ever want to go back to the default settings, call:
|
|
|
|
|
|
2018-05-30 20:40:02 +02:00
|
|
|
|
```bash
|
2018-05-08 19:48:10 +02:00
|
|
|
|
bat cache --clear
|
2018-04-30 16:03:33 +02:00
|
|
|
|
```
|
2018-05-21 00:28:30 +02:00
|
|
|
|
|
2018-08-19 10:49:09 +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
|
|
|
|
|
|
|
|
|
|
# Update the binary cache
|
|
|
|
|
bat cache --init
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Finally, use `bat --list-themes` to check if the new themes are available.
|
|
|
|
|
|
2018-08-18 20:22:11 +02:00
|
|
|
|
### 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 "$@"
|
|
|
|
|
```
|
|
|
|
|
|
2018-09-08 10:31:33 +02:00
|
|
|
|
## Using `bat` on Windows
|
|
|
|
|
|
|
|
|
|
`bat` mostly works out-of-the-box on Windows, but a few features may need extra configuration.
|
|
|
|
|
|
|
|
|
|
### Paging
|
|
|
|
|
|
|
|
|
|
Windows only includes a very limited pager in the form of `more`. You can download a Windows binary
|
|
|
|
|
for `less` [from its homepage](http://www.greenwoodsoftware.com/less/download.html) or [through
|
|
|
|
|
Chocolatey](https://chocolatey.org/packages/Less). To use it, place the binary in a directory in
|
|
|
|
|
your `PATH` or [define an environment variable](#using-a-different-pager).
|
|
|
|
|
|
|
|
|
|
### Colours
|
|
|
|
|
|
|
|
|
|
Windows 10 natively supports colours in both `conhost.exe` (Command Prompt) and PowerShell since
|
|
|
|
|
[v1511](https://en.wikipedia.org/wiki/Windows_10_version_history#Version_1511_(November_Update)), as
|
|
|
|
|
well as in newer versions of bash. On earlier versions of Windows, you can use
|
|
|
|
|
[Cmder](http://cmder.net/), which includes [ConEmu](https://conemu.github.io/).
|
|
|
|
|
|
|
|
|
|
**Note:** The Git and MSYS versions of `less` do not correctly interpret colours on Windows. If you
|
|
|
|
|
don’t have any other pagers installed, you can disable paging entirely by passing `--paging=never`
|
|
|
|
|
or by setting `BAT_PAGER` to an empty string.
|
|
|
|
|
|
2018-08-28 22:08:34 +02:00
|
|
|
|
## 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).
|
|
|
|
|
|
2018-09-03 22:12:41 +02:00
|
|
|
|
### Line numbers and grid are hardly visible
|
|
|
|
|
|
|
|
|
|
Please try a different theme (see `bat --list-themes` for a list). The `OneHalfDark` and
|
|
|
|
|
`OneHalfLight` themes provide grid and line colors that are brighter.
|
|
|
|
|
|
2018-09-05 21:13:43 +02:00
|
|
|
|
### Error when compiling: "cannot find -lz"
|
|
|
|
|
|
|
|
|
|
Please install the `zlib-devel` package and try again.
|
|
|
|
|
|
2018-08-28 21:03:03 +02:00
|
|
|
|
## 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
|
|
|
|
|
```
|
|
|
|
|
|
2018-05-21 00:28:30 +02:00
|
|
|
|
## 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.
|