| Message ID | a6a8eb8e7bb4520bfe37d3a79329cce7886af59c.1645379667.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Updates to worktree code and docs | expand |
"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes: > 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 first of multiple changes to git-worktree.txt, restricted to > the DESCRIPTION section. Looked almost perfect, except for one and a half iffy parts. > -If a working tree is deleted without using `git worktree remove`, then > ... > +If a worktree is deleted without using `git worktree remove`, then > its associated administrative files, which reside in the repository > (see "DETAILS" below), will eventually be removed automatically (see I think this one should be "working tree". The administrative files are integral part of a worktree, but from the point of view of a working tree, it is "associated" with it and not part of it. If you delete without using "git worktree remove", that would be done with a command like "rm -f", which removes the working tree but not the worktree. > -If a linked working tree is stored on a portable device or network share > -which is not always mounted, you can prevent its administrative files from > -being pruned by issuing the `git worktree lock` command, optionally > -specifying `--reason` to explain why the working tree is locked. > +If a linked worktree is stored on a portable device or network share which > +is not always mounted, you can prevent its administrative files from being > +pruned by issuing the `git worktree lock` command, optionally specifying > +`--reason` to explain why the worktree is locked. This one, because what is on a removal device is the working tree half of a worktree that leaves the "administrative files" half still on the mothership when it is removed, I think it is OK to call it a working tree, but because we defined "a linked worktree" and removed the definition of "a linked working tree" earlier, the original as-is won't work well. "If the working tree portion of a linked worktree is stored on ..." may be more correct, but it is a bit mouthful. I dunno (hence this is not even a full "iffy" part, just halfway iffy). > add <path> [<commit-ish>]:: > > -Create `<path>` and checkout `<commit-ish>` into it. The new working directory > -is linked to the current repository, sharing everything except working > -directory specific files such as `HEAD`, `index`, etc. As a convenience, > -`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. > +Create `<path>` and checkout `<commit-ish>` into it. The new worktree > +is linked to the current repository, sharing everything except per-worktree > +files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may > +be a bare "`-`", which is synonymous with `@{-1}`. The original has the problem, too, but it is unclear what is created at <path> by reading only the first sentence, even though the mention of "The new worktree" that immediately follows strongly hints that we are creating a worktree. Create a new worktree at <path> and ... perhaps? This clarification is not even part of one and a half ;-)
On 2/20/2022 3:42 PM, Junio C Hamano wrote: > "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> 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 first of multiple changes to git-worktree.txt, restricted to >> the DESCRIPTION section. > > Looked almost perfect, except for one and a half iffy parts. > >> -If a working tree is deleted without using `git worktree remove`, then >> ... >> +If a worktree is deleted without using `git worktree remove`, then >> its associated administrative files, which reside in the repository >> (see "DETAILS" below), will eventually be removed automatically (see > > I think this one should be "working tree". The administrative files > are integral part of a worktree, but from the point of view of a > working tree, it is "associated" with it and not part of it. If you > delete without using "git worktree remove", that would be done with > a command like "rm -f", which removes the working tree but not the > worktree. Good point. I agree. There is some similar discussion in the COMMANDS section around moving/renaming/repairing worktrees, so likely similar thoughts apply there, too. >> -If a linked working tree is stored on a portable device or network share >> -which is not always mounted, you can prevent its administrative files from >> -being pruned by issuing the `git worktree lock` command, optionally >> -specifying `--reason` to explain why the working tree is locked. >> +If a linked worktree is stored on a portable device or network share which >> +is not always mounted, you can prevent its administrative files from being >> +pruned by issuing the `git worktree lock` command, optionally specifying >> +`--reason` to explain why the worktree is locked. > > This one, because what is on a removal device is the working tree > half of a worktree that leaves the "administrative files" half still > on the mothership when it is removed, I think it is OK to call it a > working tree, but because we defined "a linked worktree" and removed > the definition of "a linked working tree" earlier, the original as-is > won't work well. > > "If the working tree portion of a linked worktree is stored on ..." > may be more correct, but it is a bit mouthful. I dunno (hence this > is not even a full "iffy" part, just halfway iffy). I think the wordy way you say it here is the most correct way. Another way to approach this is to start at the definition by saying "We will refer to the location of a worktree to be its associated working directory, even though its metadata is stored in another location." That could allow us to use "worktree" even in these cases, but does create some overloading of the word. >> add <path> [<commit-ish>]:: >> >> -Create `<path>` and checkout `<commit-ish>` into it. The new working directory >> -is linked to the current repository, sharing everything except working >> -directory specific files such as `HEAD`, `index`, etc. As a convenience, >> -`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. >> +Create `<path>` and checkout `<commit-ish>` into it. The new worktree >> +is linked to the current repository, sharing everything except per-worktree >> +files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may >> +be a bare "`-`", which is synonymous with `@{-1}`. > > The original has the problem, too, but it is unclear what is created > at <path> by reading only the first sentence, even though the > mention of "The new worktree" that immediately follows strongly > hints that we are creating a worktree. > > Create a new worktree at <path> and ... > > perhaps? This clarification is not even part of one and a half ;-) This is a good change. Thanks, -Stolee
On 20/02/2022 17:54, 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. Doesn't this need a clear call-out in the text to highlight the distinction, so that it is obvious at first glance to the casual reader? I'd ended up with something like: - worktree A directory whose files and sub-directories are (selectively) under Git revision management. - working tree The working tree comprises Git revision management meta-data for the worktree, and the worktree itself. The meta-data may be independently located away from the worktree's data. The key feature is to have a layout structure that shows the distinction. Or are we trying to remove all references to "working tree"? Or have I misunderstood? Philip > > This is the first of multiple changes to git-worktree.txt, restricted to > the DESCRIPTION section. > > Signed-off-by: Derrick Stolee <derrickstolee@github.com> > --- > Documentation/git-worktree.txt | 53 ++++++++++++++++++---------------- > 1 file changed, 28 insertions(+), 25 deletions(-) > > diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt > index b8d53c48303..d9705062e9d 100644 > --- a/Documentation/git-worktree.txt > +++ b/Documentation/git-worktree.txt > @@ -25,45 +25,48 @@ Manage multiple working trees attached to the same repository. > > A git repository can support multiple working trees, allowing you to check Are we removing the above "working trees" phrases as well? > out more than one branch at a time. With `git worktree add` a new working > -tree is associated with the repository. This new working tree is called a > -"linked working tree" as opposed to the "main working tree" prepared by > -linkgit:git-init[1] or linkgit:git-clone[1]. > -A repository has one main working tree (if it's not a > -bare repository) and zero or more linked working trees. When you are done > -with a linked working tree, remove it with `git worktree remove`. > +tree is associated with the repository, along with additional metadata > +that differentiates that working tree from others in the same repository. > +The working tree, along with this metada, is called a "worktree". > + > +This new worktree is called a "linked worktree" as opposed to the "main > +worktree" prepared by linkgit:git-init[1] or linkgit:git-clone[1]. > +A repository has one main worktree (if it's not a bare repository) and > +zero or more linked worktrees. When you are done with a linked worktree, > +remove it with `git worktree remove`. > > In its simplest form, `git worktree add <path>` automatically creates a > new branch whose name is the final component of `<path>`, which is > convenient if you plan to work on a new topic. For instance, `git > worktree add ../hotfix` creates new branch `hotfix` and checks it out at > -path `../hotfix`. To instead work on an existing branch in a new working > -tree, use `git worktree add <path> <branch>`. On the other hand, if you > -just plan to make some experimental changes or do testing without > -disturbing existing development, it is often convenient to create a > -'throwaway' working tree not associated with any branch. For instance, > -`git worktree add -d <path>` creates a new working tree with a detached > -`HEAD` at the same commit as the current branch. > - > -If a working tree is deleted without using `git worktree remove`, then > +path `../hotfix`. To instead work on an existing branch in a new worktree, > +use `git worktree add <path> <branch>`. On the other hand, if you just > +plan to make some experimental changes or do testing without disturbing > +existing development, it is often convenient to create a 'throwaway' > +worktree not associated with any branch. For instance, > +`git worktree add -d <path>` creates a new worktree with a detached `HEAD` > +at the same commit as the current branch. > + > +If a worktree is deleted without using `git worktree remove`, then > its associated administrative files, which reside in the repository > (see "DETAILS" below), will eventually be removed automatically (see > `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run > -`git worktree prune` in the main or any linked working tree to > -clean up any stale administrative files. > +`git worktree prune` in the main or any linked worktree to clean up any > +stale administrative files. > > -If a linked working tree is stored on a portable device or network share > -which is not always mounted, you can prevent its administrative files from > -being pruned by issuing the `git worktree lock` command, optionally > -specifying `--reason` to explain why the working tree is locked. > +If a linked worktree is stored on a portable device or network share which > +is not always mounted, you can prevent its administrative files from being > +pruned by issuing the `git worktree lock` command, optionally specifying > +`--reason` to explain why the worktree is locked. > > COMMANDS > -------- > add <path> [<commit-ish>]:: > > -Create `<path>` and checkout `<commit-ish>` into it. The new working directory > -is linked to the current repository, sharing everything except working > -directory specific files such as `HEAD`, `index`, etc. As a convenience, > -`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. > +Create `<path>` and checkout `<commit-ish>` into it. The new worktree > +is linked to the current repository, sharing everything except per-worktree > +files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may > +be a bare "`-`", which is synonymous with `@{-1}`. > + > If `<commit-ish>` is a branch name (call it `<branch>`) and is not found, > and neither `-b` nor `-B` nor `--detach` are used, but there does
On 2/24/2022 9:33 AM, Philip Oakley wrote: > On 20/02/2022 17:54, 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. > Doesn't this need a clear call-out in the text to highlight the > distinction, so that it is obvious at first glance to the casual reader? > > I'd ended up with something like: > - worktree > A directory whose files and sub-directories are (selectively) under > Git revision management. > - working tree > The working tree comprises Git revision management meta-data for the > worktree, > and the worktree itself. > The meta-data may be independently located away from the worktree's > data. > > The key feature is to have a layout structure that shows the distinction. See below where I mention that the first paragraph points out this distinction. Your use of bullets makes it even more clear, and I think that would be more valuable if this wasn't the very first thing in the document. > Or are we trying to remove all references to "working tree"? Or have I > misunderstood? ... >> A git repository can support multiple working trees, allowing you to check > Are we removing the above "working trees" phrases as well? This one is important to keep. The worktree feature is how Git manages multiple working trees. The reason for switching most of the other references is because the discussion applies specifically to worktrees, not working trees. >> out more than one branch at a time. With `git worktree add` a new working >> -tree is associated with the repository. This new working tree is called a >> -"linked working tree" as opposed to the "main working tree" prepared by >> -linkgit:git-init[1] or linkgit:git-clone[1]. >> -A repository has one main working tree (if it's not a >> -bare repository) and zero or more linked working trees. When you are done >> -with a linked working tree, remove it with `git worktree remove`. >> +tree is associated with the repository, along with additional metadata >> +that differentiates that working tree from others in the same repository. >> +The working tree, along with this metada, is called a "worktree". This first paragraph is all about the distinction between working tree and worktree, so it hopefully handles the concerns you had above. Thanks, -Stolee
Sorry for the delay in replying. I had some family matters to attend to. On 24/02/2022 15:53, Derrick Stolee wrote: > On 2/24/2022 9:33 AM, Philip Oakley wrote: >> On 20/02/2022 17:54, 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. >> Doesn't this need a clear call-out in the text to highlight the >> distinction, so that it is obvious at first glance to the casual reader? >> >> I'd ended up with something like: >> - worktree >> A directory whose files and sub-directories are (selectively) under >> Git revision management. >> - working tree >> The working tree comprises Git revision management meta-data for the >> worktree, >> and the worktree itself. >> The meta-data may be independently located away from the worktree's >> data. >> >> The key feature is to have a layout structure that shows the distinction. > See below where I mention that the first paragraph points out this > distinction. Your use of bullets makes it even more clear, and I think > that would be more valuable if this wasn't the very first thing in the > document. I don't really buy the "first paragraph points out this distinction" because it's still part of a wall of text, so not easy to locate. It's not helped by the top line NAME which uses both `worktree` and `working tree` as if they are equivalent. Though that could be easily solved by making it: git-worktree - Manage multiple working trees and their meta-data which would highlight the two distinct parts. (could also add the `git/user` distinction as below) You'll probably also have noticed how even in my original suggestion, I'd still misread the partition and got worktree/working-tree swapped over, so it is easily done. If we are trying to have clarity on the worktree/working-tree distinction, I still think it needs to be made very obvious, with perhaps even the naming of the _git_ meta data part, or at least calling it out as being the independent of the _users_ working tree . Philip > >> Or are we trying to remove all references to "working tree"? Or have I >> misunderstood? > ... >>> A git repository can support multiple working trees, allowing you to check >> Are we removing the above "working trees" phrases as well? > This one is important to keep. The worktree feature is how Git manages > multiple working trees. > > The reason for switching most of the other references is because the > discussion applies specifically to worktrees, not working trees. > >>> out more than one branch at a time. With `git worktree add` a new working >>> -tree is associated with the repository. This new working tree is called a >>> -"linked working tree" as opposed to the "main working tree" prepared by >>> -linkgit:git-init[1] or linkgit:git-clone[1]. >>> -A repository has one main working tree (if it's not a >>> -bare repository) and zero or more linked working trees. When you are done >>> -with a linked working tree, remove it with `git worktree remove`. >>> +tree is associated with the repository, along with additional metadata >>> +that differentiates that working tree from others in the same repository. >>> +The working tree, along with this metada, is called a "worktree". > This first paragraph is all about the distinction between working tree > and worktree, so it hopefully handles the concerns you had above. > > Thanks, > -Stolee
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index b8d53c48303..d9705062e9d 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -25,45 +25,48 @@ Manage multiple working trees attached to the same repository. A git repository can support multiple working trees, allowing you to check out more than one branch at a time. With `git worktree add` a new working -tree is associated with the repository. This new working tree is called a -"linked working tree" as opposed to the "main working tree" prepared by -linkgit:git-init[1] or linkgit:git-clone[1]. -A repository has one main working tree (if it's not a -bare repository) and zero or more linked working trees. When you are done -with a linked working tree, remove it with `git worktree remove`. +tree is associated with the repository, along with additional metadata +that differentiates that working tree from others in the same repository. +The working tree, along with this metada, is called a "worktree". + +This new worktree is called a "linked worktree" as opposed to the "main +worktree" prepared by linkgit:git-init[1] or linkgit:git-clone[1]. +A repository has one main worktree (if it's not a bare repository) and +zero or more linked worktrees. When you are done with a linked worktree, +remove it with `git worktree remove`. In its simplest form, `git worktree add <path>` automatically creates a new branch whose name is the final component of `<path>`, which is convenient if you plan to work on a new topic. For instance, `git worktree add ../hotfix` creates new branch `hotfix` and checks it out at -path `../hotfix`. To instead work on an existing branch in a new working -tree, use `git worktree add <path> <branch>`. On the other hand, if you -just plan to make some experimental changes or do testing without -disturbing existing development, it is often convenient to create a -'throwaway' working tree not associated with any branch. For instance, -`git worktree add -d <path>` creates a new working tree with a detached -`HEAD` at the same commit as the current branch. - -If a working tree is deleted without using `git worktree remove`, then +path `../hotfix`. To instead work on an existing branch in a new worktree, +use `git worktree add <path> <branch>`. On the other hand, if you just +plan to make some experimental changes or do testing without disturbing +existing development, it is often convenient to create a 'throwaway' +worktree not associated with any branch. For instance, +`git worktree add -d <path>` creates a new worktree with a detached `HEAD` +at the same commit as the current branch. + +If a worktree is deleted without using `git worktree remove`, then its associated administrative files, which reside in the repository (see "DETAILS" below), will eventually be removed automatically (see `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run -`git worktree prune` in the main or any linked working tree to -clean up any stale administrative files. +`git worktree prune` in the main or any linked worktree to clean up any +stale administrative files. -If a linked working tree is stored on a portable device or network share -which is not always mounted, you can prevent its administrative files from -being pruned by issuing the `git worktree lock` command, optionally -specifying `--reason` to explain why the working tree is locked. +If a linked worktree is stored on a portable device or network share which +is not always mounted, you can prevent its administrative files from being +pruned by issuing the `git worktree lock` command, optionally specifying +`--reason` to explain why the worktree is locked. COMMANDS -------- add <path> [<commit-ish>]:: -Create `<path>` and checkout `<commit-ish>` into it. The new working directory -is linked to the current repository, sharing everything except working -directory specific files such as `HEAD`, `index`, etc. As a convenience, -`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. +Create `<path>` and checkout `<commit-ish>` into it. The new worktree +is linked to the current repository, sharing everything except per-worktree +files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may +be a bare "`-`", which is synonymous with `@{-1}`. + If `<commit-ish>` is a branch name (call it `<branch>`) and is not found, and neither `-b` nor `-B` nor `--detach` are used, but there does