> 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/040-git-integration.md). # Git 整合 **Overleaf 的 Git 整合** 是 [付費功能](/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)。Git 整合可在 Overleaf Cloud 和 Overleaf Server Pro（4.0 版及更新版本）上使用。 ### 什麼是 Overleaf Git 整合？ Overleaf 的 Git 整合可讓您從 Overleaf 專案取得一個 Git URL，並將它視為遠端 Git 儲存庫（repo）。您可以將專案複製到本機 Git 儲存庫，並在本機處理專案，從本機電腦將變更推送到專案，以及將 Overleaf 線上編輯器中產生的更新提取到本機儲存庫。 這讓您在不方便線上工作的時候，也能在本機處理專案；也可以在處理 Overleaf 專案時改用您偏好的其他本機編輯器，或輕鬆將其他本機軟體的輸出加入您的 Overleaf 專案。 您可以從專案 Overleaf 選單中的 Git 選項取得該專案的 Git URL 與 clone 指令。 ![專案選單 git.png](/files/b2c1420747700464f3c56b685ee91952f45f3569) ### 使用 Git 整合時如何驗證 當您對遠端 Overleaf 專案執行 Git 操作，例如 clone、pull 或 push 時，系統會要求您進行驗證。 若要從 Git 存取您的 Overleaf 專案，必須使用 Overleaf 基於權杖的驗證。逐步說明請參閱： [基於權杖的驗證](/latex/zh-tw/zhi-shi-ku/042-git-integration-authentication-tokens.md). ### 將專案複製為本機儲存庫 從 [**選單**](/latex/zh-tw/zhi-shi-ku/148-using-the-overleaf-project-menu.md) 在您的專案中，您可以從同步選項選擇 Git。這會開啟一個對話框，顯示 `git clone` 建立本機儲存庫時要使用的指令。 ![專案選單 git.png](/files/b2c1420747700464f3c56b685ee91952f45f3569) 或者，您也可以從專案 URL（在專案中時瀏覽器網址列中的 URL）找到 Git URL。 #### Overleaf Cloud 如果您使用的是 Overleaf Cloud，而且您的 Overleaf 專案 URL 看起來像這樣： ``` https://www.overleaf.com/project/1234567 ``` 那麼用來複製專案的 Git URL 會是 ``` https://git.overleaf.com/1234567 ``` 而將專案複製到本機 Git 儲存庫所使用的指令會是： ``` git clone https://git.overleaf.com/1234567 ``` **注意**：系統可能會提示您輸入使用者名稱和密碼。請參閱 [Git 整合密碼驗證](/latex/zh-tw/zhi-shi-ku/043-git-integration-password-based-authentication.md) #### Overleaf Server Pro（4.0 版或更新版本） **注意**：Server Pro 預設未啟用 Git-bridge 整合。請參閱我們的 [Git 整合](https://github.com/overleaf/overleaf/wiki/Git-Integration) 指南，了解如何啟用它。 如果您使用的是 Overleaf Server Pro，且您的專案 URL 看起來像這樣： ``` https:///project/1234567 ``` 那麼用來複製專案的 Git URL 會是： ``` https://git@/git/1234567 ``` 而使用 Git 命令列將專案複製到本機 Git 儲存庫所使用的指令會是： ``` git clone git@/git/1234567 ``` **注意**：您可能會被要求輸入密碼。請參閱： [Git 整合驗證權杖](/latex/zh-tw/zhi-shi-ku/042-git-integration-authentication-tokens.md) ### 從既有的 Git 儲存庫建立 Overleaf 專案 如果您已有一個儲存庫，可以將 Overleaf 專案新增為遠端儲存庫。您需要執行下列幾個指令來開始設定。請注意，Overleaf 每個專案只支援一條線性歷史。Git 整合會透過將分支數量限制為一個來強制執行此限制。那個唯一的分支目前是硬編碼為稱為 `master`. 1. 首先，我們假設您電腦上有一個 Git 儲存庫，位於名為 `my-paper`的資料夾中。（它也可能託管在 GitHub、GitLab 或 Bitbucket 等平台上，但您也需要先將它複製到本機。） 2. 建立 [新專案](/latex/zh-tw/zhi-shi-ku/031-creating-a-document-in-overleaf.md) 在 Overleaf 上。由於專案中的任何內容都會被覆寫，建立此專案時請使用「空白」專案選項，並刪除 Overleaf 中的 `main.tex` 檔案。 3. 找出該專案的 Git URL（請參閱 [上方](#cloning-your-project-as-a-local-repository)). ![Git-bridge-url.png](/files/f08dc20a3f78405defb743d6c3270b2a6784dbea) 4. 將專案的 Git URL 新增為本機專案中的遠端。 ``` $ cd my-paper $ git remote add overleaf ``` （請務必使用您自己的連結，而不是範例連結。） 5. 從 Overleaf 專案提取最新內容並將其合併到您的 master 分支。 ``` $ git checkout master $ git pull overleaf master --allow-unrelated-histories --rebase=false ``` 6. 將您的專案推送到 Overleaf。 ``` $ git push overleaf master --set-upstream ``` 如果您想在本機使用不同的分支名稱，例如 `my-branch`，您可以使用別名推送變更： ``` $ git push overleaf my-branch:master ``` 7. 前往 Overleaf 上的專案。您的變更應該已經出現。（您可能需要開啟 Overleaf 專案選單，找出哪個檔案被設定為主要文件，並視需要更改這個初始選擇。） ### Git 提交與 Overleaf Git 整合 Overleaf 內建有一個 [歷史系統](/latex/zh-tw/geng-duo-zhu-ti/49-using-the-history-feature.md) 可讓多人在 Overleaf 專案中同時協作。這與 Git 並不相同，因此 Overleaf Git 整合本質上是將 Overleaf 的歷史與版本控管機制轉換成 Git。這支援許多可啟用 Git 的使用情境，但無法讓您在 Overleaf 中像使用完整的 Git 實作那樣工作。 #### 提交會在什麼時候建立？ 當您執行一個 `pull` 或 `fetch` 指令時，如果目前專案狀態沒有對應的提交，就會動態建立一個新的提交。當您 `push` 本機儲存庫中的檔案到 Overleaf 遠端時，也會在那時建立提交，並會在您之後建立的任何 Overleaf 專案複本中可見。當您或其他人在 Overleaf 中編輯時，不會自動產生提交，直到有需要為止。 #### 強制建立提交 如果您希望在 Overleaf 歷史中的特定時間點強制建立提交，可以透過 [為版本加上標籤](/latex/zh-tw/geng-duo-zhu-ti/49-using-the-history-feature.md) 來做到這一點。即使您沒有立刻執行 git pull，被標記的版本也會有自己的提交雜湊值。只有在所標記的 Overleaf 歷史點之後，沒有任何更新的提交時，標籤才會建立提交。 #### 追蹤作者資訊 Overleaf Git 整合的即時產生提交特性意味著，如果在提交產生之前，Overleaf 端已經有多次變更，則最近一次變更的作者會被列為該提交的作者。 與共同作者合作時，在每位協作者完成一個重要更新後建立標籤（生成一個提交）會很有幫助——這會在 Git 中建立一連串最能反映 Overleaf 中變更情況的提交。 ### 與另一個遠端同步 Overleaf 的 Git 整合可讓您的 Overleaf 專案作為本機儲存庫的遠端儲存庫。不過，您可能希望將 Overleaf 專案與另一個託管在 GitHub、GitLab 或其他 Git 託管服務上的遠端同步。 如果您要將專案與託管在 GitHub 上的儲存庫同步（），您可能會想使用 Overleaf 直接的 [GitHub 同步](/latex/zh-tw/zhi-shi-ku/044-github-synchronization.md) 功能。 如果您是將專案與 GitLab、GitHub Enterprise 或其他主機同步，可以使用 Overleaf Git 整合來建立一個中介的本機儲存庫。 依照上方關於 [複製您的專案](#cloning-your-project-as-a-local-repository) 或 [將專案連結到既有儲存庫](#creating-an-overleaf-project-from-an-existing-git-repository)的指示操作後，您會擁有一個可與 Overleaf 互相推送／提取變更的本機儲存庫。接著您可以為這個儲存庫新增第二個遠端，指向您託管的儲存庫。您的本機端需要有兩個遠端，分別指向您的 Git 主機與 Overleaf 專案。 雖然 Overleaf 專案與您的 Git 儲存庫之間不會有直接連線，但這樣仍可讓您維持兩者同步。 ![Git other remote.png](/files/ea83e40d07aff7d0c58b1e95ff89180d3c35f53e) ### 將 Overleaf 專案新增為 Git 子模組 Overleaf 上的每個專案都可視為獨立的 Git 儲存庫，但如果您想將多個這類專案組織成單一 Git 儲存庫，可以照一般方式將每個專案的儲存庫新增為 Git 子模組。之後您仍可個別將每個子模組儲存庫推送到／從 Overleaf 提取，並同時將它們作為子模組彙整到更大型的專案中。 **注意：** 雖然 Overleaf 專案可以作為另一個儲存庫中的子模組，但 Overleaf 專案本身不能包含其他子模組。 ### 已知限制 **分支**：Overleaf Git 系統不支援分支。 **符號連結**：Overleaf Git 系統對符號連結的處理不佳。符號連結可以被推送到 Overleaf 專案中，但會被轉換成一般檔案，並在下次提取專案時覆蓋本機的符號連結。 **標籤**：Overleaf Git 系統不支援標記。 **檔案權限**：Overleaf Git 系統不會保留可執行權限。為了因應這個問題，您可以在本機複製的儲存庫中執行 `git config core.fileMode false` 。接著您可以重設任何受影響檔案的可執行權限。如此一來，之後的 Git 操作就不會再次修改它們。 **Git LFS：** Overleaf 專案不支援 Git Large File Storage。 **Git 子模組：** Overleaf 專案可以作為其他儲存庫中的 Git 子模組，但不能包含其他 Git 子模組。若要參照其他專案中的檔案，建議使用 [從其他專案新增功能](/latex/zh-tw/zhi-shi-ku/009-can-i-share-files-e.g.-.bib-and-some-graphics-across-my-projects.md). **重新命名資料夾**：如果使用者重新命名了一個資料夾，並將變更推送到 Overleaf，除了新資料夾之外，該專案還會保留一個舊名稱的空資料夾。（例如，將 images/ 重新命名為 img/，會讓專案中留下兩個資料夾：包含圖片檔案的 img/，以及空的 images/。當使用者在一個提交中重新命名資料夾，並建立一個與舊資料夾同名的新檔案時，這可能會造成問題。Overleaf Git 系統會拒絕這個提交。在這種情況下，我們建議將提交拆成兩部分，並刪除剩餘的資料夾。 **重新命名檔案與移動檔案：** 在本機儲存庫中重新命名檔案，在 Overleaf 端會變成刪除與建立。這可能導致 Overleaf 端與檔案相關的中繼資料遺失，造成已追蹤變更與註解被刪除。不建議在 Git 端移動或重新命名那些在 Overleaf 有已追蹤變更或註解的檔案。 **追蹤變更與註解**：很遺憾地，從 Git 推送到 Overleaf 可能會導致追蹤變更與註解遺失或位置被移動；因此，我們不建議混合使用 Git 與追蹤變更和／或註解。 ### 疑難排解 #### 找不到儲存庫錯誤 如果您看到「找不到儲存庫」錯誤，很可能是使用了錯誤的 URL。正確的 URL 可在專案內的選單中點擊 Git 選項找到。對於 Overleaf Cloud，Git 整合是付費功能，因此只有在專案擁有者訂閱了付費方案，或已獲得此功能的使用權（例如參與早期測試）時才可使用。 #### 驗證失敗錯誤 請參閱下列的疑難排解說明： [Git 整合驗證權杖](/latex/zh-tw/zhi-shi-ku/042-git-integration-authentication-tokens.md) 或 [Git 整合密碼驗證](/latex/zh-tw/zhi-shi-ku/043-git-integration-password-based-authentication.md) 取決於您使用的是哪種登入方式。 #### 速率限制 當手動執行 Git 操作時，通常不會發生 Git Bridge 的速率限制。不過，有些 Git 用戶端可以設定為自動輪詢遠端是否有變更，這在某些情況下可能導致速率限制錯誤。一般來說，停用任何自動輪詢，或降低 Git 操作的頻率，就能解決這些問題。 #### 推送參照失敗 無法將某些參照推送到遠端專案，可能是因為 [超出了專案的檔案大小或數量限制](/latex/zh-tw/zhi-shi-ku/119-overleaf-plan-limits.md) ，或是包含不支援的檔案類型（例如符號連結或 LFS）。請檢查上方列出的已知限制，以找出提交中的問題檔案。 在某些情況下，提高 **postBuffer** 設定可以解決從本機儲存庫推送參照到 Overleaf 專案失敗的問題。 首先，您可以用以下指令檢查目前設定： ```      git config http.postBuffer ``` 如果沒有輸出，表示使用的是 1MB 的預設值。 接著，試試以下指令 ```      git config --global http.postBuffer 10485760 ``` 這會將值改設為 10MB。 現在您可以嘗試推送該提交（到原始專案或新的專案皆可）。如果仍然失敗，您可以回復到先前的設定，或使用以下指令移除該設定： ```      git config --global --unset http.postBuffer ``` #### 逾時 包含大量變更的 Git 提交可能會導致逾時。如果遇到逾時，請嘗試將提交拆成較小的變更。如果問題仍然存在，請考慮依照上方說明將 **postBuffer** 設為 10MB。 --- # 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/040-git-integration.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.