[PATCH 0/6] Various tweaks to 'worktree'-related manpages

[PATCH 0/6] Various tweaks to 'worktree'-related manpages

[Michael Haggerty]

I haven't been following the discussion of this feature on the mailing
list, so I apologize if these changes overlap with any in-flight
patches, and these changes should definitely be checked over by
somebody more familiar with the feature. These patches mostly fix what
seem like inconsistencies in the documentation. The last patch
contains some wordsmithing. Feel free to squash them together if you
prefer.

This patch series is also available from my GitHub account [1] as
branch "worktree-docs".

[1] https://github.com/mhagger/git

Michael Haggerty (6):
  worktree: consistently use term "linked working tree" in manpages
  worktree: remove references to "git checkout --to" from the manpage
  worktree: fix incorrect references to file "locked"
  worktree: the "locked" mechanism is already implemented
  config.txt: refer to "git worktree prune", not "prune --worktree"
  worktree: wordsmith worktree-related manpages

 Documentation/config.txt               | 10 +++++-----
 Documentation/git-worktree.txt         | 20 +++++++++-----------
 Documentation/gitrepository-layout.txt | 22 +++++++++++-----------
 3 files changed, 25 insertions(+), 27 deletions(-)

-- 
2.1.4

[PATCH 1/6] worktree: consistently use term "linked working tree" in manpages

[Michael Haggerty]

Sometimes linked working trees were called "linked working
directories" or "linked worktrees". Always refer to them as "linked
working trees" for consistency.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
 Documentation/git-worktree.txt         | 10 +++++-----
 Documentation/gitrepository-layout.txt |  8 ++++----
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index da71f50..c8dd0e5 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -31,9 +31,9 @@ The working tree's administrative files in the repository (see
 `git worktree prune` in the main or any linked working tree to
 clean up any stale administrative files.
 
-If you move a linked working directory to another file system, or
+If you move a linked working tree to another file system, or
 within a file system that does not support hard links, you need to run
-at least one git command inside the linked working directory
+at least one git command inside the linked working tree
 (e.g. `git status`) in order to update its administrative files in the
 repository so that they do not get automatically pruned.
 
@@ -141,7 +141,7 @@ demands that you fix something immediately. You might typically use
 linkgit:git-stash[1] to store your changes away temporarily, however, your
 worktree 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 worktree to
+disturbing any of it. Instead, you create a temporary linked working tree to
 make the emergency fix, remove it when done, and then resume your earlier
 refactoring session.
 
@@ -163,10 +163,10 @@ recommended to make multiple checkouts of a superproject.
 git-worktree could provide more automation for tasks currently
 performed manually, such as:
 
-- `remove` to remove a linked worktree and its administrative files (and
+- `remove` to remove a linked working tree 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
+- `list` to list linked working trees
 - `lock` to prevent automatic pruning of administrative files (for instance,
   for a worktree on a portable device)
 
diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 7173b38..fe7fa96 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -252,8 +252,8 @@ modules::
 
 worktrees::
 	Contains worktree specific information of linked
-	checkouts. Each subdirectory contains the worktree-related
-	part of a linked checkout. This directory is ignored if
+	working trees. Each subdirectory contains the worktree-related
+	part of a linked working tree. This directory is ignored if
 	$GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/worktrees" will be
 	used instead.
 
@@ -265,9 +265,9 @@ worktrees/<id>/gitdir::
 	updated every time the linked repository is accessed.
 
 worktrees/<id>/locked::
-	If this file exists, the linked repository may be on a
+	If this file exists, the linked working tree may be on a
 	portable device and not available. It does not mean that the
-	linked repository is gone and `worktrees/<id>` could be
+	linked working tree is gone and `worktrees/<id>` could be
 	removed. The file's content contains a reason string on why
 	the repository is locked.
 
-- 
2.1.4

[PATCH 2/6] worktree: remove references to "git checkout --to" from the manpage

[Michael Haggerty]

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
 Documentation/git-worktree.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index c8dd0e5..707dfd0 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -18,7 +18,7 @@ DESCRIPTION
 Manage multiple worktrees 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 checkout --to` a new working
+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 "git
 init" or "git clone".  A repository has one main working tree (if it's not a
@@ -99,7 +99,7 @@ Each linked working tree has a private sub-directory in the repository's
 $GIT_DIR/worktrees directory.  The private sub-directory's name is usually
 the base name of the linked working tree's path, possibly appended with a
 number to make it unique.  For example, when `$GIT_DIR=/path/main/.git` the
-command `git checkout --to /path/other/test-next next` creates the linked
+command `git worktree add /path/other/test-next next` creates the linked
 working tree in `/path/other/test-next` and also creates a
 `$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
 if `test-next` is already taken).
