threads / patch / 39864

v2Documentation/git-worktree: fix stale "git checkout --to" references

Subject: [PATCH v2] Documentation/git-worktree: fix stale "git checkout --to" references

## tl;dr

3 messages between Jul 16, 2015 and Jul 16, 2015. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

Eric Sunshine· Jul 16, 2015, 22:09 UTC · lore

These should have been changed to "git worktree add" by fc56361 (worktree: introduce "add" command, 2015-07-06.

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---

Changes since v1[1]: Reference the correct commit (fc56361, not b979d95) in the commit message. Sorry for the noise.

[1]: http://article.gmane.org/gmane.comp.version-control.git/274046
 Documentation/git-worktree.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Show changes to Documentation/git-worktree.txt +2 −2
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index da71f50..44619f2 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.5.0.rc2.378.g0af52e8
Junio C Hamano· Jul 16, 2015, 22:57 UTC · re: Eric Sunshine · lore

Re: [PATCH v2] Documentation/git-worktree: fix stale "git checkout --to" references

Eric Sunshine <sunshine@sunshineco.com> writes:
Show 10 quoted lines
> These should have been changed to "git worktree add" by fc56361
> (worktree: introduce "add" command, 2015-07-06.
>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> ---
>
> Changes since v1[1]: Reference the correct commit (fc56361, not b979d95)
> in the commit message. Sorry for the noise.
>
> [1]: http://article.gmane.org/gmane.comp.version-control.git/274046
Thanks.  Will apply.

By the way, given the rate of bugs and glitches I am finding in this code with a very superficial use in real work only for a few days, perhaps we would want to add a warning to the documentation of "git worktree", in addition to the "this is still experimental" mention in the release notes, to discourage people to keep their only copy of the work in a secondary worktree for now?

 Documentation/git-worktree.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Show changes to Documentation/git-worktree.txt +3 −2
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index da71f50..6de4c21 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -157,8 +157,9 @@ $ git worktree prune
 
 BUGS
 ----
-Multiple checkout support for submodules is incomplete. It is NOT
-recommended to make multiple checkouts of a superproject.
+Multiple checkout in general is still experimental, and the support
+for submodules is incomplete. It is NOT recommended to make multiple
+checkouts of a superproject.
 
 git-worktree could provide more automation for tasks currently
 performed manually, such as:
Eric Sunshine· Jul 16, 2015, 23:26 UTC · re: Junio C Hamano · lore

Re: [PATCH v2] Documentation/git-worktree: fix stale "git checkout --to" references

On Thu, Jul 16, 2015 at 6:57 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 20 quoted lines
> Eric Sunshine <sunshine@sunshineco.com> writes:
>> These should have been changed to "git worktree add" by fc56361
>> (worktree: introduce "add" command, 2015-07-06.
>>
>> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
>> ---
> By the way, given the rate of bugs and glitches I am finding in this
> code with a very superficial use in real work only for a few days,
> perhaps we would want to add a warning to the documentation of "git
> worktree", in addition to the "this is still experimental" mention
> in the release notes, to discourage people to keep their only copy
> of the work in a secondary worktree for now?
>
>  BUGS
>  ----
> -Multiple checkout support for submodules is incomplete. It is NOT
> -recommended to make multiple checkouts of a superproject.
> +Multiple checkout in general is still experimental, and the support
> +for submodules is incomplete. It is NOT recommended to make multiple
> +checkouts of a superproject.
Maybe, maybe not.

The submodule item is at least (hopefully) quantitative. That is, there should be some point after specific shortcomings have been addressed when we can say "submodules are now supported", and remove the item from BUGS.

But, "in general is still experimental" is nebulous and open-ended. At what point do we stop considering it experimental, and who will remember to remove the entry from BUGS when that day comes?

Other than that concern, the revised text seems reasonable.

← back to recent threads