docs/internal-fs-layout.md

# Repo internal filesystem layout

A reference to the `.repo/` tree in repo client checkouts.
Hopefully it's complete & up-to-date, but who knows!

*** note
**Warning**:
This is meant for developers of the repo project itself as a quick reference.
**Nothing** in here must be construed as ABI, or that repo itself will never
change its internals in backwards incompatible ways.
***

[TOC]

## .repo/ layout

All content under `.repo/` is managed by `repo` itself with few exceptions.

In general, you should not make manual changes in here.
If a setting was initialized using an option to `repo init`, you should use that
command to change the setting later on.
It is always safe to re-run `repo init` in existing repo client checkouts.
For example, if you want to change the manifest branch, you can simply run
`repo init --manifest-branch=<new name>` and repo will take care of the rest.

*   `config`: Per-repo client checkout settings using [git-config] file format.
*   `.repo_config.json`: JSON cache of the `config` file for repo to
    read/process quickly.

### repo/ state

*   `repo/`: A git checkout of the repo project.  This is how `repo` re-execs
    itself to get the latest released version.

    It tracks the git repository at `REPO_URL` using the `REPO_REV` branch.
    Those are specified at `repo init` time using the `--repo-url=<REPO_URL>`
    and `--repo-rev=<REPO_REV>` options.

    Any changes made to this directory will usually be automatically discarded
    by repo itself when it checks for updates.  If you want to update to the
    latest version of repo, use `repo selfupdate` instead.  If you want to
    change the git URL/branch that this tracks, re-run `repo init` with the new
    settings.

*   `.repo_fetchtimes.json`: Used by `repo sync` to record fetch times when
    syncing the various projects.

*   `.repo_localsyncstate.json`: Used by `repo sync` to detect and warn on
    on partial tree syncs.  Partial syncs are allowed by `repo` itself, but are
    unsupported by many projects where `repo` is used.

### Manifests

For more documentation on the manifest format, including the local_manifests
support, see the [manifest-format.md] file.

*   `submanifests/{submanifest.path}/`: The path prefix to the manifest state of
    a submanifest included in a multi-manifest checkout.  The outermost manifest
    manifest state is found adjacent to `submanifests/`.

*   `manifests/`: A git checkout of the manifest project.  Its `.git/` state
    points to the `manifest.git` bare checkout (see below).  It tracks the git
    branch specified at `repo init` time via `--manifest-branch`.

    The local branch name is always `default` regardless of the remote tracking
    branch.  Do not get confused if the remote branch is not `default`, or if
    there is a remote `default` that is completely different!

    No manual changes should be made in here as it will just confuse repo and
    it won't automatically recover causing no new changes to be picked up.

*   `manifests.git/`: A bare checkout of the manifest project.  It tracks the
    git repository specified at `repo init` time via `--manifest-url`.

    No manual changes should be made in here as it will just confuse repo.
    If you want to switch the tracking settings, re-run `repo init` with the
    new settings.

*   `manifest.xml`: The manifest that repo uses.  It is generated at `repo init`
    and uses the `--manifest-name` to determine what manifest file to load next
    out of `manifests/`.

    Do not try to modify this to load other manifests as it will confuse repo.
    If you want to switch manifest files, re-run `repo init` with the new
    setting.

    Older versions of repo managed this with symlinks.

*   `manifest.xml -> manifests/<manifest-name>.xml`: A symlink to the manifest
    that the user wishes to sync.  It is specified at `repo init` time via
    `--manifest-name`.


*   `manifests.git/.repo_config.json`: JSON cache of the `manifests.git/config`
    file for repo to read/process quickly.

*   `local_manifest.xml` (*Deprecated*): User-authored tweaks to the manifest
    used to sync.  See [local manifests] for more details.
*   `local_manifests/`: Directory of user-authored manifest fragments to tweak
    the manifest used to sync.  See [local manifests] for more details.

### Project objects

*** note
**Warning**: Please do not use repo's approach to projects/ & project-objects/
layouts as a model for other tools to implement similar approaches.
It has a number of known downsides like:
*   [Symlinks do not work well under Windows](./windows.md).
*   Git sometimes replaces symlinks under .git/ with real files (under unknown
    circumstances), and then the internal state gets out of sync, and data loss
    may ensue.
