> 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-cn/zhi-shi-ku/040-git-integration.md). # Git 集成 **Overleaf 的 Git 集成** 是一个 [高级功能](/latex/zh-cn/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 和克隆命令。 ![项目菜单 git.png](/files/0be109e0731ab0d955d5feeb0bf07d9ebb6f8c47) ### 使用 Git 集成时如何进行身份验证 当你对远程 Overleaf 项目执行 Git 操作，例如 clone、pull 或 push 时，系统会要求你进行身份验证。 要从 Git 访问你的 Overleaf 项目，你必须使用基于令牌的 Overleaf 身份验证。有关分步说明，请参见： [基于令牌的身份验证](/latex/zh-cn/zhi-shi-ku/042-git-integration-authentication-tokens.md). ### 将你的项目克隆为本地仓库 在 [**菜单**](/latex/zh-cn/zhi-shi-ku/148-using-the-overleaf-project-menu.md) 在你的项目中，你可以从同步选项中选择 Git。这将弹出一个对话框，显示 `git clone` 创建本地仓库时要使用的命令。 ![项目菜单 git.png](/files/0be109e0731ab0d955d5feeb0bf07d9ebb6f8c47) 或者，你可以从项目 URL 中找到 Git URL（也就是你在项目中时浏览器地址栏里的 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-cn/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-cn/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-cn/zhi-shi-ku/031-creating-a-document-in-overleaf.md) 在 Overleaf 上。由于项目中的任何内容都会被覆盖，创建此项目时请使用“空白”项目选项，并删除 `main.tex` Overleaf 中的文件。 3. 找到该项目的 Git URL（参见 [上文](#cloning-your-project-as-a-local-repository)). ![Git-bridge-url.png](/files/e15965a440ff8461b767f1c7d92b8ba42b3f5392) 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-cn/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-cn/geng-duo-zhu-ti/49-using-the-history-feature.md) 在 Overleaf 历史记录中实现。即使你不立即执行 git pull，被标记的版本也会获得自己的提交哈希。只有当自所标记的 Overleaf 历史点以来没有更近的其他提交时，才会由该标签创建提交。 #### 跟踪作者 Overleaf Git 集成中的提交是即时生成的，这意味着如果在生成提交之前，Overleaf 端发生了多次更改，那么最近一次更改的作者将被列为该提交的作者。 与合作者一起工作时，建议在每位协作者完成一次重要更新后创建一个标签（从而生成一个提交）——这样可以在 Git 中创建一系列可见的提交，更准确地反映 Overleaf 中正在发生的更改。 ### 与另一个远程仓库同步 Overleaf 的 Git 集成允许你的 Overleaf 项目充当地本地仓库的远程仓库。不过，你可能希望将你的 Overleaf 项目与另一个远程仓库同步，该仓库托管在 GitHub、GitLab 或其他 Git 托管服务上。 如果你正在将项目与托管在 GitHub 上的仓库同步（），你可能希望使用 Overleaf 的直接 [GitHub 同步](/latex/zh-cn/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 进行 push/pull 更改的本地仓库。然后，你可以为此仓库再添加一个指向你托管仓库的第二个远程。你的本地仓库需要有两个远程，这样它才能同时指向你的 Git 主机和 Overleaf 项目。 尽管 Overleaf 项目和你的 Git 仓库之间不会有直接连接，但这将使你能够保持它们同步。 ![Git other remote.png](/files/504c335d6f01eec5757a69800bcd93f88dde0afe) ### 将 Overleaf 项目添加为 Git 子模块 Overleaf 上的每个项目都充当一个独立的 Git 仓库，但如果你想将多个这样的项目组织到一个 Git 仓库中，你可以按照通常方式将每个项目的仓库作为 Git 子模块添加进去。然后，你可以分别对每个子模块仓库与 Overleaf 进行 push 和 pull，同时仍然将它们作为子模块收集到一个更大的项目中。 **注意：** 虽然 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-cn/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 集成是一项高级功能，因此只有在项目所有者订阅了付费版 Overleaf 或已获得该功能访问权限时才可用（例如参与早期测试版时获得访问权限）。 #### 身份验证失败错误 请查看以下内容的故障排除说明： [Git 集成身份验证令牌](/latex/zh-cn/zhi-shi-ku/042-git-integration-authentication-tokens.md) 或 [Git 集成密码身份验证](/latex/zh-cn/zhi-shi-ku/043-git-integration-password-based-authentication.md) 具体取决于你使用的登录方式。 #### 速率限制 在手动执行 Git 操作时，通常不会发生 Git Bridge 的速率限制。有些 Git 客户端可以配置为自动轮询远程仓库以检查更改，这在某些情况下会导致速率限制错误。通常，禁用任何自动轮询或降低 Git 操作频率即可解决这些问题。 #### 推送引用失败 无法将某些引用推送到远程项目，可能是由于 [超出了项目的文件大小或文件数量限制](/latex/zh-cn/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-cn/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.