| # 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.smartsync | `--smart-sync` | Default to [Smart Sync](./smart-sync.md) when syncing | | |
| | 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/partial-clone | |
| [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. | |
| Managed with `repo config`; see [repoconfig.md](./repoconfig.md) for the | |
| available settings. | |
| * `.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 |