TriForge Git

在一个 VS Code 侧边栏里管理本地 Git，并连接 GitHub、GitLab 与 Gitea。

GitHub · Releases · Wiki · Issues

TriForge Git 是一个面向 Git 新手、同时兼顾多远程工作流的 VS Code 扩展。它把分支与文件更改、提交和同步按钮、Git Graph、跨平台仓库搜索，以及一次推送到多个托管平台的流程整合在同一个活动栏中。

• 支持 GitHub、GitLab、Gitea；GitHub Enterprise、自建 GitLab 和自建 Gitea 可以填写自定义实例 URL。
• 默认把当前分支推送到所有勾选的托管平台，也可以在推送前取消任意连接。
• 某个勾选平台缺少同名仓库时，TriForge 会先征得确认，再按所选的公开/私有可见性创建仓库。
• Token 只保存在 VS Code SecretStorage 中，不写入设置文件、Git remote URL 或仓库配置。

当前版本为 0.5.1，发布者为 zhangxh-math。

查看完整 Wiki：Wiki 提供更细的安装、Token 创建、自建实例、日常操作、故障排查和安全模型说明。

项目由来与协作声明

项目发起者 zhangxh-math 不会写代码。TriForge Git 由 zhangxh-math 提出需求、产品方向和界面反馈，并负责逐轮体验与验收；Codex 负责协助分析方案、编写与审查代码、设计测试以及整理文档。这个项目是双方经过多轮沟通、修改和验证共同完成的成果。

这项声明用于如实说明项目的创作过程，并不表示 Codex、OpenAI、GitHub、GitLab 或 Gitea 对本扩展提供官方背书。遇到问题请通过本仓库的 Issues 反馈。

目录

• 项目由来与协作声明
• 界面预览
• 功能概览
• 运行要求
• 安装
• 第一次使用
• 连接 GitHub、GitLab 与 Gitea
• Token 权限建议
• 日常使用流程
• 多平台同步推送
• Git Graph、Diff 与回退
• 安全模型
• 已知限制
• 设置
• 开发与测试
• 许可证与商标

界面预览

TriForge 活动栏默认从上到下分为三个区域：

1. 分支、更改与远程：当前分支、冲突、已暂存/未暂存文件、Git remote 和托管平台连接。
2. 提交与同步：提交信息输入框，以及较大的提交、查看 Diff、回退、拉取、合并和推送按钮。
3. 提交图：紧凑展示分支、合并轨迹，以及 GitHub、GitLab、Gitea 的远程引用位置。

当前源码包只包含扩展图标和平台品牌资源，尚未加入正式界面截图。实际界面会跟随 VS Code 的深色、浅色和高对比度主题。

功能概览

本地 Git 管理

• 初始化本地仓库并识别多根工作区中的 Git 仓库。
• 查看当前分支、创建分支、切换本地/远程分支，以及安全删除分支。
• 将单个文件或全部文件加入暂存区；取消暂存单个文件或全部文件。
• 查看已暂存、未暂存和冲突文件；对已跟踪文件放弃未暂存更改时会再次确认。
• 查看 Diff、提交已暂存内容、Fetch 全部远程、Pull 当前分支和 Push 当前分支。
• 支持标准合并、始终创建合并提交（--no-ff）、Squash 和仅 Fast-forward 四种合并方式。
• 合并、Rebase、Cherry-pick 或 Revert 发生冲突时，显示继续或取消操作入口。

可视化提交图

• 展示提交、父子关系、分支、标签、作者和时间。
• 在对应提交上标出 GitHub、GitLab、Gitea 的远程分支位置。
• GitHub 使用中性灰、GitLab 使用橙色、Gitea 使用绿色；HEAD 和 Tag 使用独立配色。
• 侧栏紧凑图与完整 Graph 联动，点击提交可以查看详情或 Diff。

三平台连接与仓库操作

• 连接 GitHub.com、GitHub Enterprise、GitLab.com、自建 GitLab、Gitea.com 和自建 Gitea。
• 在托管平台区域添加、修改或删除连接；修改实例 URL 时必须为新实例重新输入 Token。
• 同时搜索所有已连接实例中的仓库，合并结果后选择并克隆。
• 多平台同步推送默认勾选全部连接，也可以取消不需要推送的目标。
• 对每个勾选连接分别检查仓库；缺失时创建公开或私有仓库，存在时直接复用。
• 自动为新目标添加不冲突的本地 remote 名称，并让用户明确选择主要 upstream。

