> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Sync Project States 集合

`githubSyncProjectStates` 為每個連結到 GitHub 儲存庫的專案保存一份文件：連結的是哪個儲存庫，以及上一次同步停在哪裡。 此集合屬於 `github-sync` web 模組（`services/web/modules/github-sync`）。schema 位於 `services/web/modules/github-sync/app/models/githubSyncProjectStates.mjs`，所有存取都經過 `services/web/modules/github-sync/app/src/SyncStateManager.mjs`。

#### 欄位

| 欄位 | 型別 | 含義 | 來源 |
| - | - | - | - |
| `_id` | ObjectId | 建立時由 Mongoose 設定。 | |
| `projectId` | ObjectId | 連結的專案。必填。schema 寫了 `unique: true`，但不會建立任何索引（見「索引」）。 | `githubSyncProjectStates.mjs:8` |
| `repoFullName` | String | 以 `owner/name` 形式表示的儲存庫（GitHub 的 `full_name`）。必填。 | `githubSyncProjectStates.mjs:9` |
| `defaultBranchName` | String | 專案同步所用的分支。在連結專案時設定，之後不再變更：匯入時為匯入表單送出的分支；匯出時為新儲存庫的預設分支。預設 `null`。 | `githubSyncProjectStates.mjs:10`, `GitHubSyncHandler.mjs:175-181,235-241` |
| `mergeStatus` | String | `clean`、`conflict` 或 `diverged`。預設 `clean`。 | `githubSyncProjectStates.mjs:11` |
| `lastSyncCommit` | String | 上次同步時已同步分支上的提交 SHA。預設 `null`。 | `githubSyncProjectStates.mjs:12` |
| `lastSyncVersion` | Number | 上次同步時的專案歷史版本，在清空歷史後從 project-history 的 `GET /project/:id/version` 讀取。預設 `null`。 | `githubSyncProjectStates.mjs:13`, `services/web/modules/github-sync/app/src/HistoryManager.mjs:8-17` |
| `unmergedBranchName` | String | 發生衝突時：存放 Overleaf 變更的暫時分支，命名為 `overleaf-YYYY-MM-DD-HHMMSS`。沒有衝突時為 `null`。 | `githubSyncProjectStates.mjs:14`, `GitMerge.mjs:773-777` |
| `unmergedBranchHead` | String | 發生衝突時：該分支的 head 提交。預設 `null`。 | `githubSyncProjectStates.mjs:15` |
| `conflictVersion` | Number | 發生衝突時：記錄衝突時的專案歷史版本。預設 `null`。 | `githubSyncProjectStates.mjs:16` |
| `__v` | Number | Mongoose 版本鍵。schema 沒有關閉它。 | Mongoose 預設 |

#### 寫入方

| 程式碼 | 作用 |
| - | - |
| `SyncStateManager.mjs:9-14` (`createProjectState`) | 建立文件：將儲存庫匯入為新專案之後（`services/web/modules/github-sync/app/src/GitHubSyncHandler.mjs:175-181`），或將專案匯出到新儲存庫之後（`GitHubSyncHandler.mjs:235-241`，僅限擁有者，已連結時拒絕）。 |
| `SyncStateManager.mjs:16-21` (`updateProjectState`) | 對變更的欄位執行 `$set`。當已同步分支不再以 `lastSyncCommit` 為基礎時，`getMergeOverview` 會設定 `mergeStatus: 'diverged'`：GitHub 的 compare 回傳 `diverged` 或 `behind`（`GitHubApiClient.mjs:382-400`），或者該提交已不存在且使用者有推送權限（`GitHubSyncHandler.mjs:123,126-137`）。 同步（`services/web/modules/github-sync/app/src/GitMerge.mjs`）成功時會更新 `lastSyncCommit`/`lastSyncVersion`（例如 `:143,173,224`），以 `unmergedBranchName`、`unmergedBranchHead` 和 `conflictVersion` 記錄衝突（`:207-213`），並在衝突解決後清除它們（`:250-257`）。 |
| `SyncStateManager.mjs:23-25` (`removeProjectState`) | 在擁有者取消連結專案時（`GitHubSyncHandler.mjs:83-97`）以及已刪除專案過期時（`services/web/modules/github-sync/index.mjs:56-58`）刪除文件。 |

#### 讀取方

| 程式碼 | 作用 |
| - | - |
| `GitHubSyncHandler.mjs:39-60` (`getProjectState`) | 向編輯器提供 `mergeStatus`、`repoFullName` 和 `unmergedBranchName`。沒有文件時回傳 `need-export`，這個值從不儲存。 |
| `GitHubSyncHandler.mjs:110-143` (`getMergeOverview`) | 將 `lastSyncCommit` 和 `lastSyncVersion` 與 GitHub 及專案歷史比較，列出新的提交。 |
| `GitHubSyncHandler.mjs:200` (`exportProject`) | 拒絕匯出已連結的專案。 |
| `GitMerge.mjs:27` (`doGitMergeWithoutLock`) | 在同步開始時載入狀態。 |

#### 索引

| 名稱 | 鍵 | 選項 | 遷移 |
| - | - | - | - |
| `_id_` | `_id: 1` | | default |

Mongoose 的 `autoIndex` 已關閉（`services/web/app/src/infrastructure/Mongoose.mjs:7`），因此 schema 中 `projectId` 上的 `unique: true` 不會建立任何索引。 `tools/migrations/20190912145010_create_githubSyncProjectStates_indexes.mjs`（上游的 `project_id` 和 `owner_id`）只帶有 `saas` 標籤，不會在 CE 中執行。

#### 備註

* 同步在專案的 `gitSync` 鎖下執行（`GitMerge.mjs:17-24`）。GitLab Sync 和 Gitea Sync 使用同一把鎖，因此每個專案同一時間只執行一個同步。
* 已刪除的專案會保留其文件，直到專案過期。
* 使用者的 GitHub 權杖位於 [GitHub Sync User Credentials](https://ayakaleaf-pro.mintlify.site/zh-TW/dev/data-model/github-sync-user-credentials-collection)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.