> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/zh-tw/zhi-shi-ku/044-github-synchronization.md). # GitHub 同步 **GitHub 同步** 是 [付費功能](/latex/zh-tw/zhi-shi-ku/120-overleaf-premium-features.md)。Overleaf 進階功能適用於以下參與者 [Overleaf Commons](https://www.overleaf.com/for/universities)，群組成員 [訂閱方案](https://www.overleaf.com/for/groups)，以及個人 [訂閱方案](https://www.overleaf.com/user/subscription/plans). 摘要 GitHub 同步功能可讓您將 Overleaf 專案直接連結到一個 GitHub 儲存庫，作為您 Overleaf 專案的遠端儲存庫，並提供在兩者之間推送與拉取變更的方法。GitHub 同步只能使用於 [GitHub.com](https://www.github.com) ，且不能用來連接其他 GitHub 企業版安裝。 您可以透過兩種方式將 Overleaf 專案與 GitHub 儲存庫同步：從既有的 GitHub 儲存庫建立新的 Overleaf 專案，或是從既有的 Overleaf 專案建立新的 GitHub 儲存庫。無法將既有的 Overleaf 專案與既有的 Github 儲存庫同步。 * 透過將您的 GitHub 帳戶連結到您的 Overleaf 帳戶即可啟用 GitHub 同步 * 可從既有的 GitHub 儲存庫建立新專案 * 可在 GitHub 中根據既有的 Overleaf 專案建立儲存庫 * 已連結的專案與儲存庫會使用 **GitHub** 選項在專案的 **選單** ### 將您的 Overleaf 帳戶連結到您的 GitHub 帳戶 若要使用 GitHub 同步功能，您必須將您的 Overleaf 帳戶連結到您的 Github 帳戶。您可以在您的 Overleaf [帳戶設定](https://www.overleaf.com/user/settings)中進行此操作。請注意，Overleaf 能否連接到與您的帳戶相關聯的某些儲存庫或組織，可能取決於 GitHub 中所設定的權限設定。 ### 從 GitHub 儲存庫建立新的 Overleaf 專案 從「新專案」選單中，您可以選擇 GitHub 選項。這會顯示一份可透過您的 GitHub 帳戶讓 Overleaf 看見的儲存庫清單，並依據您的 GitHub 權限設定而定。 ![建立新 github.png](/files/2fb7a52ac3aeb23d182df28653366f4796acb842) 從既有的 GitHub 儲存庫建立新的 Overleaf 專案時，有一些事項需要注意。 * Overleaf 專案有大小限制，這可能會阻止較大的 GitHub 儲存庫被用來建立專案。請參閱 [此頁面](/latex/zh-tw/zhi-shi-ku/119-overleaf-plan-limits.md) 以了解 Overleaf 專案中檔案大小與數量限制的概覽。 * Overleaf 專案不支援 Git 子模組或 Git LFS。 ### 從 Overleaf 專案建立新的 GitHub 儲存庫 從 Overleaf 專案選單中，您可以將 GitHub 選為同步選項之一。這會顯示一個對話框，讓您提供一個新的 GitHub 儲存庫名稱，以便與您的 Overleaf 專案同步。 ![專案選單 github.png](/files/f8870b027d257a76c9bcf07267d59aee8d0f3684) ### 與 GitHub 同步 GitHub 與 Overleaf 之間的同步不會自動發生；同步選項會在點擊 **GitHub** 選項在專案的 **選單**時顯示。此時，GitHub 視窗會回報是否有新的變更可從 GitHub 拉取。您也一定會看到將變更推送到 GitHub 的選項（注意：即使 Overleaf 與 GitHub 已是最新狀態，仍會顯示此選項）。 ![GitHub 視窗畫面](/files/6aed7fbd4e1bbf861bd71d5d001c184f8bf1395e) 當您點擊「將 Overleaf 變更推送到 GitHub」按鈕時，會建立 GitHub 提交。此時可提供一則選用的提交訊息。 * 來自 GitHub 的 Overleaf 歷史變更會顯示為由 anonymous 所撰寫。 * 來自 Overleaf 的 GitHub 歷史變更會顯示為由已連結的 GitHub 帳戶擁有者所撰寫。 ### 解決合併衝突 當 Overleaf 與 Github 都有變更時，Git 有時無法判斷如何自動合併它們。例如，如果您的協作者在 Overleaf 中修改了一行，而您也修改了 Github 儲存庫中的同一行，Overleaf 可能無法決定要保留哪個版本。 當這種情況發生時，我們不會合併到您的主分支，而是會將一個新分支推送到您的儲存庫。這個分支會有一個描述性的名稱（包含分支建立的日期與時間），並包含 Overleaf 中文件的版本。當您嘗試與 GitHub 同步時，系統會顯示一則訊息，指出需要解決合併衝突。 ![GitHub 合併衝突對話框](/files/06ad0879a8f4caaabba7f956ebf547af13797704) 若要恢復同步，您需要將 Overleaf 分支合併到您的主（預設）分支。您可以在電腦上拉取兩個分支，使用 git 或其他工具進行合併，然後再將結果推送回 Github。或者，您也可以直接在 Github 上，從 Overleaf 分支建立拉取請求，並使用其衝突解決功能來完成合併。這兩種方式都在 [Github 文件](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts). ### 存取您 GitHub 組織中的儲存庫 您可以將 Overleaf 專案與連結到您已連結的 GitHub 帳戶的儲存庫同步，也可以與您所屬的 GitHub 組織中的專案同步。若要與您所屬的 GitHub 組織中的儲存庫同步，這些組織必須授權讓 Overleaf OAuth 應用程式存取。 * 如果您是組織成員，您可以依照下列步驟 [這裡](https://help.github.com/articles/requesting-organization-approval-for-oauth-apps/) 來請求讓 Overleaf 應用程式存取您的組織。 * 如果您是組織擁有者，您可以依照下列步驟 [這裡](https://help.github.com/articles/approving-oauth-apps-for-your-organization/) 來核准該組織的 Overleaf 應用程式。 ### GitHub 同步檔案限制 Overleaf 專案受單一大小限制，以及專案內檔案總數限制，如 [這裡](/latex/zh-tw/zhi-shi-ku/119-overleaf-plan-limits.md)所述。雖然 Git 本身可處理單一提交變更數千個檔案，但 Overleaf 的 GitHub 同步功能所使用的 GitHub API 也會限制可推送或拉取的檔案數量。若使用 GitHub 同步，建議將單次提交中的檔案數量限制在 100 個以下，並將整體專案大小控制在 100 MB 以下。超過這些大小的專案也許仍可運作，但我們建議維持在這些限制內，以避免潛在的同步問題。 ### 將專案從儲存庫中解除連結 雖然可以從單一既有的 GitHub 儲存庫建立多個專案， **但無法變更與某個專案相關聯的儲存庫**。一旦專案連結到某個儲存庫，就無法解除連結並用來建立新的儲存庫。如果您需要從特定專案建立新的儲存庫，您必須先製作該專案的新副本，然後再從該副本建立新儲存庫。 ### 已知限制 **分支**：Overleaf Git 系統不支援分支。 **符號連結**：Overleaf Git 系統不支援符號連結（symlink）。符號連結可以被推送到 Overleaf 專案中，但會被轉換為一般檔案，並會在下次專案被拉取時覆蓋本機的符號連結。 **檔案權限**：Overleaf Git 系統不會保留可執行權限。當使用 GitHub 同步時，如果 GitHub 中任何具有可執行位元的檔案同步到 Overleaf，Overleaf 會自動提交一次以重設檔案權限。 **Git LFS**：Overleaf 專案不支援 Git Large File Storage。 **Git 子模組**：Overleaf 專案可以作為其他儲存庫中的 Git 子模組，但不能包含其他 Git 子模組。若要參照其他專案中的檔案，建議使用「從其他專案新增」功能。 **追蹤變更與註解**：不幸的是，從 GitHub 拉取到 Overleaf 可能會導致追蹤變更和註解遺失或被移位；因此，我們不建議在 GitHub 進行主動工作時，同時使用追蹤變更和／或註解。 **直接與 GitHub Enterprise 或 GitLab 同步：** Overleaf 使用的 GitHub API 只能連接到託管於 github.com 的儲存庫。您可以透過 [Overleaf Git 整合](/latex/zh-tw/zhi-shi-ku/040-git-integration.md) 功能。 **將現有專案連結到現有儲存庫**：無法將既有的 Overleaf 專案與既有的 Github 儲存庫同步。 **推送到 GitHub 的作者資訊**：Overleaf 唯一知道的 Github 使用者，是其 GitHub 帳戶已連結到 Overleaf 帳戶、且擁有該專案的使用者。所有提交都透過 GitHub API 建立，而該 API 會明確使用該使用者的身分來建立提交。因此，所有提交在 GitHub Git 歷史中都會顯示為來自已連結的使用者。在 Overleaf 的歷史中，變更會顯示為「Anonymous (via GitHub)」。 **Git 歷史與 Overleaf 歷史：** Overleaf 端的變更與 GitHub 提交之間沒有一對一的對應關係。Overleaf 端可以由多位使用者進行變更，但當同步被觸發時，這些變更會被彙整成由連結到 GitHub 的使用者所提交的一個提交。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/zh-tw/zhi-shi-ku/044-github-synchronization.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.