# GitHub 同步

用设备码或令牌连接 GitHub，把项目发布为新仓库或现有仓库，在电脑之间推送和拉取，以及你的令牌如何受到保护。

GitHub 同步是可选的异地备份和多台电脑之间的工作交接，建立在每个项目本来就是的[真正的 Git 仓库](/docs/git-history/)之上。没有 GitHub 也可以进行本地提交。连接时，也不会有 Oleafly 账号的参与：只用你的 GitHub 账号。

## 连接你的账号

设置，**集成**，**GitHub**，然后任选一种方式：

- **连接 GitHub**（推荐）：设备码流程。Oleafly 会显示一个短代码，浏览器会打开 `github.com/login/device`（代码旁有 **复制** 按钮），你批准后，应用会在几秒内检测到。这个连接只请求 `repo` 和 `read:user` 权限范围。
- **个人访问令牌**：展开“高级：使用个人访问令牌”，如果你更愿意自己生成凭据，就粘贴一个 PAT。

连接后，你的头像和用户名会显示在设置中，以及顶部工具栏的 GitHub 菜单里。**断开连接** 会清除令牌。

### 你的令牌如何受到保护

令牌保存在一个用 AES-256-GCM 加密、仅限所有者访问的本地文件中，从不交给应用的 UI 层；界面只会知道“已连接为 @you”。Git 需要认证时，令牌通过内存中的凭据助手注入，所以它不会出现在命令行、`.git/config` 或 shell 历史记录里。旧版本曾把令牌嵌入远程 URL，启动时会自动清理。

## 发布项目

在源代码管理面板中，点击 **发布到 GitHub**：

- **新建仓库**：选一个名称（根据项目预填），决定是否保持勾选 **私有**（推荐），然后点 **创建并推送**。Oleafly 会创建仓库，提交项目的文件，配置好 `origin`，并推送。
- **关联现有仓库**：从可搜索的仓库列表中选择（私有仓库带有锁图标），然后点 **关联并推送**。

发布之后，工具栏的 GitHub 菜单提供 **在 GitHub 中打开** 和 **复制仓库链接**。

### 看起来像密钥的文件留在本地

发布绝不会提交通常保存密钥或密码的文件，例如 `.env`、`*.pem`、SSH 私钥或 `credentials.json`。它们留在项目文件夹中，保持未暂存，对话框会点出它们的名字。如果仍想发布其中某个文件，请在源代码管理中自己暂存并提交。`.env.example` 之类的模板、公钥和 Keynote 的 `.key` 文件照常发布。

推送会上传完整的历史记录。如果曾经提交过使用这些名称的文件，Oleafly 会列出它，并等待你选择 **取消** 或 **仍然发布**，然后才会在 GitHub 上创建任何内容。

## 日常同步

源代码管理面板中的 **推送** 和 **拉取** 按钮就如其名，针对当前分支的 `origin` 操作。**获取** 和 **同步** 在 **更多源码管理操作** 菜单中，**提交并推送** 和 **提交并同步** 在 **提交** 旁边的菜单中。分支标签旁边的 **领先/落后** 指示器（↑ ↓）会告诉你什么时候有内容要推送或拉取。

### 两台电脑

1. 在电脑 A 上：发布项目，工作，**推送**。
2. 在电脑 B 上：连接同一个 GitHub 账号，然后选择 **导入项目 → GitHub** 并选中该仓库。参见[导入指南](/docs/import-project/#import-from-github)。此后，**拉取**，工作，**推送**。
3. 回到 A：开始之前先 **拉取**。指示器会提醒你。

封面颜色、主文档的选择和历史记录都会随之转移，因为它们就存放在项目文件夹本身里。

## 改变主意

设置好远程仓库后，**更多源码管理操作** 菜单里会多出两项：

- **更改仓库** 重新打开发布对话框，把 `origin` 指向别处。
- **取消链接** 移除远程仓库；本地项目及其历史记录不受影响。

## 冲突与分支

如果拉取遇到合并冲突，源代码管理会列出有冲突的文件。对每个文件选择 **使用当前版本** 或 **使用传入版本**，或者编辑文件后选择 **标记为已解决**，然后选择 **完成合并**。**中止合并** 会把文件恢复原样。推送和拉取针对你当前检出的分支进行，面板顶部的分支菜单可以切换或创建分支。参见 [Git 与源代码管理](/docs/git-history/#branches-and-stashes)。

## 明确说明的限制

Oleafly 对 HTTPS 远程仓库进行认证。发布时会替你正确地设置好。

## 如果出现失败

- “No remote 'origin'”：先发布；推送和拉取需要远程仓库。
- 因为远程仓库有新的提交而导致推送被拒绝：先拉取，再推送。
- “No GitHub token set”：在设置、集成、GitHub 中连接。

更多内容见[常见问题](/docs/faq/#history-and-collaboration)。
