README.md · bat · git.iko.soy

git.iko.soy/bat

on 3446fdf help sign in

bat/README.md

381 lines 12 kB history raw

1<p align="center">

2 <img src="doc/logo-header.svg" alt="bat - a cat clone with wings"><br>

3 <a href="https://travis-ci.org/sharkdp/bat"><img src="https://travis-ci.org/sharkdp/bat.svg?branch=master" alt="Build Status"></a>

4 <a href="https://ci.appveyor.com/project/sharkdp/bat"><img src="https://ci.appveyor.com/api/projects/status/cptsmtbiwbnr2vhf?svg=true"></a>

5 <img src="https://img.shields.io/crates/l/bat.svg" alt="license">

6 <a href="https://crates.io/crates/bat"><img src="https://img.shields.io/crates/v/bat.svg?colorB=319e8c" alt="Version info"></a><br>

7 A <i>cat(1)</i> clone with syntax highlighting and Git integration.

8</p>

10<p align="center">

11 <a href="#syntax-highlighting">Key Features</a> •

12 <a href="#how-to-use">How To Use</a> •

13 <a href="#installation">Installation</a> •

14 <a href="#customization">Customization</a> •

15 <a href="#project-goals-and-alternatives">Project goals, alternatives</a>

16</p>

18### Syntax highlighting

20`bat` supports syntax highlighting for a large number of programming and markup

21languages:

