文档

疑难解答

少数会出岔子的地方、PullMark 的提示语各是什么 意思，以及那些安静失败背后的设计——这里的大多数“错误”，其实是应用 在刻意拒绝丢掉你的工作。

GitHub 访问：PullMark 怎么连接，怎么修

PullMark 借用你自己的工具已经持有的 GitHub 凭据——它没有自己的 登录，也从不存储任何机密。 设置 → 通用 → GitHub 显示是否已连接、以谁的身份、经由哪个来源； 设置… 会引导一台新机器完成连接， 重新检查 则立刻捕捉到修复——gh auth login 之后无需重启。

正在装有 PullMark（0.36+）的 Mac 上读这页？ 现在就打开连接行。

凭据来源，按 PullMark 尝试的顺序：

  1. GitHub CLI 的令牌： gh auth token 必须能打印出一个。没有的话， brew install gh && gh auth login——这是推荐 路径：它的令牌权限范围可靠，在浏览器流程里处理 SSO，还会自动 刷新。
  2. 否则用 git credential fill——git 自己对 github.com 用什么就用什么（macOS 钥匙串、Git Credential Manager、某次旧的 HTTPS 推送存下的令牌）。

令牌的细则，写给那些半好不坏的令牌：classic 令牌需要 repo 权限（组织团队名还需要 read:org）； fine-grained 令牌绑定在单一资源所有者上——公开仓库和 该所有者的私有仓库可用，其余一律拒绝；受 SSO 保护的组织需要为每个 组织授权令牌；手工创建的令牌会过期——“昨天还好好的”就该到设置的 那一行去诊断。

GitHub：“可能在该 ref 上并不存在，也可能属于……私有仓库”

“无法打开……它可能在该 ref 上并不存在，也可能属于你的 GitHub 凭据无权访问的私有仓库。”GitHub 的 API 对“私有且无权限”和“不存在”返回得 一模一样，所以 PullMark 没法告诉你是哪种。如果这个仓库本该可用， 那几乎总是认证问题——见上文 GitHub 访问，或打开 设置 → 通用 → GitHub 点 设置…。

Gatekeeper 不肯打开应用

正式版本以 Developer ID 签名并经 Apple 公证，正常下载不会出现 任何警告。如果你是从源码构建（make app），应用是 ad-hoc 签名的：右键 → Open → Open，或到 System Settings → Privacy & Security（系统设置 → 隐私与安全性） 里放行。

Quick Look 预览不再渲染了

Homebrew 升级会替换应用包，可能悄悄弄丢 Quick Look 扩展的注册。 PullMark 每次启动都会重新注册它——所以把应用启动一次就好。如果预览 仍显示纯文本，检查“设置 → 通用 → 快速查看预览”是否 设为“渲染后”。

“PullMark 已不再是你的默认 Markdown 应用”

同一个原因：升级替换了应用包，macOS 丢掉了 .md 绑定。 横幅上的重新设为默认一键拿回来； “设置 → 通用”里也行。

“……在你编辑这个区块期间发生了改动——什么都没有保存”

在你打开区块编辑器与保存之间，文件在磁盘上被改动了（另一个 编辑器、一个智能体、一次 git 操作）。PullMark 拒绝往已经挪动的行里 拼接内容——除了这一处编辑，什么都没丢，重新打开区块就能看到当前 文本。同一道防护也保护提交：与一个文件并不存在的引用比较时，它会 明说，而不是展示一个空差异。

变暗的行：那些“不在了”的文件夹与最近条目

带问号角标的“位置”，或者变灰的最近条目，表示路径此刻解析 不了——未挂载的卷、切换了的 git 分支、被删除的工作树。行变暗而不 消失是有意为之：路径回来时它们自动复活。点击一条失效的最近条目会 提供 从最近使用中移除或 保留。

拉取请求：横幅与待上传评论

  • “此拉取请求在 GitHub 上有更新。”——你加载 之后分支前进了。刷新只要一次点击，你的草稿评论安然无恙；审查 进行中 PullMark 绝不自动重载。
  • “无法载入审查评论……”——不提示的话， 差异就会伪装成一个没有评论的 PR；“重试”重新抓取。
  • “无法把 N 条待提交评论上传到 GitHub——已保留在本地以便 重试。”——离线（或 API 打嗝时）写下的评论按 PR head 排队 存盘，能上传时就上传。什么都不会丢。
  • “已提交……，但推送失败”——提交已经安安稳稳 在你的本地历史里；需要重试的只有推送。

更新

横幅上的立即更新会运行 brew 升级（DMG 安装则 是经校验的原位安装）并重启。如果失败，横幅会显示准确的 brew upgrade --cask pullmark 命令和一个复制按钮——在 终端里运行它效果相同。开发构建不检查更新。

pullmark 命令

  • "no such file or folder"——命令在打开任何东西之前校验 每个路径；一个笔误就中止整次打开（退出码 1），让脚本大声 失败。
  • Command not found——见 安装命令。
  • "无法安装该命令"——设置里的安装器需要 授权才能写入 /usr/local/bin；如果你关掉了那个提示， 取消后再来一次。

还是卡住？

提一个 issue——应用内的“帮助 → 报告 Bug…”会替你预填。