README.md · bat · git.iko.soy

git.iko.soy/bat

on f140f6d help sign in

bat/README.md

383 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.

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

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

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

199### Output style

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

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

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

204variable to make these changes permanent.

206### Adding new syntaxes / language definitions

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

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

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

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

213Create a folder with syntax definition files:

215```bash

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

218mkdir -p "$BAT_CONFIG_DIR/syntaxes"

219cd "$BAT_CONFIG_DIR/syntaxes"

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

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

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

224```

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

228```bash

229bat cache --init

230```

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

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

236```bash

237bat cache --clear

238```

240### Adding new themes

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

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

245```bash

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

248mkdir -p "$BAT_CONFIG_DIR/themes"

249cd "$BAT_CONFIG_DIR/themes"

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

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

254# Update the binary cache

255bat cache --init

256```

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

260### Using a different pager

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

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

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

265`PAGER`.

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

268script as a wrapper, for example

270```bash

271#!/bin/bash

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

274```

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

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

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

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

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

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

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

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

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

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

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

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

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

291## Using `bat` on Windows

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

295### Paging

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

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

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

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

302### Colours

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

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

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

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

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

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

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

313### Cygwin

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

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

319```shell

320bat() {

321 local index

322 local args=("$@")

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

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

325 -*) continue;;

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

327 esac

328 done

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

331```

333## Troubleshooting

335### Terminals & colors

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

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

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

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

341terminals with truecolor support.

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

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

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

347### Line numbers and grid are hardly visible

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

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

352## Development

354```bash

355# Recursive clone to retrieve all submodules

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

358# Build (debug version)

359cd bat

360cargo build

362# Run unit tests and integration tests

363cargo test

365# Install (release version)

366cargo install

368# Build a bat binary with modified syntaxes and themes

369bash assets/create.sh

370cargo install -f

371```

373## Project goals and alternatives

375`bat` tries to achieve the following goals:

377- Provide beautiful, advanced syntax highlighting

378- Integrate with Git to show file modifications

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

380- Offer a user-friendly command-line interface

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

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