Home

TriForge Git

TriForge Git 是一款面向 GitHub、GitLab 和 Gitea 的 VS Code Git 扩展。它把本地 Git 管理、可视化提交图、跨平台仓库搜索，以及将当前分支一次推送到多个托管平台的流程放进同一个侧边栏。

当前 Wiki 对应 0.5.0，扩展 ID 为 zhangxh-math.triforge-git。

项目由来与协作声明

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

这项声明用于如实说明项目的创作过程，并不表示 Codex、OpenAI、GitHub、GitLab 或 Gitea 对本扩展提供官方背书。

它适合谁

• 希望通过按钮、文件列表和提交图学习或使用 Git 的用户。
• 同时维护 GitHub、GitLab、Gitea 镜像仓库的个人开发者。
• 使用自建 GitLab、Gitea 或 GitHub Enterprise Server 的团队成员。
• 希望在推送前看清目标平台、仓库可见性与 upstream 的用户。

TriForge 不试图替代 Git 本身。它直接调用工作区环境中的 git，远程 API 连接只负责身份验证、仓库搜索、仓库检查与创建。

主要能力

本地 Git

• 初始化仓库并选择初始分支名。
• 查看当前分支、工作区状态、冲突、已暂存和未暂存文件。
• 单文件暂存/取消暂存、暂存全部/取消暂存全部。
• 查看未暂存与已暂存 Diff；未跟踪文件直接打开内容。
• 提交、新建/切换/删除分支、Fetch、Pull、Merge。
• Revert、Soft/Mixed/Hard Reset，以及冲突后的继续或取消。

可视化

• 侧栏紧凑提交图和完整 Git Graph。
• 显示提交父子关系、分支、Tag、HEAD、作者和时间。
• 把 GitHub、GitLab、Gitea 的远程跟踪引用标在真实提交节点上。
• 回退选择节点时，同步高亮提交图中的目标节点。

三平台协作

• 连接 GitHub、GitLab、Gitea，可同时保存多个实例或账号。
• GitLab、Gitea 支持自建实例 URL；GitHub 也可输入 Enterprise Server URL。
• 并发搜索所有已连接实例并选择仓库克隆。
• 同步推送时默认勾选所有连接，也可取消任意目标。
• 每个目标都单独检查同名仓库；缺失时按所选公开/私有可见性创建。
• 一个目标失败不会阻止已经开始的其他目标，最后显示逐项汇总。

三个最重要的概念

名称	保存在哪里	用途
托管平台连接	VS Code 扩展状态；Token 在 SecretStorage	调用平台 API，搜索、检查和创建仓库，并为 TriForge 网络命令提供临时认证
Git remote	当前仓库的 .git/config	Fetch、Pull、Push，例如 origin、github、gitlab-git
upstream	当前本地分支的 Git 配置	指定普通 Pull 默认跟踪的一个远程分支，例如 github/main

三者相关但并不等价：删除一个托管平台连接不会自动删除仓库里的 Git remote；一个本地分支也只能设置一个 upstream，但同步推送仍可把它发送到多个平台。

详见 界面与核心概念。

五分钟上手

1. 安装 VS Code 1.98 或更高版本，以及 Git 2.31 或更高版本。
2. 安装 TriForge Git，打开一个受信任的本地文件夹。
3. 点击活动栏中的 TriForge 分支图标。
4. 如果文件夹还不是仓库，执行“初始化本地仓库”。
5. 在“更改”里点击文件右侧的 +，输入提交信息并提交。
6. 在“托管平台”下添加 GitHub、GitLab 或 Gitea 连接。
7. 点击“推送”，确认平台、远程仓库名、公开/私有和主要 upstream。

完整步骤见 快速开始。

默认界面顺序

从上到下共有三个可以独立折叠和调节高度的区域：

1. 分支、更改与远程：当前分支、冲突、暂存区、工作区更改、Git remote、托管平台连接。
2. 提交与同步：提交信息框，以及提交、查看 Diff、回退、拉取、合并、推送按钮。
3. 提交图：紧凑历史与三个托管平台的远程位置。

如果升级后顺序不同，VS Code 可能保留了旧布局。运行“View: Reset View Locations（视图: 重置视图位置）”即可恢复默认顺序。

安全摘要

• Token 存入 VS Code SecretStorage，不会写入 settings.json、Git URL 或仓库配置。
• SecretStorage 中的 Token 不会通过 VS Code Settings Sync 跨设备同步。
• 带 Token 的 Git 网络阶段使用实例 URL 范围限定的临时 Authorization Header。
• 认证请求不跟随 HTTP 重定向；输出和错误在显示前进行凭据脱敏。
• 认证 Push 不运行 pre-push hook，也不递归推送子模块。
• 未受信任工作区和虚拟工作区不运行 TriForge Git。

完整威胁边界见 安全设计。

当前边界

• 同步推送只推送当前分支，不自动镜像 Tag、其他分支、Wiki、Issue、Release 或平台设置。
• 自动创建仓库默认使用当前 Token 所属用户的个人命名空间。
• Pull 使用 Fast-forward only；分叉时会安全停止，让用户查看图或明确选择合并。
• Git LFS 和子模块需要按项目认可的认证流程单独处理。
• 0.5.0 尚未同步托管平台连接元数据；换电脑后需要重新添加连接和 Token。

继续阅读

• 第一次安装：安装与升级
• 创建 Token：Token 权限
• 一次推送到三个平台：多平台同步推送
• 出现认证或分支错误：故障排查