运行要求

项目	要求
VS Code	1.98.0 或更高版本
Git	2.31.0 或更高版本
工作区	本地、受信任、非虚拟工作区
网络	能访问所连接平台的 API 与 HTTPS Git 地址
系统	Windows；macOS Intel 与 Apple Silicon；无平台原生二进制依赖

TriForge 直接启动扩展宿主环境变量 PATH 中的 git。Git 2.31 是硬性前提，因为安全认证流程依赖从该版本开始支持的 GIT_CONFIG_COUNT、GIT_CONFIG_KEY_n 和 GIT_CONFIG_VALUE_n。旧版本可能无法应用临时认证与隔离设置，请不要使用 Git 2.30 或更早版本执行带 Token 的远程操作。

Windows

在 PowerShell 中确认：

where.exe git
git --version

如果尚未安装 Git，请先安装 Git for Windows，然后完全退出并重新打开 VS Code，让扩展宿主获得新的 PATH。

macOS

在终端中确认：

which git
git --version

如果系统提示缺少开发者命令行工具，可以运行：

xcode-select --install

安装或升级 Git 后请完全退出并重新打开 VS Code。TriForge 当前使用 VS Code 扩展宿主能找到的 git；从 Dock 启动 VS Code 时，该路径可能与终端中的路径不同。如果插件提示无法启动 Git，请从终端运行 code . 交叉检查，或确保 Git 所在目录已进入图形应用可见的 PATH。

第一次提交前还应配置 Git 身份，例如：

git config --global user.name "你的名字"
git config --global user.email "you@example.com"

安装

从 GitHub Releases 安装 VSIX

1. 在本项目的 Releases 页面下载 triforge-git-0.5.1.vsix。
2. 打开 VS Code 的扩展视图。
3. 点击扩展视图右上角的 …，选择 Install from VSIX…（从 VSIX 安装…）。
4. 选择下载的文件，安装后按提示重新加载 VS Code。

也可以使用命令行：

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

如果终端找不到 code，可以直接使用上面的图形界面方法。macOS 用户也可以在 VS Code 命令面板运行 Shell Command: Install 'code' command in PATH。

从源码运行

需要 Node.js 22、pnpm 和 Git 2.31+：

git clone https://github.com/zhangxh-math/triforge-git.git
cd triforge-git
pnpm install --frozen-lockfile
pnpm run verify

用 VS Code 打开 triforge-git 文件夹，按 F5 启动 Extension Development Host。

生成本地 VSIX：

pnpm run package

从旧发布者版本升级

发布者已从 local-lab 改为 zhangxh-math，VS Code 会把它识别为新的扩展 ID zhangxh-math.triforge-git。如果安装过旧的本地构建，请先卸载：

code --uninstall-extension local-lab.triforge-git

这可以避免两个扩展同时贡献同名命令和视图。SecretStorage 按扩展 ID 隔离，因此新版不能读取旧 ID 保存的 Token；安装新版后需要重新连接各托管平台。

第一次使用

1. 在 VS Code 中打开一个本地文件夹，并在提示时信任工作区。
2. 点击活动栏中的 TriForge Git 图标。
3. 如果文件夹还不是 Git 仓库，点击 初始化本地仓库。
4. 在“分支、更改与远程”区域确认当前分支。
5. 修改文件后，点击文件右侧的 + 将它加入暂存区；也可以点击 暂存全部。
6. 先用 查看 Diff 审阅内容，再输入提交信息并点击 提交。
7. 需要远程搜索、创建或多平台推送时，再添加 GitHub、GitLab 或 Gitea 连接。

Mac 上可以用 Command+Enter 提交，Windows/Linux 上可以用 Ctrl+Enter 提交。

“Git remote”和“托管平台连接”不是一回事： Git remote 存在当前仓库的 .git/config 中，供 Fetch/Pull/Push 使用；托管平台连接是 TriForge 保存的 API 地址、账号信息和 Token，供搜索仓库、检查仓库和创建仓库使用。

连接 GitHub、GitLab 与 Gitea

