README.md · bat · git.iko.soy

git.iko.soy/bat

bat/README.md

520 lines 16 kB history raw

1

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

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>

7 A cat(1) clone with syntax highlighting and Git integration.

8

10

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 Translation [<a href="https://github.com/chinanf-boy/bat-zh">中文</a>][<a href="doc/README-ja.md">日本文</a>]

17

19### Syntax highlighting

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

22languages:

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

26### Git integration

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

29(see left side bar):

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

33### Show non-printable characters

35You can use the `-A`/`--show-all` option to show and highlight non-printable

36characters:

38![Non-printable character example](https://i.imgur.com/WndGp9H.png)

40### Automatic paging

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

44### File concatenation

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

47`bat` detects a non-interactive terminal (i.e. when you pipe into another process

48or into a file), `bat` will act as a drop-in replacement for `cat` and

49fall back to printing the plain file contents.

51## How to use

53Display a single file on the terminal

55```bash

56> bat README.md

57```

59Display multiple files at once

61```bash

62> bat src/*.rs

63```

65Read from stdin, determine the syntax automatically

67```bash

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

69```

71Read from stdin, specify the language explicitly

73```bash

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

75```

77Show and highlight non-printable characters:

78```bash

79> bat -A /etc/hosts

80```

82Use it as a `cat` replacement:

84```bash

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

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

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

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

92```

94### Integration with other tools

96#### `find` or `fd`

98You can use the `-exec` option of `find` to preview all search results with `bat`:

99```bash

100find … -exec bat {} +

101```

102

103If you happen to use [`fd`](https://github.com/sharkdp/fd), you can use the `-X`/`--exec-batch` option to do the same:

104```bash

105fd … -X bat

106```

107

108#### `tail -f`

109

110`bat` can be combined with `tail -f` to continuously monitor a given file with syntax highlighting.

111```bash

112tail -f /var/log/pacman.log | bat --paging=never -l log

113```

114Note that we have to switch off paging in order for this to work. We have also specified the syntax

115explicitly (`-l log`), as it can not be auto-detected in this case.

116

117### `git show`

118

119You can combine `bat` with `git show` to view an older version of a given file with proper syntax

120highlighting:

121```bash

122git show v0.6.0:src/main.rs | bat -l rs

123```

124

125#### `xclip`

126

127The line numbers and Git modification markers in the output of `bat` can make it hard to copy

128the contents of a file. To prevent this, you can call `bat` with the `-p`/`--plain` option or

129simply pipe the output into `xclip`:

130```bash

131bat main.cpp | xclip

132```

133`bat` will detect that the output is being redirected and print the plain file contents.

134

135## Installation

136

137### On Ubuntu

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

139

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

141and install it via:

142``` bash

143sudo dpkg -i bat_0.10.0_amd64.deb # adapt version number and architecture

144```

145

146### On Arch Linux

147

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

149from the official sources:

150

151```bash

152pacman -S bat

153```

154

155### On Fedora

156

157You can install `bat` from the [Fedora Modular](https://docs.fedoraproject.org/en-US/modularity/using-modules/) repository. On Fedora 29 and higher, it is enabled by default. Otherwise, run `dnf install fedora-repos-modular` to set up, and make sure that the `fedora-modular` and `fedora-updates-modular` repos are enabled in `/etc/yum.repos.d`.

158

159```bash

160dnf module install bat

161```

162

163### On Void Linux

164

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

166```

167xbps-install -S bat

168```

169

170### On FreeBSD

171

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

173

174```bash

175pkg install bat

176```

177

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

179

180```bash

181cd /usr/ports/textproc/bat

182make install

183```

184

185### Via nix

186

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

188

189```bash

190nix-env -i bat

191```

192

193### On openSUSE

194

195You can install `bat` with zypper:

196

197```

198zypper install bat

199```

200

201### On macOS

202

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

204

205```bash

206brew install bat

207```

208

209### On Windows

210

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

212or install it with [scoop](https://scoop.sh/) or [Chocolatey](https://chocolatey.org):

213

214```bash

215scoop install bat

216```

217

218```bash

219choco install bat

220```

221

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

223

224### Via Docker

225

226There is a [Docker image](https://hub.docker.com/r/danlynn/bat/) that you can use to run `bat` in a container:

227```bash

228docker pull danlynn/bat

229alias bat='docker run -it --rm -e BAT_THEME -e BAT_STYLE -e BAT_TABS -v "$(pwd):/myapp" danlynn/bat'

230```

231

232### Via Ansible

233

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

235

236```bash

237# Install role on local machine

238ansible-galaxy install aeimer.install_bat

239```

240

241```yaml

242---

243# Playbook to install bat

244- host: all

245 roles:

246 - aeimer.install_bat

247```

248

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

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

251

252This should work with the following distributions:

253- Debian/Ubuntu

254- ARM (eg. Raspberry PI)

255- Arch Linux

256- Void Linux

257- FreeBSD

258- MacOS

259

260### From binaries

261

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

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

264binaries are also available: look for archives with `musl` in the file name.

265

266### From source

267

268If you want to build `bat` from source, you need Rust 1.31 or

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

270

271```bash

272cargo install bat

273```

274

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

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

277

278## Customization

279

280### Highlighting theme

281

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

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

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

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

286make the change permanent. Alternatively, use `bat`s

287[configuration file](https://github.com/sharkdp/bat#configuration-file).

288

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

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

291``` bash

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

293```

294

295`bat` looks good on a dark background by default. However, if your terminal uses a

296light background, some themes like `GitHub` or `OneHalfLight` will work better for you.

297You can also use a custom theme by following the

298['Adding new themes' section below](https://github.com/sharkdp/bat#adding-new-themes).

299

300### Output style

301

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

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

304and line numbers but no grid and no file header. Set the `BAT_STYLE` environment

305variable to make these changes permanent or use `bat`s

306[configuration file](https://github.com/sharkdp/bat#configuration-file).

307

308### Adding new syntaxes / language definitions

309

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

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

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

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

314

315Create a folder with syntax definition files:

316

317```bash

318mkdir -p "$(bat --config-dir)/syntaxes"

319cd "$(bat --config-dir)/syntaxes"

320

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

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

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

324```

325

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

327

328```bash

329bat cache --build

330```

331

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

333

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

335

336```bash

337bat cache --clear

338```

339

340### Adding new themes

341

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

343

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

345```bash

346mkdir -p "$(bat --config-dir)/themes"

347cd "$(bat --config-dir)/themes"

348

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

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

351

352# Update the binary cache

353bat cache --build

354```

355

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

357

358### Using a different pager

359

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

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

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

363`PAGER`.

364

365If you want to pass command-line arguments to the pager, you can also set them via the

366`PAGER`/`BAT_PAGER` variables:

367

368```bash

369export BAT_PAGER="less -RF"

370```

371

372Instead of using environment variables, you can also use `bat`s [configuration file](https://github.com/sharkdp/bat#configuration-file) to configure the pager (`--pager` option).

373

374**Note**: By default, if the pager is set to `less` (and no command-line options are specified),

375`bat` will pass the following command line

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

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

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

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

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

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

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

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

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

385

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

387

388## Configuration file

389

390`bat` can also be customized with a configuration file. The location of the file is dependent

391on your operating system. To get the default path for your system, call

392```

393bat --config-file

394```

395

396Alternatively, you can use the `BAT_CONFIG_PATH` environment variable to point `bat` to a

397non-default location of the configuration file:

398```bash

399export BAT_CONFIG_PATH="/path/to/bat.conf"

400```

401

402### Format

403

404The configuration file is a simple list of command line arguments. Use `bat --help` to see a full list of possible options and values. In addition, you can add comments by prepending a line with the `#` character.

405

406Example configuration file:

407```bash

408# Set the theme to "TwoDark"

409--theme="TwoDark"

410

411# Show line numbers, Git modifications and file header (but no grid)

412--style="numbers,changes,header"

413

414# Use italic text on the terminal (not supported on all terminals)

415--italic-text=always

416

417# Add mouse scrolling support in less (does not work with older

418# versions of "less")

419--pager="less -FR"

420

421# Use C++ syntax (instead of C) for .h header files

422--map-syntax h:cpp

423

424# Use "gitignore" highlighting for ".ignore" files

425--map-syntax .ignore:.gitignore

426```

427

428## Using `bat` on Windows

429

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

431

432### Paging

433

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

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

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

437your `PATH` or [define an environment variable](#using-a-different-pager). The [Chocolatey package](#on-windows) installs `less` automatically.

438

439### Colors

440

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

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

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

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

445

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

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

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

449

450### Cygwin

451

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

453

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

455

456```shell

457bat() {

458 local index

459 local args=("$@")

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

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

462 -*) continue;;

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

464 esac