[PATCH v2 00/11] Updates to worktree code and docs

From: Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com>
Date: Feb 22, 2022, 00:17 UTC
Message-ID: <pull.1154.v2.git.1645489080.gitgitgadget@gmail.com>
In-Reply-To: <pull.1154.git.1645379667.gitgitgadget@gmail.com>

This is built on top of ds/sparse-checkout-requires-per-worktree-config and includes some forward fixes for comments from that series.

 * Patch 1 combines two translatable messages into one. (Thanks, Jean-Noël)
 * Patches 2-4 extract methods from the already-busy add_worktree() method.
   (Thanks, Eric)
 * Patches 5-11 update git-worktree.txt to use 'worktree' over 'working
   tree'. This involves some rewrapping of the paragraphs, so the diffs are
   not obviously just a find and replace. I split the changes mostly by
   section of the file to keep the diffs from being too large.

Updates in v2 =============

Based on Junio and Taylor's review, I updated some language in the docs:

 * Some uses of "worktree" should have stayed as "working tree"
 * Some adjacent wording was improved.

Thanks, -Stolee

Derrick Stolee (11):
  worktree: combine two translatable messages
  worktree: extract copy_filtered_worktree_config()
  worktree: extract copy_sparse_checkout()
  worktree: extract checkout_worktree()
  worktree: use 'worktree' over 'working tree'
  worktree: use 'worktree' over 'working tree'
  worktree: use 'worktree' over 'working tree'
  worktree: use 'worktree' over 'working tree'
  worktree: use 'worktree' over 'working tree'
  worktree: use 'worktree' over 'working tree'
  worktree: use 'worktree' over 'working tree'

 Documentation/git-worktree.txt | 268 ++++++++++++++++-----------------
 builtin/worktree.c             | 138 +++++++++--------
 2 files changed, 209 insertions(+), 197 deletions(-)

base-commit: 3ce113827287079dced9aaf9c5d1e1734ecaa265
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1154%2Fderrickstolee%2Fworktree-forward-fixes-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1154/derrickstolee/worktree-forward-fixes-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1154

Range-diff vs v1:

1: a113ed9a844 = 1: a113ed9a844 worktree: combine two translatable messages
2: f8aa87112a8 = 2: f8aa87112a8 worktree: extract copy_filtered_worktree_config()
3: ccc5b1ef9fb = 3: ccc5b1ef9fb worktree: extract copy_sparse_checkout()
4: 1e62e4e4fa1 = 4: 1e62e4e4fa1 worktree: extract checkout_worktree()
5: a6a8eb8e7bb ! 5: 2801ae232ae worktree: use 'worktree' over 'working tree'
@@ Commit message
This is the first of multiple changes to git-worktree.txt, restricted to
the DESCRIPTION section.

+ Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>

## Documentation/git-worktree.txt ##
@@ Documentation/git-worktree.txt: Manage multiple working trees attached to the sa
-'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
@@ Documentation/git-worktree.txt: Manage multiple working trees attached to the sa
+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
+
+ If a working tree 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
@@ Documentation/git-worktree.txt: Manage multiple working trees attached to the sa
-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.
++If the working tree for a 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
--------
@@ Documentation/git-worktree.txt: Manage multiple working trees attached to the sa
-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
++Create a worktree at `<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}`.
6: 1fc4a98dc7a ! 6: a375e4b6ff0 worktree: use 'worktree' over 'working tree'
@@ Commit message
This is the second of multiple changes to git-worktree.txt, restricted
to the COMMANDS section.

+ There is some language around the movement of "the working tree of a
+ linked worktree" which is used once, but the remaining uses are left as
+ just moving "a linked worktree" for brevity.
+
+ Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>

