[PATCH v2 00/23] replace "checkout --to" with "worktree add"

This is v2 of the series to replace "git checkout --to" with "git worktree add". It's built atop Duy's df0b6cf (worktree: new place for "git prune --worktrees", 2015-06-29) which introduces the git-worktree command and replaces "git prune --worktrees" with "git worktree prune".

Although v1[*1*] consisted of only 1 patch, v2 is just a wee bit longer at 23 patches. Sorry for the length. Fortunately, most patches are quite small, thus (hopefully) easy to review.

v2 goes a bit beyond v1 by implementing Duy's suggestion[*2*] of allowing <branch> in "git worktree add <path> <branch>" to be omitted, in which case, as a convenience, it auto-vivifies a new branch named after <path>, as if it had been invoked as "git worktree add -b $(basename <path>) <path> HEAD". Moreover, unlike "git checkout -b <newbranch> --to <path> <branch>", the <branch> in "git worktree add -b <newbranch> <path> <branch>" is also optional, and defaults to HEAD.

v2 does not attempt either of the suggestions by Junio[*3*] or Duy[*4*] for eliminating git-checkout from the equation, which would allow us to remove the final couple bits of code in git-checkout which require intimate knowledge that the checkout is occurring in a newly created linked worktree. This series is already too long, and I didn't want it to grow further by implementing either of those ideas. Instead, this series leaves git-worktree at a state where one or the other of those suggestions can be done as follow-on patches touching only the underlying machinery, without affecting the user-facing interface.

[*1*]: http://thread.gmane.org/gmane.comp.version-control.git/273032
[*2*]: http://thread.gmane.org/gmane.comp.version-control.git/273032/focus=273035
[*3*]: via private email which suggested using "git-reset --hard" rather
       than "git checkout" to populate the new linked worktree.
[*4*]: http://thread.gmane.org/gmane.comp.version-control.git/273032/focus=273226

Eric Sunshine (23):
  Documentation/git-checkout: fix incorrect worktree prune command
  Documentation/git-worktree: associate options with commands
  Documentation: move linked worktree description from checkout to
    worktree
  Documentation/git-worktree: add BUGS section
  Documentation/git-worktree: split technical info from general
    description
  Documentation/git-worktree: add high-level 'lock' overview
  Documentation/git-worktree: add EXAMPLES section
  checkout: fix bug with --to and relative HEAD
  checkout: relocate --to's "no branch specified" check
  checkout: prepare_linked_checkout: drop now-unused 'new' argument
  checkout: make --to unconditionally verbose
  checkout: drop 'checkout_opts' dependency from prepare_linked_checkout
  worktree: introduce "add" command
  worktree: add --force option
  worktree: add --detach option
  worktree: add -b/-B options
  tests: worktree: retrofit "checkout --to" tests for "worktree add"
  checkout: retire --to option
  checkout: require worktree unconditionally
  worktree: extract basename computation to new function
  worktree: add: make -b/-B default to HEAD when <branch> is omitted
  worktree: add: auto-vivify new branch when <branch> is omitted
  checkout: retire --ignore-other-worktrees in favor of --force

 Documentation/git-checkout.txt                    |  78 +--------
 Documentation/git-worktree.txt                    | 141 +++++++++++++++-
 builtin/checkout.c                                | 161 +-----------------
 builtin/worktree.c                                | 193 ++++++++++++++++++++++
 git.c                                             |   2 +-
 t/{t2025-checkout-to.sh => t2025-worktree-add.sh} |  68 +++++---
 t/t2026-prune-linked-checkouts.sh                 |   2 +-
 t/t7410-submodule-checkout-to.sh                  |   4 +-
 8 files changed, 383 insertions(+), 266 deletions(-)
 rename t/{t2025-checkout-to.sh => t2025-worktree-add.sh} (51%)