Quick Start

快速开始

本页用一个新项目演示从本地提交到多平台推送的完整流程。第一次操作建议使用不含重要数据的测试文件夹。

1. 打开或初始化仓库

打开一个本地文件夹，然后点击活动栏中的 TriForge 图标。

如果它还不是 Git 仓库：

1. 点击“初始化 Git 仓库”；
2. 输入初始分支名，默认 main；
3. 等待“已初始化”提示。

多根工作区不会自动猜测目标文件夹，TriForge 会要求明确选择，避免把错误目录初始化成仓库。

2. 暂存文件

在“分支、更改与远程”中展开“更改”：

• 点击某个文件右侧 +：只暂存这个文件；
• 点击列表末尾“暂存全部”：暂存所有变动和未跟踪文件；
• 在“已暂存”里点击 −：只取消暂存该文件；
• 点击“取消暂存全部”：把所有文件移出暂存区，但保留文件内容。

如果同一文件既有已暂存内容又有新的未暂存内容，它可能同时出现在两个阶段。分别查看 Diff，确认下一次提交究竟包含什么。

3. 查看 Diff

点击大号“查看 Diff”按钮：

1. 选择“已暂存”条目，查看将进入下一次提交的内容；
2. 选择“待提交”条目，查看尚未暂存的内容；
3. 未跟踪文件会直接打开当前内容；
4. 二进制或已删除文件可能只显示没有可用文本补丁的说明。

建议养成“先 Diff、后提交”的习惯。

4. 创建第一次提交

1. 在“提交与同步”的输入框写提交信息；
2. 点击“提交”；
3. 暂存区为空但存在变动时，TriForge 会询问是否“暂存全部并提交”；
4. 提交成功后，节点会出现在下方提交图。

Windows/Linux 可用 Ctrl+Enter；macOS 可用 Command+Enter。提交信息必须为 1–10000 个字符。

如果 Git 提示没有配置作者，请先在受信任终端执行：

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

5. 添加托管平台连接

在“托管平台”下点击“添加连接”：

1. 选择 GitHub、GitLab 或 Gitea；
2. 输入实例首页 URL；公共实例保留默认值；
3. 输入 Personal Access Token；
4. TriForge 调用平台 /user API 验证身份；
5. 验证成功后，连接出现在列表中。

Token 权限详见 Token 权限。不要把 Token 粘贴到 Git remote URL、提交信息、Issue 或截图里。

6. 多平台同步推送

点击“推送”：

1. 默认勾选全部连接；取消勾选不希望推送的实例；
2. 确认远程仓库名称；
3. 选择缺失仓库创建为私有或公开；
4. 如果当前分支还没有 upstream，选择日后普通 Pull 的主要远程，或选择暂不设置；
5. 阅读 Hook、Git LFS 和子模块安全提示；
6. 确认安全推送。

TriForge 对每个勾选连接执行：

验证本机仓库仍未变化
  → 检查当前账号下是否有同名仓库
  → 缺失则按所选可见性创建空仓库
  → 复用或创建不冲突的 Git remote
  → 将当前分支推送到同名远程分支
  → 必要时设置唯一的 upstream

最终提示会说明成功数、失败数、新建仓库数和当前 upstream。详细行为见 多平台同步推送。

7. 从多个平台搜索项目

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

1. 输入仓库名或关键词；留空则列出近期可访问仓库；
2. TriForge 并发搜索全部连接；
3. 结果显示平台、实例、完整仓库名、可见性和说明；
4. 选择目标、父目录和本地文件夹名；
5. 克隆完成后选择在当前窗口打开或添加到工作区。

一个连接失败不会抹掉其他连接的搜索结果；失败详情写入 TriForge 输出日志。

8. 日常同步

常见顺序是：

刷新 → Fetch → 查看提交图 → Pull → 修改 → Diff → 暂存 → 提交 → 同步推送

Pull 默认是 --ff-only。如果本地和远程都新增了提交，它会停止而不是擅自生成 Merge commit；此时打开提交图，再明确选择合并策略。

下一步

• 理解 Git remote 与 upstream：界面与核心概念
• 学习安全的分支开发：分支与合并
• 撤销错误操作：回退、撤销与冲突恢复