Branches and Merges

分支与合并

为什么使用分支

分支是指向某个提交的可移动名称。建议每个独立功能或修复使用单独分支，在确认后再合并到 main：

main ───────●────────────●
             \          /
feature/x     ●──●──────●

新建分支

入口：

• 点击当前分支附近的新建分支按钮；
• 展开完整分支列表并选择“新建”；
• 命令面板运行“TriForge Git: 新建分支”。

输入例如：

feature/search-cache
fix/gitlab-auth
docs/wiki

TriForge 从当前 HEAD 创建分支并立即切换。Git 会验证名称；不能包含空格、连续的 .. 或其他非法引用字符。

初始仓库还没有提交时，也可以创建/使用初始分支，但正式协作前应先创建首次提交。

切换本地分支

点击顶部当前分支，或从完整列表选择目标。切换前 Git 自己会保护会被覆盖的未提交内容；更稳妥的做法仍是先提交或整理工作区。

TriForge 会在用户选择后重新确认分支没有被删除、重建或推进，避免长时间停留在选择框期间切到另一个状态的分支。

切换远程分支

选择 origin/feature-x 之类的远程跟踪分支时，TriForge 会创建同名本地跟踪分支并切换。

若同名本地分支已存在但跟踪另一个 remote，会让你：

• 切换现有本地分支；或
• 输入另一个本地分支名，新建对正确远程的跟踪分支。

不会静默改写已有分支的 upstream。

删除分支

只支持删除非当前的本地分支。流程：

1. 选择分支；
2. 模态确认普通删除；
3. Git 检查分支是否已完全合并；
4. 若未合并，按设置决定是否再次确认强制删除。

设置 triforge.confirmBeforeForceDeleteBranch 默认开启。关闭它会减少二次提示，但并不会让强制删除变得安全。

删除本地分支不会自动删除远端分支。

合并前条件

点击“合并”前：

• 当前 HEAD 必须是有提交的本地分支；
• 工作区和暂存区必须干净；
• 不能选择当前分支本身；
• Fetch 远程后才能合并最新远程跟踪分支。

界面标题会明确写成：

来源分支 → 当前分支

也就是“把来源分支合并进当前分支”。

四种合并方式

标准合并

可快进时直接移动当前分支；无法快进时创建 Merge commit。适合不强制保留每个功能分支节点的常规工作流。

始终创建合并提交（--no-ff）

即使可以快进也创建 Merge commit，提交图上能清晰看见功能分支被合入。缺点是历史节点更多。

Squash 合并

把来源分支的最终改动放进当前分支暂存区，但不自动提交，也不保留来源分支的逐个提交父子关系。

选择后应：

1. 查看已暂存 Diff；
2. 必要时调整文件；
3. 写一个总结性提交信息；
4. 手动提交。

仅允许 Fast-forward（--ff-only）

只有当前分支是来源分支祖先时才成功；否则安全停止，不生成 Merge commit。适合要求线性历史的流程。

合并冲突

发生冲突时：

1. TriForge 保留 Git 的冲突状态；
2. 在“冲突”分组或 VS Code 原生源代码管理器打开文件；
3. 逐个处理冲突标记；
4. 暂存所有已经解决的文件；
5. 点击“继续”；
6. 如果不想继续，点击“取消操作”恢复合并开始前状态。

不要在冲突未解决时删除 .git/MERGE_HEAD 等内部文件。让 Git 的 continue/abort 命令完成状态管理。

Pull 分叉后的处理

Pull 使用 --ff-only。当本地和远程分叉：

1. 先打开 Graph，看清两条线；
2. 确认本地提交是否应保留；
3. 若要保留两边，点击“选择合并方式”并选择远程跟踪分支；
4. 若团队要求 Rebase，0.5.0 没有直接 Rebase 按钮，应在受信任终端或其他获准工具中完成，之后刷新 TriForge。

多远程分支

Graph 可能显示：

GH github/main
GL gitlab-git/main
GT gitea/main

它们可以位于不同节点。先 Fetch 全部 remote，再决定把哪个远程分支合并进本地。同步推送不会先自动合并三个远端的独有历史；若某个平台已有不同历史，Push 会按 Git 规则失败，需人工处理。

另见 Diff 与提交图。