bat/doc/README-zh.md

类似 cat(1)，但带有 git 集成和语法高亮.

主要功能 • 使用方法 • 安装 • 自定义 • 项目目标和替代方案
[English] [中文] [日本語] [한국어] [Русский]

语法高亮

bat 对大部分编程语言和标记语言提供语法高亮：

Git 集成

bat 能从 git 中获取文件的修改并展示在边栏（见下图）：

不可打印(non-printable)字符可视化

添加-A/--show-all参数可以文件文件中的不可打印字符:

自动分页

bat会在一般情况下将大于屏幕可显示范围的内容输出到分页器(pager, e.g. less)。

你可以在调用时添加--paging=never参数来使bat不使用分页器（就像cat一样）。如果你想要用为cat使用bat别名，可以在 shell 配置文件（shell configuration）中添加alias cat='bat --paging=never'。

智能输出

bat能够在设置了分页器选项的同时进行管道😉。 当bat检测到当前环境为非可交互终端或管道时（例如使用bat并将内容用管道输出到文件），bat会像cat一样，一次输出文件内容为纯文本且无视--paging参数。

如何使用

在终端中查看一个文件

> bat README.md

一次性展示多个文件

> bat src/*.rs

从stdin读入流，自动为内容添加语法高亮（前提是输入内容的语言可以被正确识别，通常根据内容第一行的 shebang 标记，形如#!bin/sh）

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

显式指定stdin输入的语言

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

显示不可打印字符

> bat -A /etc/hosts

与cat的兼容性

bat > note.md  # 创建一个空文件

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

bat -n main.rs  # 只显示行号

bat f - g  # 输出 f，接着是标准输入流，最后 g

第三方工具交互

fzf

你可以使用bat作为fzf的预览器。这需要在bat后添加--color=always选项，以及--line-range 选项来限制大文件的加载次数。

fzf --preview 'bat --color=always --style=numbers --line-range=:500 {}'

更多信息请参阅fzf的说明。

find 或 fd

你可以使用find的-exec选项来用bat预览搜索结果：

find … -exec bat {} +

亦或者在用fd时添加-X/--exec-batch选项：

fd … -X bat

ripgrep

bat也能用batgrep来显示ripgrep的搜索结果。

batgrep needle src/

tail -f

当与tail -f一起使用，bat可以持续监视文件内容并为其添加语法高亮。

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

注意：这项功能需要在关闭分页时使用，同时要手动指定输入的内容语法（通过-l log）。

git

bat也能直接接受来自git show的输出并为其添加语法高亮（当然也需要手动指定语法）：

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

git diff

bat也可以和git diff一起使用：

batdiff() {
    git diff --name-only --diff-filter=d | xargs bat --diff
}

该功能也作为一个独立工具提供，你可以在bat-extras中找到batdiff。

如果你想了解更多 git 和 diff 的信息，参阅delta。

xclip

当需要拷贝文件内容时，行号以及 git 标记会影响输出，此时可以使用-p/--plain参数来把纯文本传递给xclip。

bat main.cpp | xclip

bat会检测输出是否是管道重定向来决定是否使用纯文本输出。

man

bat也能给man的输出上色。这需要设置MANPAGER环境变量：

export MANPAGER="sh -c 'col -bx | bat -l man -p'"
man 2 select

（如果你使用的是 Debian 或者 Ubuntu，使用batcat替换bat）

如果你遇到格式化问题，设置MANROFFOPT="-c"也许会有帮助。

batman能提供类似功能——作为一个独立的命令。

注意：man page 语法 还需要完善。在使用特定的man实现时该功能无法正常工作。

prettier / shfmt / rustfmt

prettybat脚本能够格式化代码并用bat输出。

安装

Ubuntu (使用 apt)

... 以及其他基于 Debian的发行版.

bat 要求的版本： Ubuntu 高于 20.04 ("Focal") 和 Debian 高于 August 2021 (Debian 11 - "Bullseye").

当你的发行版满足条件那么直接在终端运执行：

sudo apt install bat

重要：如果你通过这种方法安装bat，请留意你所安装的可执行文件是否为batcat（由其他包的可执行文件名冲突造成）。你可以创建一个bat -> batcat的符号链接(symlink)或别名来避免因为可执行文件不同带来的问题并与其他发行版保持一致性。

mkdir -p ~/.local/bin
ln -s /usr/bin/batcat ~/.local/bin/bat

Ubuntu (使用.deb包)

... 以及其他基于 Debian的发行版.

如果你无法使用上一种方法安装，或需要用最新版的bat，你可以从release 页面下载最新的.deb包并通过下述方法安装：

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

Alpine Linux

你可以用下面下列命令从官方源中安装bat 包：

apk add bat

Arch Linux

你可以用下面下列命令从官方源中安装bat包：

pacman -S bat

Fedora

你可以使用下列命令从官方Fedora Modular仓库安装bat 包：

dnf install bat

Funtoo Linux

你可以从 dev-kit 中安装bat 包：

emerge sys-apps/bat

Gentoo Linux

你可以使用下列命令从官方源中安装 bat 包：

emerge sys-apps/bat

Void Linux

你可以用 xbps-install 安装bat：

xbps-install -S bat

Termux:

你可以用 pkg 安装`bat：

pkg install bat

FreeBSD

你可以用 pkg 来安装一份预编译的bat 包：

pkg install bat

或从 FreeBSD ports 自己编译一份：

cd /usr/ports/textproc/bat
make install

OpenBSD

你可以用pkg——add安装bat包

pkg_add bat

通过 nix

你可以用nix 包管理器安装bat：

nix-env -i bat

openSUSE

你可以用 zypper 安装bat：

zypper install bat

通过 snap

目前还没有推荐的 snap 包可用。可以使用其他现存的包但不会受到官方支持且可能会遇到问题。

macOS (或 Linux) 通过 Homebrew

你可以用 Homebrew on MacOS 或者 Homebrew on Linux 安装bat：

brew install bat

macOS 通过 MacPorts

或用 MacPorts 安装bat：

port install bat

Windows

在 Windows 上具有多种安装bat的方法。若你已完成安装，记得看看 "在 Windows 上使用bat" 。

前置条件

你必须已安装 Visual C++ Redistributable 包。

使用 Chocolatey

你可以用Chocolatey 安装bat：

choco install bat

使用 Scoop

你可以用 scoop 安装bat：

scoop install bat

使用预编译二进制版本

直接从 Release 发布页 下载已经编译好的二进制包，前提是你安装了 Visual C++ Redistributable 包。

使用二进制版本

在 Release 发布页 中可以找到为多种架构构建的bat版本和静态编译的二进制文件（文件名带有musl）。

从源码编译

如果你想要自己构建bat，那么你需要安装有高于1.70.0版本的 Rust。

使用以下命令编译。

cargo install --locked bat

注意：man page或 shell 自动补全所需要的额外文件无法通过该方法安装。但你可以在cargo的生成目录找到这些文件（build目录下）。

自定义

语法高亮主题

使用 bat --list-themes 一份语法高亮主题的清单，然后用--theme=TwoDark来指定主题为TwoDark，也可以通过设置BAT_THEME环境变量来选定主题。把export BAT_THEME="TwoDark"添加到 shell 的启动脚本（shell startup file）来取得永久效果。或者使用bat的配置文件

若想要查看所有主题在一个文件上的显示效果可以用一下命令（需要安装fzf）：

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

bat在默认情况下能够在黑色主题背景下获得较好的效果，如果你的终端使用亮色背景，可以试试GitHub或OneHalfLight。想要添加自定义主题可以参考添加主题。

8-bit 主题

bat 自带三个 8-bit 色彩 主题：

• ansi 适应于大部分终端。它使用 3-bit 色彩：黑红绿黄蓝洋红靛青白。
• base16专为 base16 终端设计。它使用 4-bit 色彩（带有亮度的 3-bit 色彩）。根据 base16 styling guidelines 制作。
• base16-25专为 base16-shell 设计。它把部分亮色替换为 8-bit 色彩。请不要直接使用该主题，除非你清楚你的256色终端是否使用 base16-shell。

尽管这些主题具有诸多限制，但具有一些 truecolor 主题不具有的三个优点：

• 享有最佳兼容性。并不是所有终端工具都支持高于 3-bit 的色彩。
• 适应终端主题。
• 视觉上和其他的终端工具更协调。

输出样式

你可以用--style参数来控制bat输出的样式。使用--style=numbers,changes可以只开启 Git 修改和行号显示而不添加其他内容。BAT_STYLE环境变量具有相同功能。

添加新的语言和语法

当现有的bat不支持某个语言或语法时你可以自己添加。

bat使用syntect库来支持语法高亮，该库使用 Sublime Text .sublime-syntax 语法文件和主题。而后者中的大部分可以在 Package Control 找到。

当你找到一份语法文件，按照下列方法：

1. 创建包含语法描述文件的目录：

   mkdir -p "$(bat --config-dir)/syntaxes"
   cd "$(bat --config-dir)/syntaxes"
   
   # Put new '.sublime-syntax' language definition files
   # in this folder (or its subdirectories), for example:
   git clone https://github.com/tellnobody1/sublime-purescript-syntax
   

2. 调用下面指令把文件转换为二进制缓存：

   bat cache --build
   

3. 最后用bat --list-languages来检查新的语法是否被成功导入。如果想要回滚到最初状态，执行：

   bat cache --clear
   

4. 如果你觉得bat有必要自带该语法支持，请在阅读指导后向仓库提交 Syntax Request。

添加主题

类似添加语法支持，第一步也是创建一个带有语法高亮的目录

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

# 下载一个主题
git clone https://github.com/greggb/sublime-snazzy

# 更新二进制缓存
bat cache --build

然后用bat --list-themes检查添加是否成功。

添加或修改文件关联

你可以用--map-syntax参数添加或修改文件名模板。它需要一个类似pattern:syntax的参数来指定，其中pattern是 glob 文件匹配模板，syntax则是支持的语法的完整名（使用bat --list-languages来查看获取一份清单）。

注意：方便起见，你可能需要把参数添加到配置文件，而不是每次都在命令行中传递该参数。

以下展示了把“INI”关联到具有.conf扩展名的文件

--map-syntax='*.conf:INI'

把.ignore文件与“Git Ignore”关联

--map-syntax='.ignore:Git Ignore'

把/etc/apache2内的.conf文件关联到“Apache Conf”语法（bat已默认绑定）

--map-syntax='/etc/apache2/**/*.conf:Apache Conf'

