| Message ID | 0260ff6cac0c76c6d66187d77defef1edd4c6fb5.1644269583.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 5c11c0d52c398af65f19bcf65a46304552083214 |
| Headers | show |
| Series | Sparse checkout: fix bug with worktree of bare repo | expand |
"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes: > diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt > index 4e23d73cdca..bccaec7a963 100644 > --- a/Documentation/config/extensions.txt > +++ b/Documentation/config/extensions.txt > @@ -6,3 +6,34 @@ extensions.objectFormat:: > Note that this setting should only be set by linkgit:git-init[1] or > linkgit:git-clone[1]. Trying to change it after initialization will not > work and will produce hard-to-diagnose issues. > + > +extensions.worktreeConfig:: > + If enabled, then worktrees will load config settings from the > + `$GIT_DIR/config.worktree` file in addition to the > + `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and > + `$GIT_DIR` are the same for the main working tree, while other > + working trees have `$GIT_DIR` equal to > + `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the The mixed use of "worktree" and "working tree" in this paragraph might confuse readers into thinking that the paragraph is being careful to make distinction between the two. All references to "working tree" in the above paragraph should actually be "worktree", I would think. Side note: "working tree" is in the glossary-content.txt, but "worktree", which is one "working tree" + repository metadata (i.e. ".git/") that may be partially shared with other "worktree"s of a single repository, is not defined. This is a tangent, but I wonder why we chose to use a different filename (i.e. not "config" but "config.worktree") for this. If we were redoing multi-worktree support from scratch, we would not reuse the $GIT_DIR used by the primary worktree as $GIT_COMMON_DIR, so that all worktrees would share a single $GIT_COMMON_DIR and $GIT_COMMON_DIR/config that has stuff that is shared among all the worktrees, while per worktree stuff is in $GIT_DIR/config even for the primary worktree. But that is all water under the bridge now. Other than the terminology gotcha, looked sensible. Migrating automatically and/or noticing a suspicious setting may be needed to help end users, but that would not be within the scope of this step. Attached is a "how about this?" glossary update suggestion. Most of the existing mention of "working tree" are fine as-is because they only care about what is in the "working tree", but some should be changed to "worktree" to stress the fact that they care not just the "working tree" part but also the repository metadata part that is associated with that single "working tree". The first hunk says worktree but it is clear that it is interested only in the "working tree" files. Documentation/glossary-content.txt | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt index c077971335..d816512c6a 100644 --- c/Documentation/glossary-content.txt +++ w/Documentation/glossary-content.txt @@ -312,7 +312,7 @@ Pathspecs are used on the command line of "git ls-files", "git ls-tree", "git add", "git grep", "git diff", "git checkout", and many other commands to limit the scope of operations to some subset of the tree or -worktree. See the documentation of each command for whether +working tree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The pathspec syntax is as follows: + @@ -446,7 +446,7 @@ exclude;; interface than the <<def_plumbing,plumbing>>. [[def_per_worktree_ref]]per-worktree ref:: - Refs that are per-<<def_working_tree,worktree>>, rather than + Refs that are per-<<def_worktree,worktree>>, rather than global. This is presently only <<def_HEAD,HEAD>> and any refs that start with `refs/bisect/`, but might later include other unusual refs. @@ -669,3 +669,12 @@ The most notable example is `HEAD`. The tree of actual checked out files. The working tree normally contains the contents of the <<def_HEAD,HEAD>> commit's tree, plus any local changes that you have made but not yet committed. + +[[def_work_tree]]worktree:: + A repository can have zero (i.e. bare repository) or one or + more worktrees attached to it. One "worktree" consists of a + "working tree" and repository metadata, most of which are + shared among other worktrees of a single repository, and + some of which are maintained separately per worktree + (e.g. the index, HEAD, per-worktree refs and per-worktree + configuration file)
On 2/8/2022 5:20 PM, Junio C Hamano wrote: > "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt >> index 4e23d73cdca..bccaec7a963 100644 >> --- a/Documentation/config/extensions.txt >> +++ b/Documentation/config/extensions.txt >> @@ -6,3 +6,34 @@ extensions.objectFormat:: >> Note that this setting should only be set by linkgit:git-init[1] or >> linkgit:git-clone[1]. Trying to change it after initialization will not >> work and will produce hard-to-diagnose issues. >> + >> +extensions.worktreeConfig:: >> + If enabled, then worktrees will load config settings from the >> + `$GIT_DIR/config.worktree` file in addition to the >> + `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and >> + `$GIT_DIR` are the same for the main working tree, while other >> + working trees have `$GIT_DIR` equal to >> + `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the > > The mixed use of "worktree" and "working tree" in this paragraph > might confuse readers into thinking that the paragraph is being > careful to make distinction between the two. All references to > "working tree" in the above paragraph should actually be "worktree", > I would think. I generally agree. This was changed in the most-recent re-roll based on a request by Eric [1]. I'm happy to take whichever version the two of you settle on. [1] https://lore.kernel.org/git/CAPig+cS-3CxxyPGcy_vkeN_WYTRo1b-ZhJNdPy8ARZSNKkF1Xg@mail.gmail.com/ > Side note: "working tree" is in the glossary-content.txt, > but "worktree", which is one "working tree" + repository > metadata (i.e. ".git/") that may be partially shared with > other "worktree"s of a single repository, is not defined. > > This is a tangent, but I wonder why we chose to use a different > filename (i.e. not "config" but "config.worktree") for this. If we > were redoing multi-worktree support from scratch, we would not reuse > the $GIT_DIR used by the primary worktree as $GIT_COMMON_DIR, so > that all worktrees would share a single $GIT_COMMON_DIR and > $GIT_COMMON_DIR/config that has stuff that is shared among all the > worktrees, while per worktree stuff is in $GIT_DIR/config even for > the primary worktree. But that is all water under the bridge now. Right. I think that since the primary worktree uses $GIT_COMMON_DIR as its location for base information (like HEAD) it also means that its worktree-specific config file cannot be called "config". Perhaps there could have been a way to split the worktrees so the primary worktree got its own directory within ".git/worktrees/", but my guess is that the design optimized for backwards compatibility: Git clients that don't understand worktrees could still interact with the primary worktree. > Other than the terminology gotcha, looked sensible. Migrating > automatically and/or noticing a suspicious setting may be needed to > help end users, but that would not be within the scope of this step. > > Attached is a "how about this?" glossary update suggestion. Most of > the existing mention of "working tree" are fine as-is because they > only care about what is in the "working tree", but some should be > changed to "worktree" to stress the fact that they care not just the > "working tree" part but also the repository metadata part that is > associated with that single "working tree". The first hunk says > worktree but it is clear that it is interested only in the "working > tree" files. > > Documentation/glossary-content.txt | 13 +++++++++++-- > 1 file changed, 11 insertions(+), 2 deletions(-) > > diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt > index c077971335..d816512c6a 100644 > --- c/Documentation/glossary-content.txt > +++ w/Documentation/glossary-content.txt > @@ -312,7 +312,7 @@ Pathspecs are used on the command line of "git ls-files", "git > ls-tree", "git add", "git grep", "git diff", "git checkout", > and many other commands to > limit the scope of operations to some subset of the tree or > -worktree. See the documentation of each command for whether > +working tree. See the documentation of each command for whether > paths are relative to the current directory or toplevel. The > pathspec syntax is as follows: > + > @@ -446,7 +446,7 @@ exclude;; > interface than the <<def_plumbing,plumbing>>. > > [[def_per_worktree_ref]]per-worktree ref:: > - Refs that are per-<<def_working_tree,worktree>>, rather than > + Refs that are per-<<def_worktree,worktree>>, rather than > global. This is presently only <<def_HEAD,HEAD>> and any refs > that start with `refs/bisect/`, but might later include other > unusual refs. > @@ -669,3 +669,12 @@ The most notable example is `HEAD`. > The tree of actual checked out files. The working tree normally > contains the contents of the <<def_HEAD,HEAD>> commit's tree, > plus any local changes that you have made but not yet committed. > + > +[[def_work_tree]]worktree:: > + A repository can have zero (i.e. bare repository) or one or > + more worktrees attached to it. One "worktree" consists of a > + "working tree" and repository metadata, most of which are > + shared among other worktrees of a single repository, and > + some of which are maintained separately per worktree > + (e.g. the index, HEAD, per-worktree refs and per-worktree > + configuration file) I like this addition, except that I don't understand the "per-worktree refs" (other than HEAD). Are there other thins used by features such as merge and rebase that would appear as worktree-specific? Of course, some state for these operations is stored per-worktree, I just didn't know if any were actually "refs". Other than that technicality, which could be completely correct, this is a good idea to include. Thanks, -Stolee
Derrick Stolee <stolee@gmail.com> writes: >> +[[def_work_tree]]worktree:: >> + A repository can have zero (i.e. bare repository) or one or >> + more worktrees attached to it. One "worktree" consists of a >> + "working tree" and repository metadata, most of which are >> + shared among other worktrees of a single repository, and >> + some of which are maintained separately per worktree >> + (e.g. the index, HEAD, per-worktree refs and per-worktree >> + configuration file) > > I like this addition, except that I don't understand the "per-worktree > refs" (other than HEAD). Are there other thins used by features such > as merge and rebase that would appear as worktree-specific? Of course, > some state for these operations is stored per-worktree, I just didn't > know if any were actually "refs". "per-worktree ref" is an entry in the glossary. [[def_per_worktree_ref]]per-worktree ref:: Refs that are per-<<def_working_tree,worktree>>, rather than global. This is presently only <<def_HEAD,HEAD>> and any refs that start with `refs/bisect/`, but might later include other unusual refs. And those other things are also listed as "pseudoref". [[def_pseudoref]]pseudoref:: Pseudorefs are a class of files under `$GIT_DIR` which behave like refs for the purposes of rev-parse, but which are treated specially by git... I think the motivation of special casing refs/bisect/ is to allow use of a separate worktree for bisecting without affecting other development or another bisection. The HEAD is singled out in the description, but MERGE_HEAD and others (pseudoref) that are declared here to be files under '$GIT_DIR', when we migrate fully to other backend that may not want to have files under '$GIT_DIR' to represent them, ought to become per-worktree, for the same reason as HEAD should be per-worktree, i.e. it allows worktrees to be independent from each other and have their checkout at different commits, growing history of different branches in parallel.
On 2/9/2022 12:19 PM, Junio C Hamano wrote: > Derrick Stolee <stolee@gmail.com> writes: > >>> +[[def_work_tree]]worktree:: >>> + A repository can have zero (i.e. bare repository) or one or >>> + more worktrees attached to it. One "worktree" consists of a >>> + "working tree" and repository metadata, most of which are >>> + shared among other worktrees of a single repository, and >>> + some of which are maintained separately per worktree >>> + (e.g. the index, HEAD, per-worktree refs and per-worktree >>> + configuration file) >> >> I like this addition, except that I don't understand the "per-worktree >> refs" (other than HEAD). Are there other thins used by features such >> as merge and rebase that would appear as worktree-specific? Of course, >> some state for these operations is stored per-worktree, I just didn't >> know if any were actually "refs". > > "per-worktree ref" is an entry in the glossary. > > [[def_per_worktree_ref]]per-worktree ref:: > Refs that are per-<<def_working_tree,worktree>>, rather than > global. This is presently only <<def_HEAD,HEAD>> and any refs > that start with `refs/bisect/`, but might later include other > unusual refs. > > And those other things are also listed as "pseudoref". > > [[def_pseudoref]]pseudoref:: > Pseudorefs are a class of files under `$GIT_DIR` which behave > like refs for the purposes of rev-parse, but which are treated > specially by git... > > I think the motivation of special casing refs/bisect/ is to allow > use of a separate worktree for bisecting without affecting other > development or another bisection. The HEAD is singled out in the > description, but MERGE_HEAD and others (pseudoref) that are declared > here to be files under '$GIT_DIR', when we migrate fully to other > backend that may not want to have files under '$GIT_DIR' to > represent them, ought to become per-worktree, for the same reason as > HEAD should be per-worktree, i.e. it allows worktrees to be > independent from each other and have their checkout at different > commits, growing history of different branches in parallel. Thanks for this additional context! It means that I need to look around more carefully, not that your patch needs any changes. -Stolee
On Wed, Feb 9, 2022 at 9:19 AM Junio C Hamano <gitster@pobox.com> wrote: > > Derrick Stolee <stolee@gmail.com> writes: > > >> +[[def_work_tree]]worktree:: > >> + A repository can have zero (i.e. bare repository) or one or > >> + more worktrees attached to it. One "worktree" consists of a > >> + "working tree" and repository metadata, most of which are > >> + shared among other worktrees of a single repository, and > >> + some of which are maintained separately per worktree > >> + (e.g. the index, HEAD, per-worktree refs and per-worktree > >> + configuration file) > > > > I like this addition, except that I don't understand the "per-worktree > > refs" (other than HEAD). Are there other thins used by features such > > as merge and rebase that would appear as worktree-specific? Of course, > > some state for these operations is stored per-worktree, I just didn't > > know if any were actually "refs". > > "per-worktree ref" is an entry in the glossary. > > [[def_per_worktree_ref]]per-worktree ref:: > Refs that are per-<<def_working_tree,worktree>>, rather than > global. This is presently only <<def_HEAD,HEAD>> and any refs > that start with `refs/bisect/`, but might later include other > unusual refs. > > And those other things are also listed as "pseudoref". > > [[def_pseudoref]]pseudoref:: > Pseudorefs are a class of files under `$GIT_DIR` which behave > like refs for the purposes of rev-parse, but which are treated > specially by git... > > I think the motivation of special casing refs/bisect/ is to allow > use of a separate worktree for bisecting without affecting other > development or another bisection. The HEAD is singled out in the > description, but MERGE_HEAD and others (pseudoref) that are declared > here to be files under '$GIT_DIR', when we migrate fully to other > backend that may not want to have files under '$GIT_DIR' to > represent them, ought to become per-worktree, for the same reason as > HEAD should be per-worktree, i.e. it allows worktrees to be > independent from each other and have their checkout at different > commits, growing history of different branches in parallel. You had me worried for a second; things would be really broken if these pseudorefs weren't per-worktree. But testing just now, I think the pseudorefs are already per-worktree. I just did a merge in a secondary worktree, and then observed from the primary worktree that a .git/worktrees/<id>/MERGE_HEAD was created, not a .git/MERGE_HEAD. (Maybe the glossary could just spell out that these are under $GIT_DIR and _not_ $GIT_COMMON_DIR to avoid potential confusion?)
On Tue, Feb 8, 2022 at 2:20 PM Junio C Hamano <gitster@pobox.com> wrote: > > "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes: > > > diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt > > index 4e23d73cdca..bccaec7a963 100644 > > --- a/Documentation/config/extensions.txt > > +++ b/Documentation/config/extensions.txt > > @@ -6,3 +6,34 @@ extensions.objectFormat:: > > Note that this setting should only be set by linkgit:git-init[1] or > > linkgit:git-clone[1]. Trying to change it after initialization will not > > work and will produce hard-to-diagnose issues. > > + > > +extensions.worktreeConfig:: > > + If enabled, then worktrees will load config settings from the > > + `$GIT_DIR/config.worktree` file in addition to the > > + `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and > > + `$GIT_DIR` are the same for the main working tree, while other > > + working trees have `$GIT_DIR` equal to > > + `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the > > The mixed use of "worktree" and "working tree" in this paragraph > might confuse readers into thinking that the paragraph is being > careful to make distinction between the two. All references to > "working tree" in the above paragraph should actually be "worktree", > I would think. > > Side note: "working tree" is in the glossary-content.txt, > but "worktree", which is one "working tree" + repository > metadata (i.e. ".git/") that may be partially shared with > other "worktree"s of a single repository, is not defined. > > This is a tangent, but I wonder why we chose to use a different > filename (i.e. not "config" but "config.worktree") for this. If we > were redoing multi-worktree support from scratch, we would not reuse > the $GIT_DIR used by the primary worktree as $GIT_COMMON_DIR, so > that all worktrees would share a single $GIT_COMMON_DIR and > $GIT_COMMON_DIR/config that has stuff that is shared among all the > worktrees, while per worktree stuff is in $GIT_DIR/config even for > the primary worktree. But that is all water under the bridge now. > > Other than the terminology gotcha, looked sensible. Migrating > automatically and/or noticing a suspicious setting may be needed to > help end users, but that would not be within the scope of this step. > > Attached is a "how about this?" glossary update suggestion. Most of > the existing mention of "working tree" are fine as-is because they > only care about what is in the "working tree", but some should be > changed to "worktree" to stress the fact that they care not just the > "working tree" part but also the repository metadata part that is > associated with that single "working tree". The first hunk says > worktree but it is clear that it is interested only in the "working > tree" files. > > Documentation/glossary-content.txt | 13 +++++++++++-- > 1 file changed, 11 insertions(+), 2 deletions(-) > > diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt > index c077971335..d816512c6a 100644 > --- c/Documentation/glossary-content.txt > +++ w/Documentation/glossary-content.txt > @@ -312,7 +312,7 @@ Pathspecs are used on the command line of "git ls-files", "git > ls-tree", "git add", "git grep", "git diff", "git checkout", > and many other commands to > limit the scope of operations to some subset of the tree or > -worktree. See the documentation of each command for whether > +working tree. See the documentation of each command for whether > paths are relative to the current directory or toplevel. The > pathspec syntax is as follows: > + > @@ -446,7 +446,7 @@ exclude;; > interface than the <<def_plumbing,plumbing>>. > > [[def_per_worktree_ref]]per-worktree ref:: > - Refs that are per-<<def_working_tree,worktree>>, rather than > + Refs that are per-<<def_worktree,worktree>>, rather than > global. This is presently only <<def_HEAD,HEAD>> and any refs > that start with `refs/bisect/`, but might later include other > unusual refs. > @@ -669,3 +669,12 @@ The most notable example is `HEAD`. > The tree of actual checked out files. The working tree normally > contains the contents of the <<def_HEAD,HEAD>> commit's tree, > plus any local changes that you have made but not yet committed. > + > +[[def_work_tree]]worktree:: > + A repository can have zero (i.e. bare repository) or one or > + more worktrees attached to it. One "worktree" consists of a > + "working tree" and repository metadata, most of which are > + shared among other worktrees of a single repository, and > + some of which are maintained separately per worktree > + (e.g. the index, HEAD, per-worktree refs and per-worktree > + configuration file) We could also add pseudorefs to the list of things maintained separately in the final parenthetical comment, but otherwise looks good.
Elijah Newren <newren@gmail.com> writes: > But testing just now, I think the pseudorefs are already per-worktree. > I just did a merge in a secondary worktree, and then observed from the > primary worktree that a .git/worktrees/<id>/MERGE_HEAD was created, > not a .git/MERGE_HEAD. (Maybe the glossary could just spell out that > these are under $GIT_DIR and _not_ $GIT_COMMON_DIR to avoid potential > confusion?) I actually think the longer-term direction is to describe that these are always per-worktree, without referring to $GIT_DIR or giving any hints that these may be represented as a file in the filesystem. That would leave the door open for the reftable backend to take them over as well as the normal refs.
Elijah Newren <newren@gmail.com> writes: >> [[def_per_worktree_ref]]per-worktree ref:: >> - Refs that are per-<<def_working_tree,worktree>>, rather than >> + Refs that are per-<<def_worktree,worktree>>, rather than >> global. This is presently only <<def_HEAD,HEAD>> and any refs >> that start with `refs/bisect/`, but might later include other >> unusual refs. >> @@ -669,3 +669,12 @@ The most notable example is `HEAD`. >> The tree of actual checked out files. The working tree normally >> contains the contents of the <<def_HEAD,HEAD>> commit's tree, >> plus any local changes that you have made but not yet committed. >> + >> +[[def_work_tree]]worktree:: >> + A repository can have zero (i.e. bare repository) or one or >> + more worktrees attached to it. One "worktree" consists of a >> + "working tree" and repository metadata, most of which are >> + shared among other worktrees of a single repository, and >> + some of which are maintained separately per worktree >> + (e.g. the index, HEAD, per-worktree refs and per-worktree >> + configuration file) > > We could also add pseudorefs to the list of things maintained > separately in the final parenthetical comment, but otherwise looks > good. I think what needs updating is the per_worktree_ref section. Before we say "later include other unusual refs", not so unusual pseudorefs can be mentioned there.
On Tue, Feb 8, 2022 at 9:34 PM Derrick Stolee <stolee@gmail.com> wrote: > On 2/8/2022 5:20 PM, Junio C Hamano wrote: > > "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> +extensions.worktreeConfig:: > >> + If enabled, then worktrees will load config settings from the > >> + `$GIT_DIR/config.worktree` file in addition to the > >> + `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and > >> + `$GIT_DIR` are the same for the main working tree, while other > >> + working trees have `$GIT_DIR` equal to > >> + `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the > > > > The mixed use of "worktree" and "working tree" in this paragraph > > might confuse readers into thinking that the paragraph is being > > careful to make distinction between the two. All references to > > "working tree" in the above paragraph should actually be "worktree", > > I would think. > > I generally agree. This was changed in the most-recent re-roll > based on a request by Eric [1]. I'm happy to take whichever > version the two of you settle on. > > [1] https://lore.kernel.org/git/CAPig+cS-3CxxyPGcy_vkeN_WYTRo1b-ZhJNdPy8ARZSNKkF1Xg@mail.gmail.com/ "request" is perhaps too strong a word considering that I led in with: A few minor comments, which can be addressed later or not at all, and likely are not worth holding up the series... I mentioned "worktree vs. working tree" only to point out the terminology inconsistency being introduced by the new patch; the same sort of inconsistency which had bothered Michael Haggerty enough to do something about it in bc483285b7 (Documentation/git-worktree: consistently use term "linked working tree", 2015-07-20). I, personally, prefer the term "worktree" for both convenience and because it better encapsulates the overall "thing" which is manipulated by the git-worktree command unlike the term "working tree" which, as Junio points out, has (perhaps) a more narrow meaning. As such, I would not be opposed to a patch series which changes "working tree" to "worktree" in documentation where appropriate, but that's outside the scope of this series.
Eric Sunshine <sunshine@sunshineco.com> writes: >> I generally agree. This was changed in the most-recent re-roll >> based on a request by Eric [1]. I'm happy to take whichever >> version the two of you settle on. >> >> [1] https://lore.kernel.org/git/CAPig+cS-3CxxyPGcy_vkeN_WYTRo1b-ZhJNdPy8ARZSNKkF1Xg@mail.gmail.com/ > > "request" is perhaps too strong a word considering that I led in with: > > A few minor comments, which can be addressed later or not > at all, and likely are not worth holding up the series... > > I mentioned "worktree vs. working tree" only to point out the > terminology inconsistency being introduced by the new patch; the same > sort of inconsistency which had bothered Michael Haggerty enough to do > something about it in bc483285b7 (Documentation/git-worktree: > consistently use term "linked working tree", 2015-07-20). Yup, it seems both of us found mixed use of these two terms disturbing. Michael's old commit was mostly about "worktree" vs "working tree", even though 2 changes among 13 changes to the file were about updating "working directory" to "working tree", and to me it seems to made the terminology straightened up. E.g. a hunk from the change uses "a linked working tree and its administrative files" -- `remove` to remove a linked worktree and its administrative files (and - warn if the worktree is dirty) -- `mv` to move or rename a worktree and update its administrative files -- `list` to list linked worktrees +- `remove` to remove a linked working tree and its administrative files (and + warn if the working tree is dirty) +- `mv` to move or rename a working tree and update its administrative files +- `list` to list linked working trees - `lock` to prevent automatic pruning of administrative files (for instance, - for a worktree on a portable device) + for a working tree on a portable device) which clearly refers to things above .git as "working tree". > I, personally, prefer the term "worktree" for both convenience and > because it better encapsulates the overall "thing" which is > manipulated by the git-worktree command unlike the term "working tree" > which, as Junio points out, has (perhaps) a more narrow meaning. As > such, I would not be opposed to a patch series which changes "working > tree" to "worktree" in documentation where appropriate, but that's > outside the scope of this series. I would welcome such changes where appropriate in both directions (I think I updated a few places in the glossary). I agree that this topic is not a place to do so.
diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt index 4e23d73cdca..bccaec7a963 100644 --- a/Documentation/config/extensions.txt +++ b/Documentation/config/extensions.txt @@ -6,3 +6,34 @@ extensions.objectFormat:: Note that this setting should only be set by linkgit:git-init[1] or linkgit:git-clone[1]. Trying to change it after initialization will not work and will produce hard-to-diagnose issues. + +extensions.worktreeConfig:: + If enabled, then worktrees will load config settings from the + `$GIT_DIR/config.worktree` file in addition to the + `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and + `$GIT_DIR` are the same for the main working tree, while other + working trees have `$GIT_DIR` equal to + `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the + `config.worktree` file will override settings from any other + config files. ++ +When enabling `extensions.worktreeConfig`, you must be careful to move +certain values from the common config file to the main working tree's +`config.worktree` file, if present: ++ +* `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to + `$GIT_COMMON_DIR/config.worktree`. +* If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config` + to `$GIT_COMMON_DIR/config.worktree`. ++ +It may also be beneficial to adjust the locations of `core.sparseCheckout` +and `core.sparseCheckoutCone` depending on your desire for customizable +sparse-checkout settings for each worktree. By default, the `git +sparse-checkout` builtin enables `extensions.worktreeConfig`, assigns +these config values on a per-worktree basis, and uses the +`$GIT_DIR/info/sparse-checkout` file to specify the sparsity for each +worktree independently. See linkgit:git-sparse-checkout[1] for more +details. ++ +For historical reasons, `extensions.worktreeConfig` is respected +regardless of the `core.repositoryFormatVersion` setting. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 2285effb363..bdcfd94b642 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -141,9 +141,13 @@ from all available files. See also <<FILES>>. --worktree:: - Similar to `--local` except that `.git/config.worktree` is + Similar to `--local` except that `$GIT_DIR/config.worktree` is read from or written to if `extensions.worktreeConfig` is - present. If not it's the same as `--local`. + enabled. If not it's the same as `--local`. Note that `$GIT_DIR` + is equal to `$GIT_COMMON_DIR` for the main working tree, but is of + the form `$GIT_DIR/worktrees/<id>/` for other working trees. See + linkgit:git-worktree[1] to learn how to enable + `extensions.worktreeConfig`. -f <config-file>:: --file <config-file>:: diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 9e862fbcf79..b8d53c48303 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -286,8 +286,8 @@ CONFIGURATION FILE ------------------ By default, the repository `config` file is shared across all working trees. If the config variables `core.bare` or `core.worktree` are -already present in the config file, they will be applied to the main -working trees only. +present in the common config file and `extensions.worktreeConfig` is +disabled, then they will be applied to the main working tree only. In order to have configuration specific to working trees, you can turn on the `worktreeConfig` extension, e.g.: @@ -307,11 +307,16 @@ them to the `config.worktree` of the main working tree. You may also take this opportunity to review and move other configuration that you do not want to share to all working trees: - - `core.worktree` and `core.bare` should never be shared + - `core.worktree` should never be shared. + + - `core.bare` should not be shared if the value is `core.bare=true`. - `core.sparseCheckout` is recommended per working tree, unless you are sure you always use sparse checkout for all working trees. +See the documentation of `extensions.worktreeConfig` in +linkgit:git-config[1] for more details. + DETAILS ------- Each linked working tree has a private sub-directory in the repository's