A cat(1) clone with syntax highlighting and Git integration.

Key Features • How To Use • Installation • Customization • Project goals, alternatives

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

From binaries

Check out the Release page for binary builds and Debian packages.

On Arch Linux

You can install via Pacman:

bash pacman -S bat

On FreeBSD

You can install a precompiled bat package 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:

bash brew install bat

From source

If you want to build to compile 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 bats 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 library for syntax highlighting. syntect can read any Sublime Text .sublime-syntax file and theme. To add new syntax definitions, do the following.

Create a folder with syntax definition files:

```bash BATCONFIGDIR="$(bat cache --config-dir)"

mkdir -p "$BATCONFIGDIR/syntaxes" cd "$BATCONFIGDIR/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 BATCONFIGDIR="$(bat cache --config-dir)"

mkdir -p "$BATCONFIGDIR/themes" cd "$BATCONFIGDIR/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 for a comparison.