1. 打开 TriForge Git 活动栏。
2. 在“托管平台”下点击 添加连接，或在命令面板运行 TriForge Git: 连接 GitHub / GitLab / Gitea。
3. 选择平台。
4. 确认实例 URL。
5. 输入 Personal Access Token。TriForge 会调用实例的 /user API 验证身份，验证成功后才保存连接。

常用实例 URL：

平台	公共服务	自建实例示例
GitHub	https://github.com	https://github.company.example
GitLab	https://gitlab.com	https://gitlab.company.example
Gitea	https://gitea.com	https://git.company.example/gitea

请填写实例的首页 URL；TriForge 会自动补充 GitHub /api/v3、GitLab /api/v4 或 Gitea /api/v1。如果实例部署在子路径下，必须保留该路径前缀。URL 中不要包含用户名、Token、查询参数或 #fragment。

优先使用 HTTPS。选择 HTTP 实例时扩展会明确警告，因为同一网络中的其他人可能看到 Token 和 Git 内容。使用公司私有 CA 或自签名证书的实例时，VS Code/Node 与系统 Git 可能采用不同的证书信任来源；请按组织规范安装 CA，不要关闭 TLS 校验。

连接建立后可以在托管平台区域使用：

• 添加：连接另一个账号或实例。
• 修改：修改显示名称、实例 URL 或 Token。实例 URL 一旦变化，旧 Token 不会被发送到新地址。
• 删除：删除连接元数据，并从当前设备的 SecretStorage 中删除对应 Token。

Token 权限建议

请遵循最小权限原则：只授予本工作流需要的仓库读取、写入和创建权限，并设置合理的过期时间。组织、群组或企业策略可能进一步限制 Token。

GitHub

• 使用经典 Personal Access Token 时，完整的私有仓库搜索、创建和推送流程通常需要 repo。
• 只处理公共仓库时可以按实际操作缩小权限；如果使用 Fine-grained PAT，需要让它覆盖目标仓库，并具备读取元数据、写入仓库内容和创建仓库所需的权限。
• 组织启用了 SSO 时，可能还要单独授权该 Token 访问组织。

GitLab

• 建议使用带 api scope 的 Personal Access Token，因为插件既执行 Git 仓库读写，也会通过 API 搜索、检查和创建项目。
• Token 对目标命名空间仍需有足够的项目创建和仓库写入权限。

Gitea

• Token 需要仓库读取、写入和创建权限。
• 不同 Gitea 版本和实例策略的权限名称可能不同；如果实例支持细粒度 scope，请只授权 Repository 相关读写权限。

不要把 Token：

• 写入 Git remote URL；
• 写入 .vscode/settings.json、脚本或环境示例文件；
• 提交到仓库；
• 发送到 Issue、日志或截图中。

日常使用流程

修改、审阅与提交

1. 在“更改”中找到文件。
2. 点击文件右侧 + 暂存单个文件，或点击列表末尾的 暂存全部。
3. 已暂存文件右侧的 − 可以取消暂存，不会删除工作区内容。
4. 点击文件的 Diff 图标，或点击大号 查看 Diff 并选择文件。
5. 输入提交信息并点击 提交。

已跟踪文件可以执行“放弃未暂存更改”，操作前会二次确认；未跟踪文件不会被该命令自动删除。

拉取与合并

• 拉取遵循当前分支的 upstream，默认只接受 Fast-forward；分支已经分叉时会安全停止。
• 当前分支没有 upstream 时，TriForge 会让你选择 Git remote。
• 合并会先选择来源分支，再选择标准合并、--no-ff、Squash 或 --ff-only。
• 工作区存在未提交更改时不会开始合并。
• 出现冲突时，解决文件并暂存，然后使用“继续”；也可以取消整个操作。

搜索并克隆

运行 TriForge Git: 搜索三个平台并克隆：

1. 输入仓库名称或关键词；留空会列出账号可访问的近期仓库。
2. TriForge 遍历所有已连接实例，最多同时发出 3 个搜索任务，并分页读取结果。
3. 从合并后的结果中选择仓库和本地父目录。
4. 输入本地文件夹名称并开始克隆。

