> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/docs-as-code/git-sync/monorepos.md).

# Monorepos

Use Git Sync with monorepos and map spaces to separate directories

Use site-wide Git Sync to sync multiple spaces from one repository and branch. Map each space to its own directory in `gitbook-docs.yaml`.

### How site-wide Git Sync works

The site’s **Project directory** sets the Git Sync installation directory. `gitbook-docs.yaml` lives there. If you leave it empty, GitBook uses the repository root.

In `gitbook-docs.yaml`, each space has a `content.directory`. That directory contains the space’s `.gitbook.yaml`, `README.md`, `SUMMARY.md`, and content files.

For an overview of these files, see [Content configuration](/docs/docs-as-code/git-sync/content-configuration.md).

### Map spaces to directories

Use **Content mapping** in the Git Sync panel to map each space. GitBook saves the mapping in `gitbook-docs.yaml`.

Directory paths work as follows:

| Path     | Meaning                                          |
| -------- | ------------------------------------------------ |
| `./docs` | A directory inside the site’s Project directory. |
| `/docs`  | A directory from the repository root.            |
| `docs`   | The same as `./docs`.                            |

For example, this repository maps three spaces:

```
/
  gitbook-docs.yaml
  documentation/
    .gitbook.yaml
    README.md
    SUMMARY.md
    .gitbook/
      assets/
        logo.png
  developers/
    .gitbook.yaml
    README.md
    SUMMARY.md
  changelog/
    .gitbook.yaml
    README.md
    SUMMARY.md
```

This `gitbook-docs.yaml` maps each space to its directory:

{% code title="gitbook-docs.yaml" %}

```yaml
$schema: https://api.gitbook.com/gitbook-docs.yaml
site:
  structure:
    - type: space
      key: documentation
      title: Documentation
      path: documentation
      content:
        directory: ./documentation
    - type: space
      key: developers
      title: Developers
      path: developers
      content:
        directory: ./developers
    - type: space
      key: changelog
      title: Changelog
      path: changelog
      content:
        directory: ./changelog
```

{% endcode %}

### Keep space content self-contained

Each space only syncs the directory assigned to it. GitBook doesn’t automatically share content or assets between mapped directories.

Keep every referenced asset inside its space’s mapped directory. If several spaces need an asset, add a copy to each directory or reorganize the repository.

The `.gitbook.yaml` `root` setting controls where GitBook reads content within that space’s mapped directory. It doesn’t make sibling directories available.

### Move a mapped directory

Move a space’s content by updating its files and mapping together:

1. In the repository, move the space’s content files and assets.
2. In `gitbook-docs.yaml`, update that space’s `content.directory`. Leave its `key` unchanged.
3. Commit both changes in the same commit.

{% hint style="info" %}
If GitBook imports before both changes exist, the mapped space can appear empty.
{% endhint %}

{% hint style="danger" %}
**Don’t rename the `key` to match the new directory.** Keys and directory names are independent. Changing a space’s key replaces the space with a new one that has a new space ID, and restoring the original key doesn’t bring the old ID back. See [Keys identify your spaces](/docs/docs-as-code/git-sync/content-configuration.md#keys-identify-your-spaces).
{% endhint %}

Keys generated by GitBook — `space-1`, `space-2` — don’t reflect directory names, and there’s no benefit to keeping the two aligned.

### Use individual space Git Sync

Use individual space Git Sync when a space needs another repository or branch. For example, use it when a private space must sync separately.

Remove the space from the site’s content mapping first. Then configure Git Sync from that space.

To configure the space, follow [Enabling GitHub Sync](/docs/docs-as-code/git-sync/enabling-github-sync.md) or [Enabling GitLab Sync](/docs/docs-as-code/git-sync/enabling-gitlab-sync.md). In the scope step, select **Space Git Sync**.


---

# 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://gitbook.com/docs/docs-as-code/git-sync/monorepos.md?ask=<question>&goal=<user_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.