docs: improve project-objects & worktrees layout info
Make it clear that the paths have a .git suffix, and clarify the
reason for not using remote servers in the layout.
Change-Id: I62c6977ee6f4e1e9882d45727eb239cf5489d2b6
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/256033
Reviewed-by: Jonathan Nieder <jrn@google.com>
Tested-by: Mike Frysinger <vapier@google.com>
diff --git a/docs/internal-fs-layout.md b/docs/internal-fs-layout.md
index f474029..9e724e7 100644
--- a/docs/internal-fs-layout.md
+++ b/docs/internal-fs-layout.md
@@ -92,19 +92,23 @@
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). 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-master`, `foo/bar-release`, etc... There will be multiple
- trees under `projects/` for each one, but only one under `project-objects/`.
+ 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-master`, `foo/bar-release`, etc...
+ There will be multiple trees under `projects/` for each one, but only one
+ under `project-objects/`.
- This can run into problems if different remotes use the same path on their
- respective servers ...
+ 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.
* `subprojects/`: 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).
+ (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 worktrees are enabled.