-- 
2.1.4

[PATCH 3/6] worktree: fix incorrect references to file "locked"

[Michael Haggerty]

The manpage referred to file "lock" in a couple of places. The file is
actually called "locked".

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
 Documentation/git-worktree.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 707dfd0..6cb3877 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -39,7 +39,7 @@ repository so that they do not get automatically pruned.
 
 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 creating a file named 'lock' alongside the other
+being pruned by creating a file named 'locked' alongside the other
 administrative files, optionally containing a plain text reason that
 pruning should be suppressed. See section "DETAILS" for more information.
 
@@ -167,7 +167,7 @@ performed manually, such as:
   warn if the worktree is dirty)
 - `mv` to move or rename a worktree and update its administrative files
 - `list` to list linked working trees
-- `lock` to prevent automatic pruning of administrative files (for instance,
+- `locked` to prevent automatic pruning of administrative files (for instance,
   for a worktree on a portable device)
 
 GIT
-- 
2.1.4

[PATCH 4/6] worktree: the "locked" mechanism is already implemented

[Michael Haggerty]

So remove it from the "BUGS" section.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
 Documentation/git-worktree.txt | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 6cb3877..d5aeda0 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -167,8 +167,6 @@ performed manually, such as:
   warn if the worktree is dirty)
 - `mv` to move or rename a worktree and update its administrative files
 - `list` to list linked working trees
-- `locked` to prevent automatic pruning of administrative files (for instance,
-  for a worktree on a portable device)
 
 GIT
 ---
-- 
2.1.4

[PATCH 5/6] config.txt: refer to "git worktree prune", not "prune --worktree"

[Michael Haggerty]

The latter doesn't exist.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
 Documentation/config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 3e37b93..7f65dbb 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1293,7 +1293,7 @@ gc.pruneExpire::
 
 gc.pruneWorktreesExpire::
 	When 'git gc' is run, it will call
-	'prune --worktrees --expire 3.months.ago'.
+	'git worktree prune --expire 3.months.ago'.
 	Override the grace period with this config variable. The value
 	"now" may be used to disable the grace period and prune
 	$GIT_DIR/worktrees immediately.
-- 
2.1.4

[PATCH 6/6] worktree: wordsmith worktree-related manpages

[Michael Haggerty]

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
 Documentation/config.txt               |  8 ++++----
 Documentation/git-worktree.txt         |  2 +-
 Documentation/gitrepository-layout.txt | 18 +++++++++---------
 3 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7f65dbb..10bc351 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1292,11 +1292,11 @@ gc.pruneExpire::
 	unreachable objects immediately.
 
 gc.pruneWorktreesExpire::
-	When 'git gc' is run, it will call
+	When 'git gc' is run, it calls
 	'git worktree prune --expire 3.months.ago'.
-	Override the grace period with this config variable. The value
-	"now" may be used to disable the grace period and prune
-	$GIT_DIR/worktrees immediately.
+	This config variable can be used to set a different grace
+	period. The value "now" may be used to disable the grace
+	period and prune $GIT_DIR/worktrees immediately.
 
 gc.reflogExpire::
 gc.<pattern>.reflogExpire::
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index d5aeda0..cecb44c 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -138,7 +138,7 @@ 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
-linkgit:git-stash[1] to store your changes away temporarily, however, your
+linkgit:git-stash[1] to store your changes away temporarily; however, your
 worktree 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
diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index fe7fa96..fe7d4bb 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -251,25 +251,25 @@ modules::
 	Contains the git-repositories of the submodules.
 
 worktrees::
-	Contains worktree specific information of linked
-	working trees. Each subdirectory contains the worktree-related
+	Contains worktree-specific information for linked working
+	trees. Each subdirectory contains the worktree-related
 	part of a linked working tree. This directory is ignored if
