命令行界面

相关源文件

• assets/completions/_bat.ps1.in
• assets/completions/bat.bash.in
• assets/completions/bat.fish.in
• assets/completions/bat.zsh.in
• assets/manual/bat.1.in
• doc/long-help.txt
• doc/short-help.txt
• src/theme.rs
• tests/syntax-tests/highlighted/cmd-help/test.cmd-help
• tests/syntax-tests/source/cmd-help/test.cmd-help

此页面提供了 bat 支持的所有命令行选项、子命令和参数的全面参考。它涵盖了控制 bat 功能的各种 CLI 参数的语法、行为和相互关系。

有关应用程序启动期间命令行参数如何被解析和处理的信息，请参阅 应用程序入口点和配置。有关配置文件和环境变量的详细信息，请参阅 配置系统。

命令结构概述

Bat 支持两种主要的命令模式：主文件处理命令和缓存管理子命令。

来源： assets/manual/bat.1.in4-6 doc/long-help.txt3-4 doc/short-help.txt3-4

主命令选项

文件和输入选项

选项	短期	描述	示例
[文件]...	-	要处理的输入文件，或 - 表示标准输入	bat file1.txt file2.py
--file-name <名称>	-	覆盖标准输入显示的文件名	cat data.json | bat --file-name data.json
--map-syntax <glob:语法>	-m	将文件模式映射到语法定义	--map-syntax '*.build:Python'
--ignored-suffix <后缀>	-	忽略文件扩展名后缀	--ignored-suffix .dev

主命令处理一个或多个文件，当未提供文件或指定 - 作为文件名时，会特别处理标准输入。

来源： assets/manual/bat.1.in266-269 doc/long-help.txt7-9 assets/manual/bat.1.in69-71 assets/manual/bat.1.in140-151

语法高亮选项

来源： src/theme.rs8-16 assets/manual/bat.1.in46-51 assets/manual/bat.1.in153-186

选项	短期	值	描述
--language <语言>	-l	语言名称或扩展名	显式设置语法高亮语言
--theme <主题>	-	主题名称或特殊值	设置高亮颜色主题
--theme-dark <主题>	-	主题名称	深色终端背景主题
--theme-light <主题>	-	主题名称	浅色终端背景主题
--list-languages	-L	-	显示支持的语言
--list-themes	-	-	显示可用主题

主题特殊值

除了主题名称外，--theme 选项还接受几个特殊值

• auto（默认）：根据终端背景自动选择主题
• auto:always：即使输出被重定向，也强制检测终端颜色
• auto:system：使用系统范围的颜色偏好（仅限 macOS）
• dark：使用 --theme-dark 指定的主题
• light：使用 --theme-light 指定的主题

来源： src/theme.rs66-77 assets/manual/bat.1.in159-172 doc/long-help.txt123-131 assets/completions/bat.fish.in75-88

显示和样式选项

选项	短期	值	描述
--style <组件>	-	逗号分隔列表	配置显示的元素
--plain	-p	-	显示纯样式（--style=plain 的别名）
--number	-n	-	仅显示行号（--style=numbers 的别名）
--show-all	-A	-	显示不可打印字符
--nonprintable-notation <符号>	-	caret, unicode	如何显示不可打印字符

样式组件

--style 选项接受以下组件

• default：推荐的组件（changes, grid, header-filename, numbers, snip）
• full：所有可用组件
• auto：与 default 相同，除非输出被管道
• plain：无装饰
• changes：Git 修改标记
• header / header-filename：显示文件名
• header-filesize：显示文件大小
• grid：垂直/水平分隔线
• rule：文件之间的水平线
• numbers：侧边栏的行号
• snip：范围之间的分隔线

来源： assets/manual/bat.1.in200-208 doc/long-help.txt158-189 assets/completions/bat.fish.in75-88

输出控制选项

来源： assets/manual/bat.1.in104-138 doc/long-help.txt78-106

选项	短期	值	描述
--color <何时>	-	auto, never, always	何时使用彩色输出
--decorations <何时>	-	auto, never, always	何时显示样式装饰
--paging <何时>	-	auto, never, always	何时使用分页器
--pager <命令>	-	命令字符串	指定使用哪个分页器
--wrap <模式>	-	auto, never, character	文本换行行为
--terminal-width <宽度>	-	数字或偏移量	覆盖终端宽度检测
--chop-long-lines	-S	-	截断长行（--wrap=never 的别名）
--force-colorization	-f	-	强制使用颜色和装饰

范围和高亮选项