使用自定义分页器

bat默认使用PAGER环境变量定义的分页器，如果没有定义则使用less。bat提供了BAT_PAGER环境变量来专为bat选择分页器（优先级高于PAGER）。

注意：当PAGER设置为more或most时，bat会使用less来代替以确保能提供色彩支持。

export BAT_PAGER="less -RF"

除了使用环境变量来改变bat使用的的分页器，也可以在配置文件中提供--pager参数。

注意：bat会把部分命令行参数直接传递给分页器：-R/--RAW-CONTROL-CHARS,-F/--quit-if-one-screen以及-X/--no-init（该参数仅适用于高于530版本的less）。其中-R 参数需要在解释 ANSI 标准颜色时起作用。-F则指示less在输出内容的垂直尺寸小于终端尺寸时立即退出。当文件内容可以在一个屏幕里完全显示时，就不需要按q键退出阅读模式，很方便就是了。-X则能修复-F在less的老版本中的一些bug（代价是不支持鼠标滚轮，但可以用-R来取消quit-if-one-screen功能。）。

缩进

bat 使用四个空格宽的制表符，而不受分页器影响，同时也可以用--tabs参数来自定义。

注意：通过其他方法针对分页器的制表符设置不会生效（例如通过bat的--pager参数传递或less使用的LESS环境变量）。因为在输出提交给分页器之前，内容中的制表符就已经被bat替换为了特定长度的空格以避免由于边栏导致的缩进问题。你可以用给bat传递--tabs=0参数来取消该设定并让分页器自己处理制表符。

