> 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/044-github-synchronization.md). # GitHub 同步 **GitHub 同步** 是 [高级功能](/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). 摘要 GitHub 同步功能允许你将 Overleaf 项目直接链接到一个 GitHub 仓库，该仓库作为你的 Overleaf 项目的远程仓库，并提供在两者之间推送和拉取更改的方法。GitHub 同步只能用于 [Github.com](https://www.github.com) ，不能用于连接其他 GitHub 企业版安装实例。 你可以通过以下任一方式将 Overleaf 项目与 GitHub 仓库同步：从现有 GitHub 仓库创建新的 Overleaf 项目，或从现有 Overleaf 项目创建新的 GitHub 仓库。无法将现有 Overleaf 项目与现有 Github 仓库同步。 * 通过将你的 GitHub 账户链接到你的 Overleaf 账户来启用 GitHub 同步 * 可以从现有 GitHub 仓库创建新项目 * 可以基于现有 Overleaf 项目在 GitHub 中创建仓库 * 链接的项目和仓库会使用 **GitHub** 项目中的 **菜单** ### 将你的 Overleaf 账户链接到你的 GitHub 账户 要使用 GitHub 同步功能，你必须将你的 Overleaf 账户链接到你的 Github 账户。你可以在你的 Overleaf 中执行此操作 [账户设置](https://www.overleaf.com/user/settings)。请注意，Overleaf 能否连接到与你的账户相关的某些仓库或组织，可能取决于 GitHub 中已配置的权限设置。 ### 从 GitHub 仓库创建新的 Overleaf 项目 在“新建项目”菜单中，你可以选择 GitHub 选项。这将向你展示一个仓库列表，这些仓库根据你的 GitHub 权限设置，对 Overleaf 可见。 ![创建新 github.png](/files/cc134f3d952c22306574ac584904d8dce832db93) 从现有 GitHub 仓库创建新的 Overleaf 项目时，需要注意以下几点。 * Overleaf 项目有大小限制，这可能会阻止较大的 GitHub 仓库用于创建项目。请参见 [此页面](/latex/zh-cn/zhi-shi-ku/119-overleaf-plan-limits.md) ，了解 Overleaf 项目中文件大小和文件数量限制的概述。 * Overleaf 项目不支持 Git 子模块或 Git LFS。 ### 从 Overleaf 项目创建新的 GitHub 仓库 在 Overleaf 项目菜单中，你可以选择 GitHub 作为同步选项之一。这将为你提供一个对话框，你可以在其中提供一个新的 GitHub 仓库名称，以便与你的 Overleaf 项目同步。 ![项目菜单 github.png](/files/615ae57565a2ed2282d40d650c7c4622b366ab4e) ### 与 GitHub 同步 GitHub 与 Overleaf 之间不会自动同步，单击 **GitHub** 项目中的 **菜单**后会显示同步选项。届时 GitHub 弹窗会报告是否有新的更改可从 GitHub 拉取。你始终会看到将更改推送到 GitHub 的选项（注意：即使 Overleaf 和 GitHub 已是最新状态，也会显示此选项）。 ![GitHub 弹窗图片](/files/d81f9f328203f3c8294d98c990628bd4c24f4fcb) 当单击“将 Overleaf 更改推送到 GitHub”按钮时，会创建 GitHub 提交。此时可以提供可选的提交信息。 * 来自 GitHub 的 Overleaf 历史更改将显示为由匿名用户编写。 * 来自 Overleaf 的 GitHub 历史更改将显示为由已连接的 GitHub 账户所有者编写。 ### 解决合并冲突 当 Overleaf 和 Github 两边都进行了更改时，Git 可能无法自动判断如何将它们合并。例如，如果你的协作者在 Overleaf 中修改了一行，而你在 Github 仓库中修改了同一行，Overleaf 可能无法选择保留哪个版本。 发生这种情况时，我们不会合并到你的主分支，而是将一个新分支推送到你的仓库。该分支会有一个描述性名称（包含分支创建日期和时间），并包含 Overleaf 中文档的版本。当你尝试与 GitHub 同步时，会显示一条消息，提示需要解决合并冲突。 ![GitHub 合并冲突对话框](/files/77e113d71d49cdce6dd8af2b11010cfb1abc2e16) 要重新恢复同步，你需要将 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-cn/zhi-shi-ku/119-overleaf-plan-limits.md)。虽然 Git 本身可以处理一次提交更改成千上万个文件，但 Overleaf 的 GitHub 同步功能所使用的 GitHub API 也会对可推送或拉取的文件数量施加限制。建议在使用 GitHub 同步时，将单个提交中的文件数限制在 100 个以下，并将整体项目大小控制在 100 MB 以下。超过这些大小限制的项目可能仍然可用，但我们建议保持在这些限制之内，以避免潜在的同步问题。 ### 将项目与仓库断开连接 虽然可以从同一个现有 GitHub 仓库创建多个项目， **但无法更改与某个项目关联的仓库**。一旦项目链接到某个仓库，就无法取消链接并用于创建新的仓库。如果你需要从某个特定项目创建新仓库，你必须先制作该项目的新副本，然后再根据该副本创建新仓库。 ### 已知限制 **分支**：Overleaf Git 系统不支持分支。 **符号链接**：Overleaf Git 系统不处理符号链接。符号链接可以推送到 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-cn/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 用户身份捆绑提交到 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://ayakaleaf-pro.ayaka.space/latex/zh-cn/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.