> For the complete documentation index, see [llms.txt](https://ayakaleaf-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://ayakaleaf-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 项目执行 clone、pull 或 push 等 Git 操作时，系统会要求你进行身份验证。 要通过 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 集成通过将分支数量限制为 1 来强制执行这一限制。该唯一分支目前被硬编码为称为 `master`. 1. 首先，我们假设你在电脑上有一个 Git 仓库，位于名为 `my-paper`的文件夹中。（它也可能托管在 GitHub、GitLab 或 Bitbucket 等平台上，但你也需要在本地克隆一份。） 2. 创建 [一个新项目](/latex/zh-cn/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/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 进行推送/拉取更改的本地仓库。然后你可以为这个仓库添加第二个远程仓库，指向你托管的仓库。你的本地仓库需要有两个远程地址，这样它就同时指向你的 Git 托管服务和 Overleaf 项目。 尽管 Overleaf 项目与你的 Git 仓库之间没有直接连接，但这将允许你保持它们同步。 ![Git other remote.png](/files/504c335d6f01eec5757a69800bcd93f88dde0afe) ### 将 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-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 云端，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://ayakaleaf-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.