bat/README.md

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 😉. 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

> bat README.md

Display multiple files at once

> bat src/*.rs

Read from stdin, explicitly specify the language

> yaml2json .travis.yml | json_pp | bat -l json

> curl -s https://raw.githubusercontent.com/sharkdp/bat/master/src/main.rs | bat -l rs

As a replacement for cat:

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:

pacman -S bat

On FreeBSD

You can install a precompiled bat package with pkg:

pkg install bat

or build it on your own from the FreeBSD ports:

cd /usr/ports/textproc/bat
make install

On macOS

You can install bat with Homebrew:

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:

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:

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:

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:

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:

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:

#!/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.