> 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/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 企业版安装。 您可以通过从现有 GitHub 仓库创建新的 Overleaf 项目，或通过从现有 Overleaf 项目创建新的 GitHub 仓库来同步 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 权限设置，可通过您的 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 大文件存储。 **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 的历史中，更改会显示为“匿名（通过 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-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.