README.md · bat · git.iko.soy

git.iko.soy/bat

on f9fd5e4 help sign in

bat/README.md

386 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. Statically-linked

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

172releases page.

174### From source

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

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

179```bash

180cargo install bat

181```

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

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

186## Customization

188### Highlighting theme

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

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

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

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

194make the change permanent.

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

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

198``` bash

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

200```

202### Output style

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

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

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

207variable to make these changes permanent.

209### Adding new syntaxes / language definitions

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

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

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

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

216Create a folder with syntax definition files:

218```bash

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

221mkdir -p "$BAT_CONFIG_DIR/syntaxes"

222cd "$BAT_CONFIG_DIR/syntaxes"

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

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

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

227```

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

231```bash

232bat cache --init

233```

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

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

239```bash

240bat cache --clear

241```

243### Adding new themes

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

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

248```bash

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

251mkdir -p "$BAT_CONFIG_DIR/themes"

252cd "$BAT_CONFIG_DIR/themes"

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

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

257# Update the binary cache

258bat cache --init

259```

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

263### Using a different pager

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

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

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

268`PAGER`.

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

271script as a wrapper, for example

273```bash

274#!/bin/bash

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

277```

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

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

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

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

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

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

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

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

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

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

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

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

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

294## Using `bat` on Windows

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

298### Paging

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

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

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

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

305### Colours

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

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

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

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

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

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

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

316### Cygwin

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

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

322```shell

323bat() {

324 local index

325 local args=("$@")

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

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

328 -*) continue;;

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

330 esac

331 done

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

334```

336## Troubleshooting

338### Terminals & colors

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

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

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

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

344terminals with truecolor support.

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

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

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

350### Line numbers and grid are hardly visible

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

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

355## Development

357```bash

358# Recursive clone to retrieve all submodules

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

361# Build (debug version)

362cd bat

363cargo build

365# Run unit tests and integration tests

366cargo test

368# Install (release version)

369cargo install

371# Build a bat binary with modified syntaxes and themes

372bash assets/create.sh

373cargo install -f

374```

376## Project goals and alternatives

378`bat` tries to achieve the following goals:

380- Provide beautiful, advanced syntax highlighting

381- Integrate with Git to show file modifications

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

383- Offer a user-friendly command-line interface

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

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