macOS

macOS 使用说明

TriForge Git 的 VSIX 不含原生 .node、.dylib 或 CPU 专属二进制，理论上同一个包可运行在 Intel Mac 和 Apple Silicon Mac。扩展代码使用 VS Code API、Node.js API 和系统 git，没有 PowerShell、CMD 或 git.exe 依赖。

0.5.0 已通过跨平台静态审查，但项目尚未在 macOS CI 和所有真实 Mac 组合上完成正式认证。重要仓库首次使用前，请按本页做冒烟测试。

要求

• VS Code 1.98 或更高版本；
• Git 2.31 或更高版本；
• 受信任的本地文件系统工作区；
• 平台 API 和 Git HTTPS 网络可达。

查看架构和版本：

uname -m
which git
git --version

arm64 表示 Apple Silicon，x86_64 表示 Intel 或 Rosetta 环境。

安装 Git

macOS 第一次运行 git 可能提示安装 Xcode Command Line Tools：

xcode-select --install

安装后重新执行 git --version。系统自带 Git 可能不是你通过 Homebrew/MacPorts 安装的版本。

VS Code 从哪里找到 Git

0.5.0 固定通过 PATH 启动命令名 git，没有单独的 triforge.git.path 设置，也不保证复用 VS Code 内置 Git 扩展解析到的路径。

从 Dock/Finder 启动的 VS Code 与 Terminal 的 PATH 可能不同。可能出现：

• Terminal 的 which git 指向 Homebrew 新版；
• TriForge 扩展宿主找到 /usr/bin/git；
• 两边版本或全局配置不同。

遇到行为差异时：

1. 确认 VS Code 内置终端中的 which git 和 git --version；
2. 完全退出所有 VS Code 窗口后重新打开；
3. 检查启动环境的 PATH；
4. 在 TriForge 输出日志中查看实际错误；
5. 不要通过把 Token 写入全局 Git 配置来“修复”路径问题。

后续版本适合增加可见的 Git 可执行文件与版本诊断；0.5.0 用户需自行确认。

安装 VSIX

code --install-extension ./triforge-git-0.5.0.vsix

若 code 命令不存在：在 VS Code 命令面板运行“Shell Command: Install 'code' command in PATH”，或通过扩展视图的“从 VSIX 安装…”完成。

快捷键

提交框实现同时识别 Control 和 Meta 键：

• macOS：Command+Enter；
• Windows/Linux：Ctrl+Enter。

0.5.0 输入框占位文案可能只写 Ctrl+Enter，但 Mac 上 Command+Enter 可用。

Keychain 与 SecretStorage

Token 由 VS Code SecretStorage 保存。在桌面版中，底层由 Electron safeStorage 提供平台加密，用户可能看到与系统钥匙串有关的授权行为。

以下情况需要在 Mac 重新输入 Token：

• 从 Windows/Linux 换到 Mac；
• 换了一台 Mac；
• 扩展 ID 从 local-lab.triforge-git 变为 zhangxh-math.triforge-git；
• 清除 VS Code 用户数据或钥匙串条目；
• 修改了连接的实例 URL。

SecretStorage 不通过 Settings Sync 跨设备同步，这是安全设计。

文件路径注意事项

macOS 默认 APFS 通常不区分文件名大小写，但也可以创建区分大小写的卷。0.5.0 在非 Windows 系统上按区分大小写的路径字符串比较仓库，因此同一目录若通过大小写不同的路径或符号链接打开，极端情况下可能被视为不同上下文。

建议：

• 始终用同一规范路径打开仓库；
• 避免同时把真实路径和符号链接路径加入多根工作区；
• 仓库路径不要使用换行或结尾空白等极端字符；
• 出现“活动仓库发生变化”时，关闭重复工作区根并重新打开真实路径。

这不会影响大多数普通 /Users/name/project 路径。

自建实例证书

公司 CA 场景需分别验证：

1. 浏览器能否打开实例；
2. git ls-remote <https-url> 能否通过；
3. TriForge 添加连接能否通过 /user 验证。

系统 Git 与 VS Code 扩展宿主可能使用不同信任来源。不要用关闭 TLS 校验的方式解决，参见 自建实例。

建议冒烟测试

在测试仓库中依次执行：

1. 打开 TriForge 三个视图；
2. 查看当前分支和状态；
3. 修改带中文文件名和空格路径的文本文件；
4. 查看 Diff，单文件暂存和取消暂存；
5. 用 Command+Enter 提交；
6. 创建、切换和删除测试分支；
7. 打开完整 Graph；
8. 添加三个平台连接；
9. 完全退出 VS Code 后重开，确认本机 Token 仍可用；
10. Fetch、Pull 和同步推送测试仓库；
11. 如果使用自建实例，验证证书与路径前缀；
12. 如果项目使用 LFS/子模块，按单独受信流程测试。

在完成上述验证前，不要让第一次 macOS Push 面向唯一副本或生产主分支。