-	$GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/worktrees" will be
-	used instead.
+	$GIT_COMMON_DIR is set, in which case
+	"$GIT_COMMON_DIR/worktrees" will be used instead.
 
 worktrees/<id>/gitdir::
 	A text file containing the absolute path back to the .git file
 	that points to here. This is used to check if the linked
 	repository has been manually removed and there is no need to
-	keep this directory any more. mtime of this file should be
+	keep this directory any more. The mtime of this file should be
 	updated every time the linked repository is accessed.
 
 worktrees/<id>/locked::
 	If this file exists, the linked working tree may be on a
-	portable device and not available. It does not mean that the
-	linked working tree is gone and `worktrees/<id>` could be
-	removed. The file's content contains a reason string on why
-	the repository is locked.
+	portable device and not available. The presence of this file
+	prevents `worktrees/<id>` from being pruned by `git worktree
+	prune`. The file may contain a string explaining why the
+	repository is locked.
 
 worktrees/<id>/link::
 	If this file exists, it is a hard link to the linked .git
-- 
2.1.4

Re: [PATCH 0/6] Various tweaks to 'worktree'-related manpages

[Eric Sunshine]

On Sat, Jul 18, 2015 at 10:10 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> I haven't been following the discussion of this feature on the mailing
> list, so I apologize if these changes overlap with any in-flight
> patches, and these changes should definitely be checked over by
> somebody more familiar with the feature. These patches mostly fix what
> seem like inconsistencies in the documentation. The last patch
> contains some wordsmithing. Feel free to squash them together if you
> prefer.

Thanks for the patches. The changes mostly look fine, but see my
responses to the individual patches for some comments.

Re: [PATCH 1/6] worktree: consistently use term "linked working tree" in manpages

[Eric Sunshine]

On Sat, Jul 18, 2015 at 10:10 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> Sometimes linked working trees were called "linked working
> directories" or "linked worktrees". Always refer to them as "linked
> working trees" for consistency.
>
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> ---
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index da71f50..c8dd0e5 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -141,7 +141,7 @@ demands that you fix something immediately. You might typically use
>  linkgit:git-stash[1] to store your changes away temporarily, however, your
>  worktree is in such a state of disarray (with new, moved, and removed files,

Was your intention to replace all instances of "worktree" with
"working tree" or just some? If only some, what is the criteria by
which you decide? I ask because several instances of "worktree" (such
as the one above) remain even after this patch.

>  and other bits and pieces strewn around) that you don't want to risk
> -disturbing any of it. Instead, you create a temporary linked worktree to
> +disturbing any of it. Instead, you create a temporary linked working tree to
>  make the emergency fix, remove it when done, and then resume your earlier
>  refactoring session.

Re: [PATCH 2/6] worktree: remove references to "git checkout --to" from the manpage

[Eric Sunshine]

