| Message ID | e7e579d2995288de13a2328e592e61f2b6dfaf63.1645379667.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Updates to worktree code and docs | expand |
On Sun, Feb 20, 2022 at 05:54:24PM +0000, Derrick Stolee via GitGitGadget wrote: > From: Derrick Stolee <derrickstolee@github.com> > > It is helpful to distinguish between a 'working tree' and a 'worktree'. > A worktree contains a working tree plus additional metadata. This > metadata includes per-worktree refs and worktree-specific config. > > This is the fourth of multiple changes to git-worktree.txt, restricted > to the REFS section. > > This section previously described "per working tree" refs but they are > now replaced with "per-worktree" refs, which matches the definition in > glossary-content.txt. > > Signed-off-by: Derrick Stolee <derrickstolee@github.com> > --- > Documentation/git-worktree.txt | 31 +++++++++++++++---------------- > 1 file changed, 15 insertions(+), 16 deletions(-) > > diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt > index 10021c85e77..54a2c335fd5 100644 > --- a/Documentation/git-worktree.txt > +++ b/Documentation/git-worktree.txt > @@ -255,24 +255,23 @@ have two worktrees, at `/abc/def/ghi` and `/abc/def/ggg`, then `ghi` or > > REFS > ---- > -In multiple working trees, some refs may be shared between all working > -trees and some refs are local. One example is `HEAD` which is different for each > -working tree. This section is about the sharing rules and how to access > -refs of one working tree from another. Not the fault of this patch, but I have a tough time deciphering this first sentence. Would the first part be clearer as: When using multiple worktrees, some refs are shared among all worktrees, but others are specific to an individual worktree. ? Otherwise, this patch (and all of the replacement one preceding it) look good to me. Thanks, Taylor
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 10021c85e77..54a2c335fd5 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -255,24 +255,23 @@ have two worktrees, at `/abc/def/ghi` and `/abc/def/ggg`, then `ghi` or REFS ---- -In multiple working trees, some refs may be shared between all working -trees and some refs are local. One example is `HEAD` which is different for each -working tree. This section is about the sharing rules and how to access -refs of one working tree from another. - -In general, all pseudo refs are per working tree and all refs starting -with `refs/` are shared. Pseudo refs are ones like `HEAD` which are -directly under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are -exceptions, however: refs inside `refs/bisect` and `refs/worktree` are not -shared. - -Refs that are per working tree can still be accessed from another -working tree via two special paths, `main-worktree` and `worktrees`. The -former gives access to per-working tree refs of the main working tree, -while the latter to all linked working trees. +In multiple worktrees, some refs may be shared between all worktrees and +some refs are local. One example is `HEAD` which is different for each +worktree. This section is about the sharing rules and how to access +refs of one worktree from another. + +In general, all pseudo refs are per-worktree and all refs starting with +`refs/` are shared. Pseudo refs are ones like `HEAD` which are directly +under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are exceptions, +however: refs inside `refs/bisect` and `refs/worktree` are not shared. + +Refs that are per-worktree can still be accessed from another worktree via +two special paths, `main-worktree` and `worktrees`. The former gives +access to per-worktree refs of the main worktree, while the latter to all +linked worktrees. For example, `main-worktree/HEAD` or `main-worktree/refs/bisect/good` -resolve to the same value as the main working tree's `HEAD` and +resolve to the same value as the main worktree's `HEAD` and `refs/bisect/good` respectively. Similarly, `worktrees/foo/HEAD` or `worktrees/bar/refs/bisect/bad` are the same as `$GIT_COMMON_DIR/worktrees/foo/HEAD` and