A cat(1) clone with syntax highlighting and Git integration.
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 ### On Ubuntu *... and other Debian-based Linux distributions.* Download the latest `.deb` package from the [release page](https://github.com/sharkdp/bat/releases) and install it via: ``` bash sudo dpkg -i bat_0.6.1_amd64.deb # adapt version number and architecture ``` ### On Arch Linux You can install [the `bat` package](https://www.archlinux.org/packages/community/x86_64/bat/) from the official sources: ```bash pacman -S bat ``` ### On Void Linux You can install `bat` via xbps-install: ``` xbps-install -S bat ``` ### On FreeBSD You can install a precompiled [`bat` package](https://www.freshports.org/textproc/bat) 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](http://braumeister.org/formula/bat): ```bash brew install bat ``` ### On Windows You can download pre-built binaries from the [Release page](https://github.com/sharkdp/bat/releases), or install it with [scoop](https://scoop.sh/): ```bash scoop install bat ``` [See below](#using-bat-on-windows) for notes. ### From binaries Check out the [Release page](https://github.com/sharkdp/bat/releases) for prebuilt versions of `bat` for many different architectures. ### From source If you want to build `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 `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. ### Adding new syntaxes / language definitions `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) and theme. To add new syntax definitions, do the following. Create a folder with syntax definition files: ```bash 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: ```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 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: ```bash #!/bin/bash less --tabs 4 -RF "$@" ``` ## 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. ## 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). ### 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. ### Error when compiling: "cannot find -lz" Please install the `zlib-devel` package and try again. ## 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 ``` ## 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.