Search and Clone

搜索与克隆

“搜索三个平台并克隆”会查询当前保存的所有连接，名称中的“三个平台”表示支持 GitHub、GitLab、Gitea，并不限制只能有三个连接。

开始搜索

入口：

• 命令面板 → “TriForge Git: 搜索三个平台并克隆”；
• “分支、更改与远程”视图标题中的搜索入口；
• 当前仓库没有 remote 时，从 Pull 提示进入。

没有连接时，TriForge 会先建议添加至少一个平台。

查询语义

• 输入名称或关键词：各平台按自己的 API 语义搜索；
• 留空：列出当前账号可访问的近期仓库；
• GitHub、GitLab、Gitea 的排序与匹配语义不同，合并后的列表不代表跨平台统一相关度。

TriForge 最多并行处理三个连接；每个连接分页读取并去重。单连接结果上限由 triforge.search.maxRepositoriesPerConnection 控制，0.5.0 设置范围为 10–100，默认 100。

结果中能看到什么

• 平台与实例主机名；
• owner/repository 完整名称；
• 公开、私有或内部可见性；
• 是否已归档；
• 仓库说明。

某个连接失败时，其他连接的有效结果仍会显示，选择框标题会指出失败连接数量；具体原因在 TriForge 输出日志中。

克隆步骤

1. 选择远程仓库。
2. 选择本地父目录。
3. 确认本地文件夹名；目标路径必须尚不存在。
4. 等待可取消的克隆操作。
5. 完成后选择“在当前窗口打开”或“添加到工作区”。

TriForge 使用平台 API 返回并经过严格校验的 HTTP(S) clone URL。返回 URL 必须匹配所连接实例、目标 namespace 和仓库名；危险协议、外域地址、嵌入凭据、查询参数或 fragment 会被拒绝。

LFS 与子模块

认证克隆分成两个阶段：

1. 带临时 PAT 的安全网络下载；
2. 移除 PAT 后进行本地 Checkout。

认证克隆不会递归克隆子模块，也不会让工作区 Hook/过滤器在持有 PAT 的进程环境中执行。因此：

• Git LFS 大对象可能没有自动下载；
• 子模块不会自动初始化；
• 需要按项目说明，用组织认可的凭据流程继续。

常见后续命令示例仅供理解，执行前请确认项目安全策略：

git lfs pull
git submodule update --init --recursive

为什么不能克隆到已存在目录

TriForge 要求目标路径不存在，避免：

• 覆盖已有文件；
• 把失败的半成品仓库和旧内容混合；
• 空目录与非空目录的 Git 行为差异；
• 用户误选工作区根目录。

失败后先检查目标目录是否已被创建。认证克隆会尽量清理可安全确认的空失败目录，但不要假设所有中断都能自动删除内容。

取消行为

点击进度通知中的取消会中断 Git 子进程。网络端可能已经收到部分对象，但分支不会被 TriForge 视为成功完成。若目录仍存在，检查后手动决定保留、改名或删除；不要直接把未知半成品当成完整克隆。

搜索不到仓库

依次检查：

1. Token 是否有私有仓库读取权限；
2. GitHub fine-grained Token 是否包含该仓库；
3. 仓库是否属于另一个组织/群组而 Token 无权读取；
4. 自建实例 URL 是否正确保留路径前缀；
5. 是否因分页上限没有进入前 100 条；
6. 平台搜索 API 是否暂时限流；
7. 查看 TriForge 输出是否有某连接失败。

另见 Token 权限 和 故障排查。