> For the complete documentation index, see [llms.txt](https://docs.overleaf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization/interacting-with-large-git-repositories.md). # Interacting with large Git repositories Overleaf users sometimes run into trouble synchronizing their large Git repositories with an Overleaf project. This page provides some guidance on how to manage this situation. {% hint style="warning" %} This page describes a specific scenario for working with Overleaf's [GitHub synchronization](/integrations-and-add-ons/git-integration-and-github-synchronization/github-synchronization.md) and [Git integratio](/integrations-and-add-ons/git-integration-and-github-synchronization/git-integration.md)n features. Please refer to the documentation on those features for general information about them. {% endhint %} Research projects often involve broad software repositories containing raw data, processing scripts (e.g., Python or R), literature PDFs, and experimental outputs alongside LaTeX source files. Git repositories that are used in research or teaching workflows often contain many different types of resources. An Overleaf project, on the other hand, is designed specifically to compile a single LaTeX document. A project should not be used as a general storage space for research artifacts (PDFs, data sets, etc.). While there are cases where a project can contain independently compilable LaTeX source files, in most cases each Overleaf project should be used to compile a single document, and each of your LaTeX documents should be in a distinct project. Conceptually related projects can be organized [using tags](/managing-projects-and-files/organizing-projects-with-tags.md), and common files that are required by multiple projects can be [shared between projects](/managing-projects-and-files/adding-files-to-a-project/sharing-files-across-projects.md). {% hint style="danger" %} If a large research workspace is synchronized directly with an Overleaf project, using either the GitHub synchronization or the Git integration features, these differences can lead to synchronization timeouts, errors due to unexpected file types, plan limit warnings, or import failures. {% endhint %} Separating your LaTeX compilation files from your broader research workspace provides a modular structure for sharing, backing up, and managing both your research assets and your final manuscript. ## Problems with large repositories You may need to restructure your repository if you encounter any of the following issues when attempting to import a project or synchronize with GitHub, or when you push or pull using the Git integration. * **GitHub Sync errors**: This error may be reported as "We couldn’t reach GitHub. Please try again in a few moments." This error can be caused by API Timeout Errors, triggered by the inclusion of large files or large multi-file commits. * **Git Integration timeouts, or failures to push**: Timeouts can be experienced when pushing large artifacts or large commits via the Git Integration. * **File limitations on the Overleaf side**: Limitations on the total number of files or on the amount of editable text can be shown on the Overleaf side when the project is linked to a large repository. Please see [Plan limits](/getting-started/free-and-premium-plans/plan-limits.md). ## Recommended workflow strategies Depending on whether you prefer local command-line tools or cloud-based automation, several flexible workflows can keep a main workspace up-to-date with an Overleaf project. In these workflows, we assume that you have a general research or teaching repository that we will refer to as your **workspace repository**. This workplace repository may contain data, scripts, PDFs of related papers, and other artifacts in addition to the LaTeX source files. In contrast, we will refer to the repository that solely contains the LaTeX source files that are to be kept in sync with an Overleaf project as your **paper repository.** {% hint style="success" %} **Rule 1:** Do not synchronize a large **workspace repository** directly with an Overleaf project, either using GitHub Synchronization or the Git Integration. **Rule 2:** Synchronize a smaller, distinct **paper repository** directly with an Overleaf project, either using GitHub Synchronization or the Git Integration. **Rule 3**: Set up a relationship between the workspace repository and the paper repository that makes sense for your workflow. This is external to Overleaf, and will rely on local scripts, GitHub automation, or other tools. {% endhint %} There are several strategies for setting up a relationship between the workspace repository and the paper repository to keep them up-to-date with each other. These can be automated or can be implemented as manual processes. {% hint style="info" %} These workflow strategy examples are intended as conceptual guidance to help you design a repository layout and automation that fits your needs. While our support team is always happy to help with Overleaf’s native Git and GitHub integration features, we cannot assist with creating or debugging custom local scripts, GitHub Actions, or advanced Git command-line use. {% endhint %} ### Strategy 1: Dedicated sub-repository (submodules or subtrees) You can isolate your document files into a dedicated paper repository, then embed that repository inside your main research repository as a Git **submodule** or **subtree**. * **Structure**: The dedicated paper repository contains only the files needed for LaTeX compilation. * **On Overleaf**: Connect your Overleaf project directly to the dedicated paper repository using GitHub Synchronization or the Git Integration. * **Within Git or GitHub**: Embed the paper repository inside your main workspace repository as a submodule or folder subtree. * **Workflow**: Local edits inside the submodule directory can be pushed directly to update Overleaf, while your main repository tracks overall project history. ### Strategy 2: Automated folder synchronization (GitHub Actions) If you prefer to maintain separate, standalone repositories without using submodules, you can automate file transfers between them. * **Structure**: Maintain a primary workspace repository for research data and a secondary paper repository for the Overleaf project. * **Git or GitHub automation**: Set up a GitHub Actions or CI/CD workflows in your workspace and/or repository. The workflows can be automatically triggered or explicit invocation. These may copy LaTeX assets from the paper repository back to the workspace repository, or may copy other assets (generated figures, tables) from the workspace repository to the paper repository. * **Workflow**: Whenever you update figures or tables in the workspace repo, the action copies those specific assets to the paper repository, which is synchronized with your Overleaf project. ### Strategy 3: Local copying For workflows managed entirely on a local machine, you can use the [Overleaf Git](/integrations-and-add-ons/git-integration-and-github-synchronization/git-integration.md) Integration to bridge your directories without cloud automation. * **Structure**: Clone both your main workflow repository locally and your Overleaf project locally (using the Overleaf Git URL). These are independent folders on your local machine. * **Workflow**: Use local build scripts or standard copy commands to transfer generated figures or updated tables from your local workspace folder into your local Overleaf clone. Commit and push from the local Overleaf clone directly to the Overleaf remote. ## Course and teaching repositories While this guide focuses on a single paper within a research workspace, these architectural patterns also apply to other multi-artifact environments. For instance, instructors managing a course repository (containing lecture slides, assignment sheets, solution keys, and syllabi) face similar scope challenges. When specific LaTeX assets from a master course folder need to be edited in Overleaf, those specific subfolders can be extracted into dedicated paper repositories using the same submodule, subtree, or automated mirroring methods as described above. ## Limitations While separating LaTeX assets into dedicated repositories resolves project size and timeout issues, you should evaluate the following trade-offs: * **1:1 mapping requirement**: Overleaf integrations require a direct link between a single Overleaf project and a single Git repository. Overleaf cannot link directly to a sub-folder within a repository. * **Multiple repositories**: Extracting many distinct LaTeX documents from a single mono-repo may be challenging. If your team or personal workflow requires many distinct documents to reside in the same repository, creating and multiple sub repos or sub trees may be difficult. * **Shared dependencies**: If multiple documents share a single common resource, that dependency must be manually duplicated or synced across every secondary repository. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization/interacting-with-large-git-repositories.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.