README.md · bat · git.iko.soy

179You can install [the `bat` package](https://koji.fedoraproject.org/koji/packageinfo?packageID=27506) from the official [Fedora Modular](https://docs.fedoraproject.org/en-US/modularity/using-modules/) repository.

180

181```bash

182dnf install bat

183```

184

185### On Gentoo Linux

186

187You can install [the `bat` package](https://packages.gentoo.org/packages/sys-apps/bat)

188from the official sources:

189

190```bash

191emerge sys-apps/bat

192```

193

194### On Void Linux

195

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

197```

198xbps-install -S bat

199```

200

201### On FreeBSD

202

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

204

205```bash

206pkg install bat

207```

208

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

210

211```bash

212cd /usr/ports/textproc/bat

213make install

214```

215

216### Via nix

217

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

219

220```bash

221nix-env -i bat

222```

223

224### On openSUSE

225

226You can install `bat` with zypper:

227

228```

229zypper install bat

230```

231

232### On macOS

233

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

235

236```bash

237brew install bat

238```

239

240### On Windows

241

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

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

244

245```bash

246scoop install bat

247```

248

249```bash

250choco install bat

251```

252

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

254

255### Via Docker

256

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

258```bash

259docker pull danlynn/bat

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

261```

262

263### Via Ansible

264

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

266

267```bash

268# Install role on local machine

269ansible-galaxy install aeimer.install_bat

270```

271

272```yaml

273---

274# Playbook to install bat

275- host: all

276 roles:

277 - aeimer.install_bat

278```

279

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

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

282

283This should work with the following distributions:

284- Debian/Ubuntu

285- ARM (eg. Raspberry PI)

286- Arch Linux

287- Void Linux

288- FreeBSD

289- MacOS

290

291### From binaries

292

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

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

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

296

297### From source

298

299If you want to build `bat` from source, you need Rust 1.35 or

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

301

302```bash

303cargo install bat

304```

305

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

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

308

309## Customization

310

311### Highlighting theme

312

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

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

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

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

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

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

319

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

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

322``` bash

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

324```

325

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

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

328You can also use a custom theme by following the

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

330

331### Output style

332

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

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

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

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

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

338

339### Adding new syntaxes / language definitions

340

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

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

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

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

345

346Create a folder with syntax definition files:

347

348```bash

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

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

351

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

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

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

355```

356

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

358

359```bash

360bat cache --build

361```

362

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

364

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

366

367```bash

368bat cache --clear

369```

370

371### Adding new themes

372

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

374

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

376```bash

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

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

379

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

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

382

383# Update the binary cache

384bat cache --build

385```

386

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

388

389### Using a different pager

390

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

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

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

394`PAGER`.

395

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

397`PAGER`/`BAT_PAGER` variables:

398

399```bash

400export BAT_PAGER="less -RF"

401```

402

403Instead 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).

404

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

406`bat` will pass the following command line

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

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

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

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

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

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

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

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

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

416

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

418

419### Dark mode

420

421If you make use of the dark mode feature in macOS, you might want to configure `bat` to use a different

422theme based on the OS theme. The following snippet uses the `default` theme when in the light mode

423and the `GitHub` theme when in the dark mode.

424

425```

426alias cat="bat --theme=\$(defaults read -globalDomain AppleInterfaceStyle &> /dev/null && echo default || echo GitHub)"

427```

428

429## Configuration file

430

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

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

433```

434bat --config-file

435```

436

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

438non-default location of the configuration file:

439```bash

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

441```

442

443### Format

444

445The 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.

446

447Example configuration file:

448```bash

449# Set the theme to "TwoDark"

450--theme="TwoDark"

451

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

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

454

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

456--italic-text=always

457

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

459# versions of "less")

460--pager="less -FR"

461

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

463--map-syntax h:cpp

464

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

466--map-syntax .ignore:.gitignore

467```

468

469## Using `bat` on Windows

470

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

472

473### Paging

474

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

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

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

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

479

480### Colors

481

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

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

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

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

486

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

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

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

490

491### Cygwin

492

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

494

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

496

497```shell

498bat() {

499 local index

500 local args=("$@")

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

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

503 -*) continue;;

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

505 esac