## Documentation/git-worktree.txt ##
@@ Documentation/git-worktree.txt: branches from there if `<branch>` is ambiguous b
-reestablish the connection. If multiple linked working trees are moved,
-running `repair` from any working tree with each tree's new `<path>` as
-an argument, will reestablish the connection to all the specified paths.
-+Similarly, if a linked worktree is moved without using `git worktree
-+move`, the main worktree (or bare repository) will be unable to locate it.
-+Running `repair` within the recently-moved worktree will reestablish the
-+connection. If multiple linked worktrees are moved, running `repair` from
-+any worktree with each tree's new `<path>` as an argument, will
-+reestablish the connection to all the specified paths.
++Similarly, if the working directory for a linked worktree is moved without
++using `git worktree move`, the main worktree (or bare repository) will be
++unable to locate it. Running `repair` within the recently-moved worktree
++will reestablish the connection. If multiple linked worktrees are moved,
++running `repair` from any worktree with each tree's new `<path>` as an
++argument, will reestablish the connection to all the specified paths.
+
-If both the main working tree and linked working trees have been moved
-manually, then running `repair` in the main working tree and specifying the
7: 00d261d0a2a = 7: d1c4b687cbc worktree: use 'worktree' over 'working tree'
8: e7e579d2995 ! 8: 65a0cd52711 worktree: use 'worktree' over 'working tree'
@@ Commit message
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 <m3@ttaylorr.com>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>

## Documentation/git-worktree.txt ##
@@ Documentation/git-worktree.txt: have two worktrees, at `/abc/def/ghi` and `/abc/
-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.
++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-worktree and all refs starting with
+`refs/` are shared. Pseudo refs are ones like `HEAD` which are directly
9: 23e74c87116 ! 9: e8890134fb4 worktree: use 'worktree' over 'working tree'
@@ Commit message
This is the fifth of multiple changes to git-worktree.txt, restricted to
the CONFIGURATION FILE section.

+ While here, clear up some language to improve readability.
+
+ Helped-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>

## Documentation/git-worktree.txt ##
@@ Documentation/git-worktree.txt: which will handle refs correctly.
+will be applied to the main worktree only.

-In order to have configuration specific to working trees, you can turn
-+In order to have configuration specific to worktrees, you can turn
- on the `worktreeConfig` extension, e.g.:
+-on the `worktreeConfig` extension, e.g.:
++In order to have worktree-specific configuration, you can turn on the
++`worktreeConfig` extension, e.g.:

------------
+ $ git config extensions.worktreeConfig true
@@ Documentation/git-worktree.txt: versions will refuse to access repositories with this extension.

Note that in this file, the exception for `core.bare` and `core.worktree`
@@ Documentation/git-worktree.txt: versions will refuse to access repositories with

- - `core.sparseCheckout` is recommended per working tree, unless you
- are sure you always use sparse checkout for all working trees.
-+ - `core.sparseCheckout` is recommended per worktree, unless you are sure
-+ you always use sparse checkout for all worktrees.
++ - `core.sparseCheckout` should not be shared, unless you are sure you
++ always use sparse checkout for all worktrees.

See the documentation of `extensions.worktreeConfig` in
linkgit:git-config[1] for more details.
10: 4729a96af6e = 10: 75f0e4ff5c2 worktree: use 'worktree' over 'working tree'
11: 91773337675 ! 11: 1e07383552a worktree: use 'worktree' over 'working tree'
@@ Commit message
This is the last of multiple changes to git-worktree.txt, starting at
the LIST OUTPUT FORMAT section.

+ The EXAMPLES section has an instance of "working tree" that must stay as
+ it is, because it is not talking about a worktree, but an example of why
+ a user might want to create a worktree.
+
+ Helped-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>

## Documentation/git-worktree.txt ##
@@ Documentation/git-worktree.txt: label and value separated by a single space. Bo
end of the record. For example:

------------
-@@ Documentation/git-worktree.txt: EXAMPLES
- You are in the middle of a refactoring session and your boss comes in and
- demands that you fix something immediately. You might typically use
+@@ Documentation/git-worktree.txt: demands that you fix something immediately. You might typically use
linkgit:git-stash[1] to store your changes away temporarily, however, your
--working tree is in such a state of disarray (with new, moved, and removed
-+worktree is in such a state of disarray (with new, moved, and removed
+ working tree is in such a state of disarray (with new, moved, and removed
files, and other bits and pieces strewn around) that you don't want to risk
-disturbing any of it. Instead, you create a temporary linked working tree to
+disturbing any of it. Instead, you create a temporary linked worktree to

-- 
gitgitgadget