# 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)。
