kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

worktree: use 'worktree' over 'working tree' 

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.

The first paragraph of this section was also a bit confusing, so it is
cleaned up to make it easier to understand.

Helped-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
maint
Derrick Stolee 2022-02-23 14:29:16 +00:00 committed by Junio C Hamano
parent 6036be1458
commit a777d4c750
1 changed files with 13 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
Documentation/git-worktree.txt
View File

@ -256,24 +256,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.
When using multiple worktrees, some refs are shared between all worktrees,
but others are specific to an individual worktree. 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 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.
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 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.
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