暗色模式

如果你用的 macOS 处于暗色模式，你可以为bat启用基于系统主题的主题。如下所示操作会让bat在系统处于亮色模式时加载GitHub主题和暗色模式时加载default主题。

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

配置文件

bat --config-file

你也可以用BAT_CONFIG_PATH来为bat指定自定义位置的配置文件：

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

使用--generate-config-file参数调用bat会在指定位置生成一份默认的bat配置文件：

bat --generate-config-file

格式

配置文件其实是一份按行分割的命令行参数列表。你可以用bat --help来查看所有可用的参数和适用的值。配置文件中#打头的行会被视为注释而不生效。

以下是一份示例：

# 设置主题为 TwoDark
--theme="TwoDark"

# 显示行号和 Git 修改信息， 但没有边框
--style="numbers,changes,header"

# 在终端中以斜体输出文本（不是所有终端都支持）
--italic-text=always

# 使用 C++ 语法来给 Arduino 的 .ino 文件提供高亮
--map-syntax "*.ino:C++"

在 Windows 中使用 bat

bat 在 Windows 上开箱即用，除了部分功能需要额外配置。

前置条件

你需要先安装 Visual C++ Redistributable 包。

分页

Windows 只有一个提供有限功能的分页器，你可以从这里下载或用 Chocolatey 安装 Windows 版本的less。第一种方法需要你把它所在目录加入PATH环境变量或定义分页器变量

