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

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

[Eric Sunshine]

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(-)

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

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

[Junio C Hamano]

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>
> ---
>
> 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(-)

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:

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

[Eric Sunshine]

On Thu, Jul 16, 2015 at 6:57 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 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.