On Sat, Jul 18, 2015 at 10:10 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> ---
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index c8dd0e5..707dfd0 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -18,7 +18,7 @@ DESCRIPTION
>  Manage multiple worktrees 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 checkout --to` a new working
> +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 "git
>  init" or "git clone".  A repository has one main working tree (if it's not a
> @@ -99,7 +99,7 @@ Each linked working tree has a private sub-directory in the repository's
>  $GIT_DIR/worktrees directory.  The private sub-directory's name is usually
>  the base name of the linked working tree's path, possibly appended with a
>  number to make it unique.  For example, when `$GIT_DIR=/path/main/.git` the
> -command `git checkout --to /path/other/test-next next` creates the linked
> +command `git worktree add /path/other/test-next next` creates the linked
>  working tree in `/path/other/test-next` and also creates a
>  `$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1`
>  if `test-next` is already taken).

These fixes are already in 'master': 4d5a3c5
(Documentation/git-worktree: fix stale "git checkout --to" references,
2015-07-16)

Re: [PATCH 3/6] worktree: fix incorrect references to file "locked"

[Eric Sunshine]

On Sat, Jul 18, 2015 at 10:10 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> The manpage referred to file "lock" in a couple of places. The file is
> actually called "locked".
>
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> ---
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index 707dfd0..6cb3877 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -39,7 +39,7 @@ repository so that they do not get automatically pruned.
>
>  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 creating a file named 'lock' alongside the other
> +being pruned by creating a file named 'locked' alongside the other

This change is good.

>  administrative files, optionally containing a plain text reason that
>  pruning should be suppressed. See section "DETAILS" for more information.
>
> @@ -167,7 +167,7 @@ performed manually, such as:
>    warn if the worktree is dirty)
>  - `mv` to move or rename a worktree and update its administrative files
>  - `list` to list linked working trees
> -- `lock` to prevent automatic pruning of administrative files (for instance,
> +- `locked` to prevent automatic pruning of administrative files (for instance,
>    for a worktree on a portable device)

This one is not. This 'lock' is referring to a proposed user-interface
command ("git worktree lock") for manipulating the underlying 'locked'
file so that the user doesn't have to have detailed implementation
knowledge or muck with the underlying mechanics manually.

Re: [PATCH 4/6] worktree: the "locked" mechanism is already implemented

[Eric Sunshine]

On Sat, Jul 18, 2015 at 10:10 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> So remove it from the "BUGS" section.
>
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> ---
>  Documentation/git-worktree.txt | 2 --
>  1 file changed, 2 deletions(-)
>
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index 6cb3877..d5aeda0 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -167,8 +167,6 @@ performed manually, such as:
>    warn if the worktree is dirty)
>  - `mv` to move or rename a worktree and update its administrative files
>  - `list` to list linked working trees
> -- `locked` to prevent automatic pruning of administrative files (for instance,
> -  for a worktree on a portable device)

This patch should be dropped. This BUGS item is not referring to the
low-level implementation of locking, but rather to the proposed user
interface command ("git worktree lock") for manipulating the 'locked'
file so that the user doesn't need detailed knowledge about the
underlying implementation.

Re: [PATCH 5/6] config.txt: refer to "git worktree prune", not "prune --worktree"

[Eric Sunshine]

On Sat, Jul 18, 2015 at 10:10 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> The latter doesn't exist.
>
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> ---
>  Documentation/config.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 3e37b93..7f65dbb 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -1293,7 +1293,7 @@ gc.pruneExpire::
>
>  gc.pruneWorktreesExpire::
>         When 'git gc' is run, it will call
> -       'prune --worktrees --expire 3.months.ago'.
> +       'git worktree prune --expire 3.months.ago'.

Looks good. This appears to be the last reference to "prune --worktrees".

>         Override the grace period with this config variable. The value
>         "now" may be used to disable the grace period and prune
>         $GIT_DIR/worktrees immediately.

Re: [PATCH 6/6] worktree: wordsmith worktree-related manpages

[Eric Sunshine]

On Sat, Jul 18, 2015 at 10:10 PM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> ---
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 7f65dbb..10bc351 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -1292,11 +1292,11 @@ gc.pruneExpire::
>         unreachable objects immediately.
>
>  gc.pruneWorktreesExpire::
> -       When 'git gc' is run, it will call
> +       When 'git gc' is run, it calls
>         'git worktree prune --expire 3.months.ago'.

This is a tangent, but I wonder if this config variable should be
renamed to gc.worktreePruneExpire to reflect the rename of "prune
--wortkrees" to "worktree prune".

> -       Override the grace period with this config variable. The value
> -       "now" may be used to disable the grace period and prune
> -       $GIT_DIR/worktrees immediately.
> +       This config variable can be used to set a different grace
> +       period. The value "now" may be used to disable the grace
> +       period and prune $GIT_DIR/worktrees immediately.
>
>  gc.reflogExpire::
>  gc.<pattern>.reflogExpire::
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index d5aeda0..cecb44c 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -138,7 +138,7 @@ EXAMPLES
>  worktrees/<id>/locked::
>         If this file exists, the linked working tree may be on a
> -       portable device and not available. It does not mean that the
> -       linked working tree is gone and `worktrees/<id>` could be
> -       removed. The file's content contains a reason string on why
> -       the repository is locked.
> +       portable device and not available. The presence of this file
> +       prevents `worktrees/<id>` from being pruned by `git worktree
> +       prune`. The file may contain a string explaining why the
> +       repository is locked.

When I read the new text, I kind of get the impression that pruning
only happens manually when the user invokes "git worktree prune". I
wonder if it can be reworded to mention that pruning can happen
automatically too. Or, maybe don't mention "git worktree prune" at
all, and instead just say, generally, that it prevents the
linked-worktree administrative files from being pruned.