色彩

Windows 10 从 v1511 开始 shell（conhost.exe，命令提示符或 Powershell）原生支持色彩。在早些版本的 Windows 中你可以用第三方终端如 Cmder （使用ConEmu）。

注意：Git 和 MSYS 版本的 less 没法正确在 Windows 表达色彩。如果你没有安装其他分页器，你可以直接用--paging=never或设置BAT_PAGER为空字符串来关闭分页功能。

Cygwin

Windows 上的bat原生不支持 Cygwin' unix-style 路径（/cygdrive/*）。当传递一个绝对 cygwin 路径作为参数值时，bat会产生The system cannot find the path specified. (os error 3)的错误。你可以.bash_profile文件中添加以下函数来解决这个问题。

bat() {
    local index
    local args=("$@")
    for index in $(seq 0 ${#args[@]}) ; do
        case "${args[index]}" in
        -*) continue;;
        *)  [ -e "${args[index]}" ] && args[index]="$(cygpath --windows "${args[index]}")";;
        esac
    done
    command bat "${args[@]}"
}

疑难解答

输出内容含糊不清

当输入文件包含颜色代码和其他 ANSI 转义符号时，bat会产生错误的语法高亮和文本，导致输出看起来令人无法理解。当你需要输出该文件时，请使用--color=never --wrap=never参数来关闭上色和文字包裹。

终端与色彩

bat会区分支持 truecolor 和不支持 truecolor 的终端。但是大部分语法高亮主题都是用了没有为 8-bit 色彩支持的颜色，因此强烈推荐使用一个支持 24-bit 色彩的终端（terminator，konsole，iTerm2...），或使用一个 8-bit 主题来限制一些颜色。查看这篇文章使用自定义分页器了解更多支持 truecolor 的终端。你需要定义COLORTERM变量为truecolor或24bit来确保bat能够识别终端的对颜色的支持，否则会使用 8 bit 模式。

行号和边框很难看清

试试其他主题，说不定能有所改善（用bat --list-themes查看主题列表）。

文件编码

bat原生支持 UTF-8 和 UTF-16。至于其他文件你可能需要在使用bat之前先把编码转换到UTF-8。

这里展示了使用iconv来把 Latin-1(ISO-8859-1) 编码的 PHP 文件转换到 UTF-8：

iconv -f ISO-8859-1 -t UTF-8 my-file.php | bat

注意： 当bat无法识别语言时你可能会需要-l/--language参数。

开发

# 递归 clone 以获取所有子模块
git clone --recursive https://github.com/sharkdp/bat

# 构建（调试版本）
cd bat
cargo build --bins

# 运行单元测试和集成测试
cargo test

# 安装（发布版本）
cargo install --path . --locked

# 使用修改后的语法和主题构建一个 bat 二进制文件
bash assets/create.sh
cargo install --path . --locked --force

如果你想构建一个使用 bat 美化打印功能的应用程序，请查看 API 文档。请注意，当你依赖 bat 作为库时，必须使用 regex-onig 或 regex-fancy 作为特性。

贡献指南

请查看 CONTRIBUTING.md 指南。

维护者

• sharkdp
• eth-p
• keith-hall
• Enselic

安全漏洞

如果你想报告 bat 中的漏洞，请通过邮件联系 David Peter。

项目目标和替代方案

bat 试图实现以下目标：

• 提供美观的高级语法高亮
• 与 Git 集成以显示文件修改
• 成为 (POSIX) cat 的替代品
• 提供用户友好的命令行界面

如果你在寻找类似的程序，有很多替代方案。请参阅本文档进行比较。

许可证

版权所有 (c) 2018-2021 bat-developers。

bat 可根据 MIT 许可证或 Apache 许可证 2.0 的条款使用，任选其一。

有关许可证的详细信息，请参阅 LICENSE-APACHE 和 LICENSE-MIT 文件。