bat

by sharkdp

sharkdp /bat

A cat(1) clone with wings.

22.8K Stars 498 Forks Last release: 4 months ago (v0.15.4) Other 1.4K Commits 26 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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

Show non-printable characters

You can use the

-A
/
--show-all
option to show and highlight non-printable characters:

Non-printable character example

Automatic paging

bat
can pipe its own output to a pager (e.g
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 (i.e. when you pipe into another process or into a file),
bat
will act as a drop-in replacement for
cat
and 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, determine the syntax automatically (note, highlighting will only work if the syntax can be determined from the first line of the file, usually through a shebang such as

#!/bin/sh
)
> curl -s https://sh.rustup.rs | bat

Read from stdin, specify the language explicitly

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

Show and highlight non-printable characters: ```bash

bat -A /etc/hosts ```

Use it as a

cat
replacement:
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'.

Integration with other tools

find
or
fd

You can use the

-exec
option of
find
to preview all search results with
bat
:
bash
find … -exec bat {} +

If you happen to use

fd
, you can use the

-X
/
--exec-batch
option to do the same:
bash
fd … -X bat

ripgrep

With

batgrep
,

bat
can be used as the printer for
ripgrep
search results.
batgrep needle src/

tail -f

bat
can be combined with
tail -f
to continuously monitor a given file with syntax highlighting.
bash
tail -f /var/log/pacman.log | bat --paging=never -l log
Note that we have to switch off paging in order for this to work. We have also specified the syntax explicitly (
-l log
), as it can not be auto-detected in this case.

git

You can combine

bat
with
git show
to view an older version of a given file with proper syntax highlighting:
bash
git show v0.6.0:src/main.rs | bat -l rs

Note that syntax highlighting within diffs is currently not supported. If you are looking for this, check out

delta
.

xclip

The line numbers and Git modification markers in the output of

bat
can make it hard to copy the contents of a file. To prevent this, you can call
bat
with the
-p
/
--plain
option or simply pipe the output into
xclip
:
bash
bat main.cpp | xclip
bat
will detect that the output is being redirected and print the plain file contents.

man

bat
can be used as a colorizing pager for
man
, by setting the
MANPAGER
environment variable:
export MANPAGER="sh -c 'col -bx | bat -l man -p'"
man 2 select

It might also be necessary to set

MANROFFOPT="-c"
if you experience formatting problems.

If you prefer to have this bundled in a new command, you can also use

batman
.

Note that the Manpage syntax is developed in this repository and still needs some work.

prettier
/
shfmt
/
rustfmt

The

prettybat
script is a wrapper that will format code and print it with

bat
.

Installation

Packaging status

On Ubuntu (using
apt
)

... and other Debian-based Linux distributions.

bat
is making its way through the Ubuntu and Debian package release process, and is available for Ubuntu as of Eoan 19.10. On Debian
bat
is currently only available on the unstable "Sid" branch.

If your Ubuntu/Debian installation is new enough you can simply run:

apt install bat

If you install

bat
this way, please note that the executable may be installed as
batcat
instead of
bat
(due to a name clash with another package). You can set up a
bat -> batcat
symlink or alias to prevent any issues that may come up because of this and to be consistent with other distributions:
bash
mkdir -p ~/.local/bin
ln -s /usr/bin/batcat ~/.local/bin/bat

On Ubuntu (using most recent
.deb
packages)

... and other Debian-based Linux distributions.

If the package has not yet been promoted to your Ubuntu/Debian installation, or you want the most recent release of

bat
, download the latest
.deb
package from the release page and install it via:
sudo dpkg -i bat_0.15.4_amd64.deb  # adapt version number and architecture

On Alpine Linux

You can install the

bat
package from the official sources, provided you have the appropriate repository enabled:

apk add bat

On Arch Linux

You can install the

bat
package from the official sources:

pacman -S bat

On Fedora

You can install the

bat
package from the official Fedora Modular repository.

dnf install bat

On Gentoo Linux

You can install the

bat
package from the official sources:

emerge sys-apps/bat

On Void Linux

You can install

bat
via xbps-install:
bash
xbps-install -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

Via nix

You can install

bat
using the nix package manager:
nix-env -i bat

On openSUSE

You can install

bat
with zypper:
zypper install bat

On macOS

You can install

bat
with Homebrew:
brew install bat

Or install

bat
with MacPorts:
port install bat

On Windows

There are a few options to install

bat
on Windows. Once you have installed
bat
, take a look at the "Using
bat
on Windows"
section.

Prerequisites

You will need to install the Visual C++ Redistributable package.

With Chocolatey

You can install

bat
via Chocolatey:
bash
choco install bat

With Scoop

You can install

bat
via scoop:
bash
scoop install bat

From prebuilt binaries:

You can download prebuilt binaries from the Release page,

You will need to install the Visual C++ Redistributable package.

From binaries

Check out the Release page for prebuilt versions of

bat
for many different architectures. Statically-linked binaries are also available: look for archives with
musl
in the file name.

From source

If you want to build

bat
from source, you need Rust 1.40 or higher. You can then use
cargo
to build everything:
cargo install --locked bat

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 shell's startup file to make the change permanent. Alternatively, use
bat
s configuration file.

If you want to preview the different themes on a custom file, you can use the following command (you need

fzf
for this):

bash
bat --list-themes | fzf --preview="bat --theme={} --color=always /path/to/file"

bat
looks good on a dark background by default. However, if your terminal uses a light background, some themes like
GitHub
or
OneHalfLight
will work better for you. You can also use a custom theme by following the 'Adding new themes' section below.

8-bit themes

bat
has four themes that always use 8-bit colors, even when truecolor support is available:
  • ansi-dark
    looks decent on any terminal with a dark background. It uses 3-bit colors: black, red, green, yellow, blue, magenta, cyan, and white.
  • ansi-light
    is like
    ansi-dark
    , but for terminals with a light background.
  • base16
    is designed for base16 terminal themes. It uses 4-bit colors (3-bit colors plus bright variants) in accordance with the base16 styling guidelines.
  • base16-256
    is designed for base16-shell. It replaces certain bright colors with 8-bit colors from 16 to 21. Do not use this simply because you have a 256-color terminal but are not using base16-shell.

Although these themes are more restricted, they have two advantages over truecolor themes:

  • They harmonize better with other terminal software using 3-bit or 4-bit colors.
  • When you change your terminal theme,
    bat
    output already on the screen will update to match.

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. Set the
BAT_STYLE
environment variable to make these changes permanent or use
bat
s configuration file.

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:

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 --build

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: ```bash 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 --build ```

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 can also set them via the

PAGER
/
BAT_PAGER
variables:
export BAT_PAGER="less -RF"

Instead of using environment variables, you can also use

bat
s configuration file to configure the pager (
--pager
option).

Note: By default, if the pager is set to

less
(and no command-line options are specified),
bat
will pass the following command line options to the pager:
-R
/
--RAW-CONTROL-CHARS
,
-F
/
--quit-if-one-screen
and
-X
/
--no-init
. The last option (
-X
) is only used for
less
versions older than 530.

The

-R
option is needed to interpret ANSI colors correctly. The second option (
-F
) instructs less to exit immediately if the output size is smaller than the vertical size of the terminal. This is convenient for small files because you do not have to press
q
to quit the pager. The third option (
-X
) is needed to fix a bug with the
--quit-if-one-screen
feature in old versions of
less
. Unfortunately, it also breaks mouse-wheel support in
less
.

If you want to enable mouse-wheel scrolling on older versions of

less
, you can pass just
-R
(as in the example above, this will disable the quit-if-one-screen feature). For less 530 or newer, it should work out of the box.

Indentation

bat
expands tabs to 4 spaces by itself, not relying on the pager. To change this, simply add the
--tabs
argument with the number of spaces you want to be displayed.

Note: Defining tab stops for the pager (via the

--pager
argument by
bat
, or via the
LESS
environment variable for
less
) won't be taken into account because the pager will already get expanded spaces instead of tabs. This behaviour is added to avoid indentation issues caused by the sidebar. Calling
bat
with
--tabs=0
will override it and let tabs be consumed by the pager.

Dark mode

If you make use of the dark mode feature in macOS, you might want to configure

bat
to use a different theme based on the OS theme. The following snippet uses the
default
theme when in the dark mode and the
GitHub
theme when in the light mode.
alias cat="bat --theme=\$(defaults read -globalDomain AppleInterfaceStyle &> /dev/null && echo default || echo GitHub)"

Configuration file

bat
can also be customized with a configuration file. The location of the file is dependent on your operating system. To get the default path for your system, call
bat --config-file

Alternatively, you can use the

BAT_CONFIG_PATH
environment variable to point
bat
to a non-default location of the configuration file:
bash
export BAT_CONFIG_PATH="/path/to/bat.conf"

A default configuration file can be created with the

--generate-config-file
option.
bash
bat --generate-config-file

Format

The configuration file is a simple list of command line arguments. Use

bat --help
to see a full list of possible options and values. In addition, you can add comments by prepending a line with the
#
character.

Example configuration file: ```bash

Set the theme to "TwoDark"

--theme="TwoDark"

Show line numbers, Git modifications and file header (but no grid)

--style="numbers,changes,header"

Use italic text on the terminal (not supported on all terminals)

--italic-text=always

Use C++ syntax for .ino files

--map-syntax "*.ino:C++"

Use ".gitignore"-style highlighting for ".ignore" files

--map-syntax ".ignore:Git Ignore" ```

Using
bat
on Windows

bat
mostly works out-of-the-box on Windows, but a few features may need extra configuration.

Prerequisites

You will need to install the Visual C++ Redistributable package.

Paging

Windows only includes a very limited pager in the form of

more
. You can download a Windows binary for
less
from its homepage or through Chocolatey. To use it, place the binary in a directory in your
PATH
or define an environment variable. The Chocolatey package installs
less
automatically.

Colors

Windows 10 natively supports colors in both

conhost.exe
(Command Prompt) and PowerShell since v1511, as well as in newer versions of bash. On earlier versions of Windows, you can use Cmder, which includes ConEmu.

Note: The Git and MSYS versions of

less
do not correctly interpret colors 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.

Cygwin

bat
on Windows does not natively support Cygwin's unix-style paths (
/cygdrive/*
). When passed an absolute cygwin path as an argument,
bat
will encounter the following error:
The system cannot find the path specified. (os error 3)

This can be solved by creating a wrapper or adding the following function to your

.bash_profile
file:
bat() {
    local index
    local args=("[email protected]")
    for index in $(seq 0 ${#args[@]}) ; do
        case "${args[index]}" in
        -*) continue;;
        *)  [ -e "${args[index]}" ] && args[index]="$(cygpath --windows "${args[index]}")";;
        esac
    done
    command bat "${args[@]}"
}

Troubleshooting

Terminals & colors

bat
handles terminals with and without truecolor support. However, the colors in most syntax highlighting themes are not optimized for 8-bit colors. It is therefore strongly recommended that you use a terminal with 24-bit truecolor support (
terminator
,
konsole
,
iTerm2
, ...), or use one of the basic 8-bit themes designed for a restricted set of colors. See this article 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).

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.

File encodings

bat
natively supports UTF-8 as well as UTF-16. For every other file encoding, you may need to convert to UTF-8 first because the encodings can typically not be auto-detected. You can
iconv
to do so. Example: if you have a PHP file in Latin-1 (ISO-8859-1) encoding, you can call:
bash
iconv -f ISO-8859-1 -t UTF-8 my-file.php | bat
Note: you might have to use the
-l
/
--language
option if the syntax can not be auto-detected by
bat
.

Development

# Recursive clone to retrieve all submodules
git clone --recursive https://github.com/sharkdp/bat

Build (debug version)

cd bat cargo build --bins

Run unit tests and integration tests

cargo test

Install (release version)

cargo install --locked

Build a bat binary with modified syntaxes and themes

bash assets/create.sh cargo install --locked --force

Maintainers

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.

License

Copyright (c) 2018-2020 bat-developers.

bat
is made available under the terms of either the MIT License or the Apache License 2.0, at your option.

See the LICENSE-APACHE and LICENSE-MIT files for license details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.