README.md · bat · git.iko.soy

git.iko.soy/bat

on cea05e9 help sign in

bat/README.md

397 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, determine the syntax automatically

58```bash

59> curl -s https://sh.rustup.rs | bat

60```

62Read from stdin, specify the language explicitly

64```bash

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

66```

69As a replacement for `cat`:

71```bash

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

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

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

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

79```

81## Installation

83### On Ubuntu

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

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

87and install it via:

88``` bash

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

90```

92### On Arch Linux

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

95from the official sources:

97```bash

98pacman -S bat

99```

101### On Void Linux

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

104```

105xbps-install -S bat

106```

108### On FreeBSD

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

112```bash

113pkg install bat

114```

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

118```bash

119cd /usr/ports/textproc/bat

120make install

121```

123### Via Ansible

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

127```bash

128# Install role on local machine

129ansible-galaxy install aeimer.install_bat

130```

132```yaml

133---

134# Playbook to install bat

135- host: all

136 roles:

137 - aeimer.install_bat

138```

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

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

143This should work with the following distributions:

144- Debian/Ubuntu

145- ARM (eg. Raspberry PI)

146- Arch Linux

147- Void Linux

148- FreeBSD

149- MacOS

151### Via nix

153You can install `bat` using the [nix package manager](https://nixos.org/nix):

155```bash

156nix-env -i bat

157```

159### On macOS

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

163```bash

164brew install bat

165```

167### On Windows

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

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

172```bash

173scoop install bat

174```

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

178### From binaries

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

181prebuilt versions of `bat` for many different architectures. Statically-linked

182binaries are available, just look for releases with `musl` in the name on the

183releases page.

185### From source

187If you want to build `bat` from source, you need Rust 1.27 or

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

190```bash

191cargo install bat

192```

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

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

197## Customization

199### Highlighting theme

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

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

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

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

205make the change permanent.

207If you want to preview the different themes on a custom file, you can use

208the following command (you need [`fzf`](https://github.com/junegunn/fzf) for this):

209``` bash

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

211```

213### Output style

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

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

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

218variable to make these changes permanent.

220### Adding new syntaxes / language definitions

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

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

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

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

227Create a folder with syntax definition files:

229```bash

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

232mkdir -p "$BAT_CONFIG_DIR/syntaxes"

233cd "$BAT_CONFIG_DIR/syntaxes"

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

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

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

238```

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

242```bash

243bat cache --init

244```

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

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

250```bash

251bat cache --clear

252```

254### Adding new themes

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

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

259```bash

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

262mkdir -p "$BAT_CONFIG_DIR/themes"

263cd "$BAT_CONFIG_DIR/themes"

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

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

268# Update the binary cache

269bat cache --init

270```

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

274### Using a different pager

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

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

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

279`PAGER`.

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

282script as a wrapper, for example

284```bash

285#!/bin/bash

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

288```

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

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

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

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

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

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

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

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

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

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

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

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

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

305## Using `bat` on Windows

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

309### Paging

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

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

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

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

316### Colours

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

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

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

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

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

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

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

327### Cygwin

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

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

333```shell

334bat() {

335 local index

336 local args=("$@")

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

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

339 -*) continue;;

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

341 esac

342 done

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

345```

347## Troubleshooting

349### Terminals & colors

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

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

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

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

355terminals with truecolor support.

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

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

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

361### Line numbers and grid are hardly visible

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

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

366## Development

368```bash

369# Recursive clone to retrieve all submodules

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

372# Build (debug version)

373cd bat

374cargo build

376# Run unit tests and integration tests

377cargo test

379# Install (release version)

380cargo install

382# Build a bat binary with modified syntaxes and themes

383bash assets/create.sh

384cargo install -f

385```

387## Project goals and alternatives

389`bat` tries to achieve the following goals:

391- Provide beautiful, advanced syntax highlighting

392- Integrate with Git to show file modifications

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

394- Offer a user-friendly command-line interface

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

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