*   When sharing project-objects between multiple project checkouts, Git might
    automatically run `gc` or `prune` which may lead to data loss or corruption
    (since those operate on leaf projects and miss refs in other leaves).  See
    https://gerrit-review.googlesource.com/c/git-repo/+/254392 for more details.

Instead, you should use standard Git workflows like [git worktree] or
[gitsubmodules] with [superprojects].
***

*   `copy-link-files.json`: Tracking file used by `repo sync` to determine when
    copyfile or linkfile are added or removed and need corresponding updates.
*   `project.list`: Tracking file used by `repo sync` to determine when projects
    are added or removed and need corresponding updates in the checkout.
*   `projects/`: Bare checkouts of every project synced by the manifest.  The
    filesystem layout matches the `<project path=...` setting in the manifest
    (i.e. where it's checked out in the repo client source tree).  Those
    checkouts will symlink their `.git/` state to paths under here.

    Some git state is further split out under `project-objects/`.
*   `project-objects/`: Git objects that are safe to share across multiple
    git checkouts.  The filesystem layout matches the `<project name=...`
    setting in the manifest (i.e. the path on the remote server) with a `.git`
    suffix.  This allows for multiple checkouts of the same remote git repo to
    share their objects.  For example, you could have different branches of
    `foo/bar.git` checked out to `foo/bar-main`, `foo/bar-release`, etc...
    There will be multiple trees under `projects/` for each one, but only one
    under `project-objects/`.

    This layout is designed to allow people to sync against different remotes
    (e.g. a local mirror & a public review server) while avoiding duplicating
    the content.  However, this can run into problems if different remotes use
    the same path on their respective servers.  Best to avoid that.
*   `modules/`: Like `projects/`, but for git submodules.
*   `subproject-objects/`: Like `project-objects/`, but for git submodules.
*   `worktrees/`: Bare checkouts of every project synced by the manifest.  The
    filesystem layout matches the `<project name=...` setting in the manifest
    (i.e. the path on the remote server) with a `.git` suffix.  This has the
    same advantages as the `project-objects/` layout above.

    This is used when [git worktree]'s are enabled.

### Global settings

The `.repo/manifests.git/config` file is used to track settings for the entire
repo client checkout.

Most settings use the `[repo]` section to avoid conflicts with git.

Everything under `[repo.syncstate.*]` is used to keep track of sync details for logging
purposes.

User controlled settings are initialized when running `repo init`.

| Setting                  | `repo init` Option        | Use/Meaning |
|-------------------       |---------------------------|-------------|
| manifest.groups          | `--groups` & `--platform` | The manifest groups to sync |
| manifest.standalone      | `--standalone-manifest`   | Download manifest as static file instead of creating checkout |
| repo.archive             | `--archive`               | Use `git archive` for checkouts |
| repo.clonebundle         | `--clone-bundle`          | Whether the initial sync used clone.bundle explicitly |
| repo.clonefilter         | `--clone-filter`          | Filter setting when using [partial git clones] |
| repo.depth               | `--depth`                 | Create shallow checkouts when cloning |
| repo.dissociate          | `--dissociate`            | Dissociate from any reference/mirrors after initial clone |
| repo.git-lfs             | `--git-lfs`               | Enable [Git LFS] support |
| repo.mirror              | `--mirror`                | Checkout is a repo mirror |
| repo.partialclone        | `--partial-clone`         | Create [partial git clones] |
| repo.partialcloneexclude | `--partial-clone-exclude` | Comma-delimited list of project names (not paths) to exclude while using [partial git clones] |
| repo.reference           | `--reference`             | Reference repo client checkout |
| repo.submodules          | `--submodules`            | Sync git submodules |
| repo.superproject        | `--use-superproject`      | Sync [superproject] |
| repo.worktree            | `--worktree`              | Use [git worktree] for checkouts |
| user.email               | `--config-name`           | User's e-mail address; Copied into `.git/config` when checking out a new project |
| user.name                | `--config-name`           | User's name; Copied into `.git/config` when checking out a new project |

[partial git clones]: https://git-scm.com/docs/gitrepository-layout#_code_partialclone_code
[superproject]: https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects

### Repo hooks settings

For more details on this feature, see the [repo-hooks docs](./repo-hooks.md).
We'll just discuss the internal configuration settings.
These are stored in the registered `<repo-hooks>` project itself, so if the
manifest switches to a different project, the settings will not be copied.

| Setting                              | Use/Meaning |
|--------------------------------------|-------------|
| repo.hooks.\<hook\>.approvedmanifest | User approval for secure manifest sources (e.g. https://) |
| repo.hooks.\<hook\>.approvedhash     | User approval for insecure manifest sources (e.g. http://) |


For example, if our manifest had the following entries, we would store settings
under `.repo/projects/src/repohooks.git/config` (which would be reachable via
`git --git-dir=src/repohooks/.git config`).
```xml
  <project path="src/repohooks" name="chromiumos/repohooks" ... />
  <repo-hooks in-project="chromiumos/repohooks" ... />
```

If `<hook>` is `pre-upload`, the `.git/config` setting might be:
```ini
[repo "hooks.pre-upload"]
	approvedmanifest = https://chromium.googlesource.com/chromiumos/manifest
```

## Per-project settings

These settings are somewhat meant to be tweaked by the user on a per-project
basis (e.g. `git config` in a checked out source repo).

Where possible, we re-use standard git settings to avoid confusion, and we
refrain from documenting those, so see [git-config] documentation instead.

See `repo help upload` for documentation on `[review]` settings.

The `[remote]` settings are automatically populated/updated from the manifest.

The `[branch]` settings are updated by `repo start` and `git branch`.

| Setting                               | Subcommands   | Use/Meaning |
|---------------------------------------|---------------|-------------|
| review.\<url\>.autocopy               | upload        | Automatically add to `--cc=<value>` |
| review.\<url\>.autoreviewer           | upload        | Automatically add to `--reviewers=<value>` |
| review.\<url\>.autoupload             | upload        | Automatically answer "yes" or "no" to all prompts |
| review.\<url\>.uploadhashtags         | upload        | Automatically add to `--hashtag=<value>` |
| review.\<url\>.uploadlabels           | upload        | Automatically add to `--label=<value>` |
| review.\<url\>.uploadnotify           | upload        | [Notify setting][upload-notify] to use |
| review.\<url\>.uploadtopic            | upload        | Default [topic] to use |
| review.\<url\>.uploadwarningthreshold | upload        | Warn when attempting to upload more than this many CLs |
| review.\<url\>.username               | upload        | Override username with `ssh://` review URIs |
| remote.\<remote\>.fetch               | sync          | Set of refs to fetch |
| remote.\<remote\>.projectname         | \<network\>   | The name of the project as it exists in Gerrit review |
| remote.\<remote\>.pushurl             | upload        | The base URI for pushing CLs |
| remote.\<remote\>.review              | upload        | The URI of the Gerrit review server |
| remote.\<remote\>.url                 | sync & upload | The URI of the git project to fetch |
| branch.\<branch\>.merge               | sync & upload | The branch to merge & upload & track |
| branch.\<branch\>.remote              | sync & upload | The remote to track |

## ~/ dotconfig layout

Repo will create & maintain a few files under the `.repoconfig/` directory.
This is placed in the user's home directory by default but can be changed by
setting `REPO_CONFIG_DIR`.

*   `.repoconfig/`: Repo's per-user directory for all random config files/state.
*   `.repoconfig/config`: Per-user settings using [git-config] file format.
*   `.repoconfig/keyring-version`: Cache file for checking if the gnupg subdir
    has all the same keys as the repo launcher.  Used to avoid running gpg
    constantly as that can be quite slow.
*   `.repoconfig/gnupg/`: GnuPG's internal state directory used when repo needs
    to run `gpg`.  This provides isolation from the user's normal `~/.gnupg/`.

*   `.repoconfig/.repo_config.json`: JSON cache of the `.repoconfig/config`
    file for repo to read/process quickly.
*   `.repo_.gitconfig.json`: JSON cache of the `.gitconfig` file for repo to
    read/process quickly.


[git-config]: https://git-scm.com/docs/git-config
[Git LFS]: https://git-lfs.github.com/
[git worktree]: https://git-scm.com/docs/git-worktree
[gitsubmodules]: https://git-scm.com/docs/gitsubmodules
[manifest-format.md]: ./manifest-format.md
[local manifests]: ./manifest-format.md#Local-Manifests
[superprojects]: https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects
[topic]: https://gerrit-review.googlesource.com/Documentation/intro-user.html#topics
[upload-notify]: https://gerrit-review.googlesource.com/Documentation/user-upload.html#notify