文档

命令行

一条命令，pullmark，把文件和 文件夹递给应用。既为终端里的人而造，也为想把文档摆到你面前的智能体 和脚本而造。

安装命令

你怎么装的 PullMark，决定你怎么得到这条命令：

• Homebrew——已经装好；cask 会把 pullmark 链接进你的 brew 前缀。
• DMG——打开 设置 (⌘,) → 通用， 点击 安装 pullmark 命令…；它会把命令链接进 /usr/local/bin（可能会要求授权）。
• 源码检出——make install-cli （加 BIN_DIR=~/bin 可自选位置）。

基本用法其实不装也行——open -a PullMark README.md ~/notes 借 macOS 自身就能做到同样的事。

用法

pullmark                     # 启动（或前置）PullMark
pullmark <path> ...          # 打开文件和/或文件夹
pullmark --diff <path> ...   # 以渲染差异打开文件（对比 HEAD）
pullmark --diff=<ref> <path> ...
                             # ……对比分支、标签或提交
pullmark --diff=<r1>..<r2> <path> ...
                             # 同一文件的两个引用版本，均已冻结
pullmark --diff-with=<file> <path> ...
                             # ……对比磁盘上的另一个文件
pullmark -h, --help          # 内置参考
pullmark --version           # 打印应用版本

打开时会发生什么

规则刻意乏味，好让脚本可以放心依赖：

• 文件落进侧边栏的 “打开的文件”分区，作为固定 条目，最后传入的文件会被显示。
• 文件夹——包括 git 工作树——成为 “位置”：其中 Markdown 文件的可浏览树。
• 应用已在运行？一切都在最前面的窗口打开。绝不会 启动第二个应用实例。
• 相对路径相对你的当前目录解析；~ 照常工作。
• 不存在的路径会中止整条命令，并给出一条消息和 退出码 1——不会打开一半。

工作树，以及指定单个文件

同时传一个文件夹和一个文件，两种行为一起发生：文件夹作为“位置” 打开，文件固定并显示。这就是“打开这个工作树、给我看这份文档”的 完整配方：

$ pullmark ~/wt/feature ~/wt/feature/docs/plan.md

工作树的文件树进入“位置”（带分支标签，因为工作树就是一个 git 检出），plan.md 固定在“打开的文件”中并渲染出来。右键它选 在“位置”中显示即可跳到它在树中的 落点。若该“位置”早已打开，行为完全相同——打开位于其中的文件绝不会 造出一个重复的世界，只会多一条工作集条目。

文件夹/文件的配对不看顺序，但显示的是最后传入的文件， 所以把你想上屏的文档放在最后。

来自 shell 的渲染差异

--diff 让每个文件以比较状态打开——工作内容 对比最后一次提交，呈现为拉取请求同款的渲染词级差异。 --diff=<ref> 改为对比某个分支、标签或提交 SHA。 它是通往应用内“比较”功能（工具栏的时钟加箭头按钮）的 shell 之门，也是“智能体刚对这份文档做了什么”的最快答案：

$ pullmark --diff docs/plan.md            # 最近的编辑改了什么
$ pullmark --diff=main README.md          # 当前文件对比 main
$ pullmark --diff=v1.0..main README.md    # 两个修订之间，均已冻结
$ pullmark --diff-with=old.md new.md      # 两个文件，old.md 为基准
$ pullmark --diff ~/wt/feature ~/wt/feature/docs/plan.md
                                          # 一个工作树，plan.md 以差异显示

一同传入的文件夹照常作为“位置”打开，每种形式在工具栏的 “比较”菜单里都有应用内的孪生兄弟（包括 比较修订版本… 和 与文件比较…）。因为 --diff 和 --diff-with 是旗标而非子命令，一个恰好叫 diff 的文件永远会被正常 打开。

退出码

示例

$ pullmark README.md                      # 阅读单个文件
$ pullmark ~/notes                        # 浏览文件夹
$ pullmark docs specs/design.md           # 一个“位置”外加一份文档
$ pullmark ~/wt/feature docs/plan.md      # 一个工作树，显示一份文档
$ pullmark --diff docs/plan.md            # 最近的编辑改了什么
$ pullmark -- --weird-filename.md         # -- 结束选项解析

给智能体的说明

如果你要把 PullMark 接进智能体或脚本：

• 命令在 macOS 接受打开请求后立即返回——它不等应用渲染 完成。
• 重复打开是幂等的：已打开的文件或文件夹会被选中，不会 重复。
• 一切都落在最前面的窗口，这是设计使然——盯着一个窗口的人能 看到每次打开都到那里去。
• 编辑完文档之后，pullmark --diff <file> 是把 你改了什么摆到人面前的一行代码——渲染呈现，改动的词 高亮。