选项	短期	格式	描述
--line-range <N:M>	-r	30:40, :40, 40:, 30:+10	仅打印指定的行范围
--highlight-line <N:M>	-H	与 line-range 相同	使用不同背景高亮指定的行
--diff	-d	-	仅显示 Git 修改过的行
--diff-context <N>	-	数字	Git 更改周围的上下文行数

范围说明支持多种格式

• N:M - 第 N 行到第 M 行
• :M - 第 1 行到第 M 行
• N: - 第 N 行到文件末尾
• N:+X - 从第 N 行开始的 X 行
• N - 仅第 N 行（用于 --line-range）

来源： assets/manual/bat.1.in53-67 assets/manual/bat.1.in210-222 doc/long-help.txt40-58

文本处理选项

选项	短期	值	描述
--tabs <T>	-	数字	设置制表符宽度（0 = 直接传递）
--squeeze-blank	-s	-	压缩连续的空行
--squeeze-limit <N>	-	数字	最大连续空行数
--strip-ansi <when>	-	auto, always, never	剥离 ANSI 转义序列的时机
--italic-text <when>	-	always, never	使用斜体文本格式的时机

来源： assets/manual/bat.1.in81-83 assets/manual/bat.1.in192-198 doc/long-help.txt60-61 doc/long-help.txt153-156

缓存子命令

bat cache 子命令用于管理用于性能优化的语法定义和主题缓存文件。

来源： assets/manual/bat.1.in272 assets/manual/bat.1.in299-324

缓存选项

选项	短期	描述
--build	-b	初始化或更新语法/主题缓存
--clear	-c	删除缓存的语法定义和主题
--source <dir>	-	指定加载语法和主题的目录
--target <dir>	-	指定存储缓存文件的目录
--blank	-	创建全新的缓存（不追加到默认值）
--acknowledgements	-	构建 acknowledgements.bin 文件

缓存系统允许用户通过将 .sublime-syntax 和 .tmTheme 文件放在配置目录中，然后重新构建缓存来添加自定义语法定义和主题。

来源： assets/completions/bat.zsh.in10-18 assets/completions/bat.fish.in228-238

信息和实用选项

选项	短期	描述
--help	-h	显示帮助信息（短形式用 -h，详细信息用 --help）
--version	-V	显示版本信息
--config-dir	-	显示 bat 的配置目录路径
--config-file	-	显示配置文件路径
--cache-dir	-	显示缓存目录路径
--generate-config-file	-	生成默认配置文件
--diagnostic	-	显示用于错误报告的诊断信息
--acknowledgements	-	显示包含组件的致谢信息

配置控制选项

选项	描述
--no-config	不使用配置文件
--no-custom-assets	不加载自定义语法/主题资源
--lessopen	启用 $LESSOPEN 预处理器
--no-lessopen	禁用 $LESSOPEN 预处理器
--set-terminal-title	使用分页器时将终端标题设置为文件名

来源： assets/manual/bat.1.in257-263 assets/manual/bat.1.in287-298 assets/manual/bat.1.in331-355

环境变量

bat 识别出几个与命令行选项对应的环境变量

可变	等效选项	描述
BAT_THEME	--theme	默认主题选择
BAT_THEME_DARK	--theme-dark	深色背景主题
BAT_THEME_LIGHT	--theme-light	浅色背景主题
BAT_STYLE	--style	默认样式组件
BAT_PAGING	--paging	默认分页行为
BAT_PAGER	--pager	默认分页命令
BAT_CONFIG_PATH	-	配置文件路径
PAGER	--pager	系统分页器（被 BAT_PAGER 覆盖）

环境变量会被命令行选项覆盖，并且优先级低于配置文件设置。

来源： src/theme.rs9-16 assets/manual/bat.1.in129 assets/manual/bat.1.in206 assets/manual/bat.1.in279-280

选项优先级和交互

来源： assets/manual/bat.1.in40-44 doc/long-help.txt30-33 doc/long-help.txt165-169

一些选项具有特殊关系并会覆盖行为

• -p/--plain 等同于 --style=plain
• -pp 结合了 --style=plain --paging=never
• -n/--number 等同于 --style=numbers
• -f/--force-colorization 同时设置 --decorations=always 和 --color=always
• -S/--chop-long-lines 等同于 --wrap=never

当样式选项包含 + 或 - 前缀时，它们会修改之前的样式设置，而不是完全替换它们。

来源： assets/manual/bat.1.in40-44 assets/manual/bat.1.in100-102 assets/manual/bat.1.in120-124 doc/long-help.txt165-169