Interface and Concepts

界面与核心概念

三个视图

1. 分支、更改与远程

这是主要状态视图，默认位于最上方。它包含：

• 仓库名称、当前分支和更改数量；
• 始终可见的当前分支选择入口；
• 可展开的完整本地/远程分支列表；
• 冲突、已暂存、未暂存三个文件阶段；
• 用于 Fetch/Pull/Push 的 Git remote；
• 用于 API 搜索/建库/认证的托管平台连接；
• 添加、修改、删除连接入口。

每个文件行会根据阶段显示可执行图标：

图标/动作	结果
+ 暂存	把该文件当前工作区变动放入暂存区
− 取消暂存	把该文件从暂存区移回工作区，内容不消失
Diff	查看该文件对应阶段的文本差异
放弃	仅放弃已跟踪文件的未暂存内容；需二次确认

未跟踪文件不会被“放弃未暂存更改”自动删除。

2. 提交与同步

默认位于中间，包括：

• 提交信息输入框；
• 大号“提交 / 查看 Diff / 回退”；
• “拉取 / 合并 / 推送”；
• 工作区是否干净、当前 upstream 和三平台连接数量；
• 打开完整 Graph 的入口；
• 冲突中断时出现的“继续 / 取消操作”。

3. 提交图

默认位于最下方，显示紧凑提交历史。顶部图例列出检测到的 GitHub、GitLab、Gitea remote；提交行标签显示它们各自远程跟踪分支所在的提交。

点击提交可打开完整 Graph，并保留该节点选中状态。

本地仓库、平台连接与远程

本地仓库

本地仓库就是包含 .git 数据的项目。暂存、提交、分支和提交图首先都发生在本机；在 Push 以前，平台看不到这些新提交。

托管平台连接

连接由以下信息组成：

• 平台种类；
• 显示名称；
• 实例首页 URL；
• 验证所得用户名；
• SecretStorage 中的 Token。

它让 TriForge 可以调用平台 API，并在精确匹配实例的 HTTPS Git 命令中临时提供认证。连接不是 Git remote。

Git remote

Git remote 是当前仓库的远程地址别名，保存在 .git/config。例如：

github      https://github.com/alice/project.git
gitlab-git  https://gitlab.example.com/alice/project.git
gitea       https://git.example.com/alice/project.git

侧栏中的 Git remote 可以：

• 在浏览器打开安全清理后的地址；
• 复制不含凭据、查询参数和 fragment 的 URL；
• 作为 Fetch、Pull、Push 的目标。

同步推送会尝试复用安全指向同一仓库的已有 remote；否则创建不冲突的名称。

远程跟踪分支

执行 Fetch 后，本机会得到只读位置记录，例如 github/main、gitlab-git/main。它们是“上次 Fetch 时远端分支在哪里”的本地记录，所以 Graph 能把三个平台标在不同节点上。

如果 Graph 显示“暂无远程引用”，先执行 Fetch；仅配置 remote 并不等于已经取得远程分支引用。

upstream

一个本地分支最多跟踪一个 upstream，例如：

main → github/main

upstream 决定普通 Pull 默认从哪里拉取，也用于显示 ahead/behind。它不会限制 TriForge 的同步推送目标：main 可以跟踪 github/main，同时推送到 GitHub、GitLab、Gitea。

Fetch、Pull 与 Push

操作	做什么	是否改动工作区
Fetch	下载远程引用、Tag，并清理已删除的远程引用	通常不改动工作区文件
Pull	Fetch 后把指定远程分支快进到当前分支	成功时可能更新文件
Push	上传本地已提交对象与分支引用	不上传未提交内容

TriForge 的 Pull 默认只允许 Fast-forward。同步推送一次处理当前分支，并不会自动推送所有分支或 Tag。

暂存区是什么

Git 有三个常见层次：

工作区文件 → 暂存区（下一次提交快照）→ 本地提交历史 → 远程平台

“暂存”不是上传，“提交”也不是上传；只有 Push 才把提交发送到远程。

同一文件可以一部分已经暂存、另一部分仍未暂存。TriForge 0.5.0 的单文件暂存按文件工作，不提供逐行/逐块暂存；需要交互式挑选代码块时，可使用 VS Code 原生源代码管理器或受信任终端中的 git add -p。

多根工作区

TriForge 根据活动编辑器和工作区上下文选择仓库。初始化等高风险操作在多根工作区中要求明确选择文件夹。长操作开始后，如果活动仓库、当前分支或 HEAD 发生变化，TriForge 会停止剩余步骤并报告，避免把结果写入错误仓库。

恢复视图布局

VS Code 会记住用户隐藏、移动或调整过的视图。若“分支、更改与远程”和“提交与同步”只能显示一个，或顺序异常：

1. 打开命令面板；
2. 运行“View: Reset View Locations（视图: 重置视图位置）”；
3. 重新点击 TriForge 图标；
4. 拖动各视图之间的分隔线分配高度；
5. 在视图标题或侧栏空白处右键，确认三个视图均已勾选。

继续阅读：日常 Git 工作流。