A cat(1) clone with wings.
Go to file
2018-08-28 20:24:13 +02:00
assets Small style changes to --list-themes 2018-08-28 20:24:13 +02:00
ci Add man page to releases 2018-08-27 23:10:14 +02:00
doc Add initial version of man page, see #52 2018-08-27 22:57:47 +02:00
src Run cargo fmt 2018-08-28 20:24:13 +02:00
tests Add simple loop-through mode 2018-08-23 23:13:24 +02:00
.gitignore Remove user specific change 2018-05-06 11:22:48 +02:00
.gitmodules Add syntaxes for Elm, Kotlin, Puppet, TypeScript 2018-08-28 19:36:31 +02:00
.travis.yml Add arm as a compile target 2018-08-19 09:50:24 +02:00
Cargo.lock Bump version 2018-08-19 12:31:35 +02:00
Cargo.toml Update the --help text 2018-08-22 19:27:11 +02:00
LICENSE-APACHE Add license 2018-04-22 15:34:14 +02:00
LICENSE-MIT Add license 2018-04-22 15:34:14 +02:00
README.md Load customized themes in addition to defaults 2018-08-20 21:39:21 +02:00

bat - a cat clone with wings
Build Status license Version info
A cat(1) clone with syntax highlighting and Git integration.

Key FeaturesHow To UseInstallationCustomizationProject goals, alternatives

Syntax highlighting

bat supports syntax highlighting for a large number of programming and markup languages:

Syntax highlighting example

Git integration

bat communicates with git to show modifications with respect to the index (see left side bar):

Git integration example

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

# 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:

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