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>

1 files changed, 13 insertions, 9 deletions

diff --git a/docs/internal-fs-layout.md b/docs/internal-fs-layout.md
index f4740291..9e724e7b 100644
--- a/docs/internal-fs-layout.md
+++ b/docs/internal-fs-layout.md
@@ -92,19 +92,23 @@ support, see the [manifest-format.md] file.
     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/`.
-
-    This can run into problems if different remotes use the same path on their
-    respective servers ...
+    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 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.