主要功能 •
使用方法 •
安装 •
自定义 •
项目目标和替代方案
[English]
[中文]
[日本語]
[한국어]
[Русский]
bat
对大部分编程语言和标记语言提供语法高亮:
bat
能从 git 中获取文件的修改并展示在边栏(见下图):
添加-A
/--show-all
参数可以文件文件中的不可打印字符:
bat
会在一般情况下将大于屏幕可显示范围的内容输出到分页器(pager, e.g. less
)。
你可以在调用时添加--paging=never
参数来使bat
不使用分页器(就像cat
一样)。如果你想要用为cat
使用bat
别名,可以在 shell 配置文件(shell configuration)中添加alias cat='bat --paging=never'
。
bat
能够在设置了分页器选项的同时进行管道:wink:。
当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
你可以使用bat
作为fzf
的预览器。这需要在bat
后添加--color=always
选项,以及--line-range
选项来限制大文件的加载次数。
fzf --preview 'bat --color=always --style=numbers --line-range=:500 {}'
更多信息请参阅fzf
的说明。
你可以使用find
的-exec
选项来用bat
预览搜索结果:
find … -exec bat {} +
亦或者在用fd
时添加-X
/--exec-batch
选项:
fd … -X bat
bat
也能用batgrep
来显示ripgrep
的搜索结果。
batgrep needle src/
当与tail -f
一起使用,bat
可以持续监视文件内容并为其添加语法高亮。
tail -f /var/log/pacman.log | bat --paging=never -l log
注意:这项功能需要在关闭分页时使用,同时要手动指定输入的内容语法(通过-l log
)。
bat
也能直接接受来自git show
的输出并为其添加语法高亮(当然也需要手动指定语法):
git show v0.6.0:src/main.rs | bat -l rs
bat
也可以和git diff
一起使用:
batdiff() {
git diff --name-only --diff-filter=d | xargs bat --diff
}
该功能也作为一个独立工具提供,你可以在bat-extras
中找到batdiff
。
如果你想了解更多 git 和 diff 的信息,参阅delta
。
当需要拷贝文件内容时,行号以及 git 标记会影响输出,此时可以使用-p
/--plain
参数来把纯文本传递给xclip
。
bat main.cpp | xclip
bat
会检测输出是否是管道重定向来决定是否使用纯文本输出。
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
实现时该功能无法正常工作。
prettybat
脚本能够格式化代码并用bat
输出。
... 以及其他基于 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
... 以及其他基于 Debian的发行版.
如果你无法使用上一种方法安装,或需要用最新版的bat
,你可以从release 页面下载最新的.deb
包并通过下述方法安装:
sudo dpkg -i bat_0.18.3_amd64.deb # adapt version number and architecture
你可以用下面下列命令从官方源中安装bat 包
:
apk add bat
你可以用下面下列命令从官方源中安装bat
包:
pacman -S bat
你可以使用下列命令从官方Fedora Modular仓库安装bat
包:
dnf install bat
你可以从 dev-kit 中安装bat
包:
emerge sys-apps/bat
你可以使用下列命令从官方源中安装 bat
包:
emerge sys-apps/bat
你可以用 xbps-install 安装bat
:
xbps-install -S bat
你可以用 pkg 安装`bat:
pkg install bat
你可以用 pkg 来安装一份预编译的bat
包:
pkg install bat
或从 FreeBSD ports 自己编译一份:
cd /usr/ports/textproc/bat
make install
你可以用pkg——add
安装bat
包
pkg_add bat
你可以用nix 包管理器安装bat
:
nix-env -i bat
你可以用 zypper 安装bat
:
zypper install bat
目前还没有推荐的 snap 包可用。可以使用其他现存的包但不会受到官方支持且可能会遇到问题。
你可以用 Homebrew on MacOS 或者 Homebrew on Linux 安装bat
:
brew install bat
或用 MacPorts 安装bat
:
port install bat
在 Windows 上具有多种安装bat
的方法。若你已完成安装,记得看看 "在 Windows 上使用bat
" 。
你必须已安装 Visual C++ Redistributable 包。
你可以用Chocolatey 安装bat
:
choco install bat
你可以用 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
。想要添加自定义主题可以参考添加主题。
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 找到。
当你找到一份语法文件,按照下列方法:
-
创建包含语法描述文件的目录:
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
-
调用下面指令把文件转换为二进制缓存:
bat cache --build
-
最后用
bat --list-languages
来检查新的语法是否被成功导入。如果想要回滚到最初状态,执行:bat cache --clear
-
如果你觉得
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++"
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
为空字符串来关闭分页功能。
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
指南。
如果你想报告 bat
中的漏洞,请通过邮件联系 David Peter。
bat
试图实现以下目标:
- 提供美观的高级语法高亮
- 与 Git 集成以显示文件修改
- 成为 (POSIX)
cat
的替代品 - 提供用户友好的命令行界面
如果你在寻找类似的程序,有很多替代方案。请参阅本文档进行比较。
版权所有 (c) 2018-2021 bat-developers。
bat
可根据 MIT 许可证或 Apache 许可证 2.0 的条款使用,任选其一。
有关许可证的详细信息,请参阅 LICENSE-APACHE 和 LICENSE-MIT 文件。