23![Syntax highlighting example](https://imgur.com/rGsdnDe.png)

25### Git integration

27`bat` communicates with `git` to show modifications with respect to the index

28(see left side bar):

30![Git integration example](https://i.imgur.com/2lSW4RE.png)

32### Automatic paging

34`bat` can pipe its own output to `less` if the output is too large for one screen.

36### File concatenation

38Oh.. you can also use it to concatenate files :wink:. Whenever

39`bat` detects a non-interactive terminal, it will fall back to printing

40the plain file contents.

42## How to use

44Display a single file on the terminal

46```bash

47> bat README.md

48```

50Display multiple files at once

52```bash

53> bat src/*.rs

54```

56Read from stdin, explicitly specify the language

58```bash

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

60```

62```bash

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

64```

66As a replacement for `cat`:

68```bash

69bat > note.md # quickly create a new file

71bat header.md content.md footer.md > document.md

73bat -n main.rs # show line numbers (only)

75bat f - g # output 'f', then stdin, then 'g'.

76```

78## Installation

80### On Ubuntu

81*... and other Debian-based Linux distributions.*

83Download the latest `.deb` package from the [release page](https://github.com/sharkdp/bat/releases)

84and install it via:

85``` bash

86sudo dpkg -i bat_0.7.1_amd64.deb # adapt version number and architecture

87```

89### On Arch Linux

91You can install [the `bat` package](https://www.archlinux.org/packages/community/x86_64/bat/)

92from the official sources:

94```bash

95pacman -S bat

96```

98### On Void Linux

100You can install `bat` via xbps-install:

101```

102xbps-install -S bat

103```

105### On FreeBSD

107You can install a precompiled [`bat` package](https://www.freshports.org/textproc/bat) with pkg:

109```bash

110pkg install bat

111```

113or build it on your own from the FreeBSD ports:

115```bash

116cd /usr/ports/textproc/bat

117make install

118```

120### Via Ansible

122You can install `bat` with [Ansible](https://www.ansible.com/):

124```bash

125# Install role on local machine

126ansible-galaxy install aeimer.install_bat

127```

129```yaml

130---

131# Playbook to install bat

132- host: all

133 roles:

134 - aeimer.install_bat

135```

137- [Ansible Galaxy](https://galaxy.ansible.com/aeimer/install_bat)

138- [GitHub](https://github.com/aeimer/ansible-install-bat)

140This should work with the following distributions:

141- Debian/Ubuntu

142- ARM (eg. Raspberry PI)

143- Arch Linux

144- Void Linux

145- FreeBSD

146- MacOS

148### On macOS

150You can install `bat` with [Homebrew](http://braumeister.org/formula/bat):

152```bash

153brew install bat

154```

156### On Windows

158You can download prebuilt binaries from the [Release page](https://github.com/sharkdp/bat/releases),

159or install it with [scoop](https://scoop.sh/):

161```bash

162scoop install bat

163```

165[See below](#using-bat-on-windows) for notes.

167### From binaries

169Check out the [Release page](https://github.com/sharkdp/bat/releases) for

170prebuilt versions of `bat` for many different architectures.

172### From source

174If you want to build `bat` from source, you need Rust 1.26 or

175higher. You can then use `cargo` to build everything:

177```bash

178cargo install bat

179```

181You may have to install `cmake` and the `libz` development package

182(`libz-dev` or `libz-devel`) in order for the build to succeed.

184## Customization

186### Highlighting theme

188Use `bat --list-themes` to get a list of all available themes for syntax

189highlighting. To select the `TwoDark` theme, call `bat` with the

190`--theme=TwoDark` option or set the `BAT_THEME` environment variable to

191`TwoDark`. Use `export BAT_THEME="TwoDark"` in your shell's startup file to

192make the change permanent.

193Want to rapidly preview the themes on a file that matters to you? Have

194[`fzf`](https://github.com/junegunn/fzf) installed? Try this:

195`bat --list-themes|fzf --preview='bat --theme={} --color=always /path/to/file'`

197### Output style

199You can use the `--style` option to control the appearance of `bat`s output.

200You can use `--style=numbers,changes`, for example, to show only Git changes

201and line numbers but no grid and no file header. Use the `BAT_STYLE` environment

202variable to make these changes permanent.

204### Adding new syntaxes / language definitions

206`bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)

207library for syntax highlighting. `syntect` can read any

208[Sublime Text `.sublime-syntax` file](https://www.sublimetext.com/docs/3/syntax.html)

209and theme. To add new syntax definitions, do the following.

211Create a folder with syntax definition files:

213```bash

214BAT_CONFIG_DIR="$(bat cache --config-dir)"

216mkdir -p "$BAT_CONFIG_DIR/syntaxes"

217cd "$BAT_CONFIG_DIR/syntaxes"

219# Put new '.sublime-syntax' language definition files

220# in this folder (or its subdirectories), for example:

221git clone https://github.com/tellnobody1/sublime-purescript-syntax

222```

224Now use the following command to parse these files into a binary cache:

226```bash

227bat cache --init

228```

230Finally, use `bat --list-languages` to check if the new languages are available.

232If you ever want to go back to the default settings, call:

234```bash

235bat cache --clear

236```

238### Adding new themes

240This works very similar to how we add new syntax definitions.

242First, create a folder with the new syntax highlighting themes:

243```bash

244BAT_CONFIG_DIR="$(bat cache --config-dir)"

246mkdir -p "$BAT_CONFIG_DIR/themes"

247cd "$BAT_CONFIG_DIR/themes"

249# Download a theme in '.tmTheme' format, for example:

250git clone https://github.com/greggb/sublime-snazzy

252# Update the binary cache

253bat cache --init

254```

256Finally, use `bat --list-themes` to check if the new themes are available.

258### Using a different pager

260`bat` uses the pager that is specified in the `PAGER` environment variable. If this variable is not

261set, `less` is used by default. If you want to use a different pager, you can either modify the

262`PAGER` variable or set the `BAT_PAGER` environment variable to override what is specified in

263`PAGER`.

265If you want to pass command-line arguments to the pager, you need to create a small shell

266script as a wrapper, for example

268```bash

269#!/bin/bash

271less --tabs 4 -R "$@"

272```

273(put this in a file `~/.bat-pager.sh`, make it executable `chmod +x ~/.bat-pager.sh` and use

274`export BAT_PAGER="$HOME/.bat-pager.sh"` in your shells `rc` file)

276**Note**: By default, if the pager is set to `less`, `bat` will pass the following command line

277options to the pager: `-R`/`--RAW-CONTROL-CHARS`, `-F`/`--quit-if-one-screen` and `-X`/`--no-init`.

278The first (`-R`) is needed to interpret ANSI colors correctly. The second option (`-F`) instructs

279less to exit immediately if the output size is smaller than the vertical size of the terminal.

280This is convenient for small files because you do not have to press `q` to quit the pager. The

281third option (`-X`) is needed to fix a bug with the `--quit-if-one-screen` feature in old versions

282of `less`. Unfortunately, it also breaks mouse-wheel support in `less`. If you want to enable

283mouse-wheel scrolling, you can either pass just `-R` (as in the example above, this will disable

284the quit-if-one-screen feature), or you can use a recent version of `less` and pass `-RF` which

285will hopefully enable both quit-if-one-screen and mouse-wheel scrolling.

287If scrolling still doesn't work for you, you can try to pass the `-S` option in addition.

289## Using `bat` on Windows

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

293### Paging

295Windows only includes a very limited pager in the form of `more`. You can download a Windows binary

296for `less` [from its homepage](http://www.greenwoodsoftware.com/less/download.html) or [through

297Chocolatey](https://chocolatey.org/packages/Less). To use it, place the binary in a directory in

298your `PATH` or [define an environment variable](#using-a-different-pager).

300### Colours

302Windows 10 natively supports colours in both `conhost.exe` (Command Prompt) and PowerShell since

303[v1511](https://en.wikipedia.org/wiki/Windows_10_version_history#Version_1511_(November_Update)), as

304well as in newer versions of bash. On earlier versions of Windows, you can use

305[Cmder](http://cmder.net/), which includes [ConEmu](https://conemu.github.io/).

307**Note:** The Git and MSYS versions of `less` do not correctly interpret colours on Windows. If you

308don’t have any other pagers installed, you can disable paging entirely by passing `--paging=never`

309or by setting `BAT_PAGER` to an empty string.

311### Cygwin

313`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)`

315This can be solved by creating a wrapper or adding the following function to your `.bash_profile` file:

317```shell

318bat() {

319 local index

320 local args=("$@")

321 for index in $(seq 0 ${#args[@]}) ; do

322 case "${args[index]}" in

323 -*) continue;;

324 *) [ -e "${args[index]}" ] && args[index]="$(cygpath --windows "${args[index]}")";;

325 esac

326 done

327 command bat "${args[@]}"

329```

331## Troubleshooting

333### Terminals & colors

335`bat` handles terminals *with* and *without* truecolor support. However, the colors in the syntax

336highlighting themes are not optimized for 8-bit colors and it is therefore strongly recommended

337that you use a terminal with 24-bit truecolor support (`terminator`, `konsole`, `iTerm2`, ...).

338See [this article](https://gist.github.com/XVilka/8346728) for more details and a full list of

339terminals with truecolor support.

341Make sure that your truecolor terminal sets the `COLORTERM` variable to either `truecolor` or

342`24bit`. Otherwise, `bat` will not be able to determine whether or not 24-bit escape sequences

343are supported (and fall back to 8-bit colors).

345### Line numbers and grid are hardly visible

347Please try a different theme (see `bat --list-themes` for a list). The `OneHalfDark` and

348`OneHalfLight` themes provide grid and line colors that are brighter.

350## Development

352```bash

353# Recursive clone to retrieve all submodules

354git clone --recursive https://github.com/sharkdp/bat

356# Build (debug version)

357cd bat

358cargo build

360# Run unit tests and integration tests

361cargo test

363# Install (release version)

364cargo install

366# Build a bat binary with modified syntaxes and themes

367bash assets/create.sh

368cargo install -f

369```

371## Project goals and alternatives

373`bat` tries to achieve the following goals:

375- Provide beautiful, advanced syntax highlighting

376- Integrate with Git to show file modifications

377- Be a drop-in replacement for (POSIX) `cat`

378- Offer a user-friendly command-line interface

380There are a lot of alternatives, if you are looking for similar programs. See

381[this document](doc/alternatives.md) for a comparison.