Merge branch 'es/worktree-add'

Update to the "linked checkout" in 2.5.0-rc1.

Instead of "checkout --to" that does not do what "checkout"
normally does, move the functionality to "git worktree add".

As this makes the end-user experience of the "worktree add" more or
less complete, I am tempted to say we should cook the other topic
that removes the internal "new-worktree-mode" hack from "checkout"
a bit longer in 'next', and release 2.5 final without that one.

* es/worktree-add:
  Documentation/git: fix stale "MULTIPLE CHECKOUT MODE" reference
  worktree: caution that this is still experimental
  Documentation/git-worktree: fix stale "git checkout --to" references

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).
@@ -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:

Documentation/git.txt

@@ -845,7 +845,7 @@ Git so take care if using Cogito etc.
 	normally in $GIT_DIR will be taken from this path
 	instead. Worktree-specific files such as HEAD or index are
 	taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and
-	the section 'MULTIPLE CHECKOUT MODE' in linkgit:checkout[1]
+	linkgit:git-worktree[1] for
 	details. This variable has lower precedence than other path
 	variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY...