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

`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.