GitHub、GitLab 和 Gitea 的搜索语义并不完全相同。某个连接失败时，其他连接仍会继续搜索，错误详情可在 TriForge Git 输出日志中查看。

多平台同步推送

运行 TriForge Git: 多平台同步推送，或点击大号 推送：

1. 如果工作区有未提交更改，选择先提交或仅推送已经存在的提交。
2. 在勾选框中选择目标。默认选中所有已连接实例，可以取消任意 GitHub、GitLab 或 Gitea 连接。
3. 输入远程仓库名称。默认优先从已有 remote 推断，没有 remote 时使用当前文件夹名。
4. 选择缺失仓库创建为 私有还是公开。
5. 当前分支没有 upstream 时，选择以后普通 Pull 使用的主要远程，也可以暂不设置。
6. 确认安全推送提示。
7. TriForge 对每个勾选连接逐一检查：同名仓库不存在就创建，存在就复用，然后添加不会冲突的 local remote 并推送当前分支。
8. 完成后查看每个连接的成功、失败和创建结果。单个连接失败不会阻止其他目标继续执行。

推送只发送已经提交的内容。当前版本每次只同步当前分支，不是完整镜像工具。

为防止不受信任的仓库 Hook 读取认证环境，TriForge 发起的认证 Push 使用 --no-verify，不会运行 pre-push hook，也不会递归推送子模块。依赖 pre-push 检查、Git LFS 或子模块自动推送的项目，请先按项目认可的受信任流程完成相应检查和上传。

Git Graph、Diff 与回退

查看 Graph

侧栏“提交图”显示近期提交和三平台远程位置。点击提交可以打开完整 Graph；完整视图提供提交详情、父节点、引用、创建分支、复制 Hash 和 Diff 等操作。大型仓库会受到 triforge.graph.maxCommits 限制。

如果升级后视图顺序不正确，请在命令面板运行 View: Reset View Locations（视图: 重置视图位置）。VS Code 会记住用户曾经拖动或隐藏过的视图位置，扩展升级不会强制覆盖这些个性化布局。

查看 Diff

大号 查看 Diff 会列出已暂存和未暂存文件，同一个文件的两个阶段会分开显示：

• 已跟踪文本文件显示统一差异；
• 未跟踪文件打开当前内容；
• 二进制文件提示无法显示文本补丁；
• 文件行上的 Diff 图标可以直接打开对应阶段的差异。

回退与安全撤销

点击 回退 后分两步：

1. 选择提交节点；移动选择时，提交图会滚动并高亮对应节点。
2. 选择处理方式。

方式	结果	适用场景
Revert（推荐）	创建反向提交，保留原历史	已经 Push 或正在协作
Mixed Reset	分支移到目标，后续内容成为未暂存更改	想重新整理改动
Soft Reset	分支移到目标，后续内容留在暂存区	想立即重新提交
Hard Reset	分支、暂存区和已跟踪文件恢复到目标	明确要永久丢弃内容

Hard Reset 会再次显示不可恢复警告。Reset 会改写当前本地分支历史；相关提交已经推送时应优先选择 Revert。取消任意选择步骤都不会执行 Git 命令。

安全模型

• Token 存入 VS Code SecretStorage，不写入 settings.json、Git URL 或永久 Git 配置。
• 连接 URL、平台、显示名称和用户名属于非敏感元数据；当前版本尚未通过 VS Code Settings Sync 同步连接列表。
• SecretStorage 中的 Token 不跨设备同步。换电脑或更换扩展 ID 后必须重新输入 Token。
• API 错误、Git 参数和 Git 输出在进入日志与 UI 前进行 Token、Authorization Header 和 URL 凭据脱敏。
• Git 子进程通过参数数组启动，不经过 shell；具体文件路径启用字面量 pathspec，避免 *、?、[ 等字符被当成通配符。
• Token 只用于与连接实例 origin/路径严格匹配的 HTTP(S) remote；SSH、SCP 和自定义 remote helper 不会收到 PAT。
• 带 Token 的 API 请求禁止 HTTP 重定向并限制响应大小；平台返回的仓库和 clone URL 会校验实例、命名空间、名称和协议。
• 认证网络阶段使用工作区外的一次性空 Hook 目录，禁用凭据交互、Git Credential Manager、自动维护和子模块递归。
• Pull 与 Clone 将带 Token 的网络阶段和无 Token 的本地合并/Checkout 分开，减少仓库 Hook 或过滤器接触凭据的机会。
• 自动创建远程仓库、Hard Reset、放弃文件更改、强制删除未合并分支等操作都会要求明确确认。
• 扩展不支持未受信任工作区，也不在虚拟工作区运行 Git 命令。

TriForge 只控制自己启动的 Git 命令。VS Code 内置源代码管理器、终端或其他扩展拥有各自的认证流程；从那些入口 Push 时，Git Credential Manager 或平台登录窗口仍可能出现。

已知限制

• 当前版本只同步当前分支，不自动镜像 Tags、其他分支、Git LFS 配置、子模块或服务端设置。
• 自动创建仓库默认位于当前登录用户的个人命名空间；组织/群组命名空间不是当前 UI 的默认创建目标。
• 认证 Push 不运行 pre-push hook，也不递归推送子模块。
• 使用 Token 克隆时，认证下载与本地 Checkout 分阶段执行；Git LFS 对象和子模块需要随后按项目认可的认证流程获取。
• Pull 默认使用 --ff-only，分支分叉时需要查看 Graph 或显式选择合并方式。
• Token 和连接列表目前不会随 VS Code Settings Sync 自动迁移到另一台设备。
• 当前没有 triforge.git.path 设置；插件使用扩展宿主 PATH 中找到的 git。
• 自建实例的私有 CA 需要同时满足 VS Code/Node API 请求和系统 Git 的证书信任要求。
• Graph 按配置的最大提交数截断，不会一次加载无限历史。

设置

在 VS Code 设置中搜索 TriForge Git：

设置	默认值	说明
triforge.defaultVisibility	private	自动创建远程仓库时默认使用私有或公开可见性
triforge.graph.maxCommits	300	Graph 一次最多加载的提交数，范围 20–2000
triforge.search.maxRepositoriesPerConnection	100	每个连接最多返回的搜索结果数，范围 10–100
triforge.confirmBeforeForceDeleteBranch	true	强制删除未合并分支前是否再次确认

开发与测试

项目结构：

src/
  git/                 # 本地 Git 命令、解析与临时认证隔离
  remote/              # GitHub / GitLab / Gitea API 适配器
  ui/                  # 仓库树、操作区与 Git Graph Webview
  connectionStore.ts   # 连接元数据与 SecretStorage 凭据
  commands.ts          # VS Code 命令和用户交互流程
  extension.ts         # 扩展激活与视图注册
test/                  # 核心、Git、远程 API、UI 和打包冒烟测试

常用命令：

pnpm install --frozen-lockfile
pnpm run check          # TypeScript 类型检查
pnpm run test           # 编译并运行测试
pnpm run compile        # esbuild 生成 dist/extension.js
pnpm run test:bundle    # 打包产物加载冒烟检查
pnpm run verify         # 依次执行以上验证
pnpm run package        # 验证并生成 VSIX

在 GitHub Issues 提交问题时请说明：

• VS Code 版本；
• 操作系统与 CPU 架构；
• git --version 输出；
• 平台类型与是否为自建实例；
• 可复现步骤；
• 已脱敏的 TriForge Git 输出日志。

请不要在 Issue 中粘贴 Token、Authorization Header、带凭据的 URL 或公司内部敏感地址。

Wiki

TriForge Git Wiki 是完整用户手册，建议从 Wiki 首页开始。计划/已提供的主题包括：

• 安装与升级；
• Windows 与 macOS 环境检查；
• GitHub、GitLab、Gitea Token 创建与权限；
• 自建实例和证书；
• 暂存、Diff、提交、分支、合并与回退；
• 聚合搜索、克隆与多平台同步推送；
• Git Graph 图例；
• SecretStorage 与安全模型；
• 常见错误和故障排查；
• 开发、测试与发布。

许可证与商标

TriForge Git 采用 MIT License。

TriForge Git 是独立项目，与 GitLab Inc. 或 Gitea 项目不存在赞助、背书或从属关系。GitLab 与 Gitea 品牌资源仅用于标识兼容平台，来源、许可证和商标说明见 THIRD_PARTY_NOTICES.md。GitHub、GitLab、Gitea 及其标志属于各自权利人。