Merge branch 'ks/doc-checkout-previous'
authorJunio C Hamano <gitster@pobox.com>
Wed, 13 Dec 2017 21:28:57 +0000 (13:28 -0800)
committerJunio C Hamano <gitster@pobox.com>
Wed, 13 Dec 2017 21:28:57 +0000 (13:28 -0800)
@{-N} in "git checkout @{-N}" may refer to a detached HEAD state,
but the documentation was not clear about it, which has been fixed.

* ks/doc-checkout-previous:
  Doc/checkout: checking out using @{-N} can lead to detached state

1  2 
Documentation/git-checkout.txt

@@@ -13,8 -13,7 +13,8 @@@ SYNOPSI
  'git checkout' [-q] [-f] [-m] [--detach] <commit>
  'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
  'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 -'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]
 +'git checkout' [<tree-ish>] [--] <pathspec>...
 +'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...]
  
  DESCRIPTION
  -----------
@@@ -39,7 -38,7 +39,7 @@@ $ git checkout -b <branch> --track <rem
  ------------
  +
  You could omit <branch>, in which case the command degenerates to
 -"check out the current branch", which is a glorified no-op with a
 +"check out the current branch", which is a glorified no-op with
  rather expensive side-effects to show only the tracking information,
  if exists, for the current branch.
  
@@@ -79,13 -78,20 +79,13 @@@ be used to detach HEAD at the tip of th
  +
  Omitting <branch> detaches HEAD at the tip of the current branch.
  
 -'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
 +'git checkout' [<tree-ish>] [--] <pathspec>...::
  
 -      When <paths> or `--patch` are given, 'git checkout' does *not*
 -      switch branches.  It updates the named paths in the working tree
 -      from the index file or from a named <tree-ish> (most often a
 -      commit).  In this case, the `-b` and `--track` options are
 -      meaningless and giving either of them results in an error.  The
 -      <tree-ish> argument can be used to specify a specific tree-ish
 -      (i.e.  commit, tag or tree) to update the index for the given
 -      paths before updating the working tree.
 -+
 -'git checkout' with <paths> or `--patch` is used to restore modified or
 -deleted paths to their original contents from the index or replace paths
 -with the contents from a named <tree-ish> (most often a commit-ish).
 +      Overwrite paths in the working tree by replacing with the
 +      contents in the index or in the <tree-ish> (most often a
 +      commit).  When a <tree-ish> is given, the paths that
 +      match the <pathspec> are updated both in the index and in
 +      the working tree.
  +
  The index may contain unmerged entries because of a previous failed merge.
  By default, if you try to check out such an entry from the index, the
@@@ -95,14 -101,6 +95,14 @@@ specific side of the merge can be check
  using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
  file can be discarded to re-create the original conflicted merge result.
  
 +'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::
 +      This is similar to the "check out paths to the working tree
 +      from either the index or from a tree-ish" mode described
 +      above, but lets you use the interactive interface to show
 +      the "diff" output and choose which hunks to use in the
 +      result.  See below for the description of `--patch` option.
 +
 +
  OPTIONS
  -------
  -q::
@@@ -258,15 -256,6 +258,15 @@@ section of linkgit:git-add[1] to learn 
        out anyway. In other words, the ref can be held by more than one
        worktree.
  
 +--[no-]recurse-submodules::
 +      Using --recurse-submodules will update the content of all initialized
 +      submodules according to the commit recorded in the superproject. If
 +      local modifications in a submodule would be overwritten the checkout
 +      will fail unless `-f` is used. If nothing (or --no-recurse-submodules)
 +      is used, the work trees of submodules will not be updated.
 +      Just like linkgit:git-submodule[1], this will detach the
 +      submodules HEAD.
 +
  <branch>::
        Branch to checkout; if it refers to a branch (i.e., a name that,
        when prepended with "refs/heads/", is a valid ref), then that
        commit, your HEAD becomes "detached" and you are no longer on
        any branch (see below for details).
  +
As a special case, the `"@{-N}"` syntax for the N-th last branch/commit
checks out branches (instead of detaching).  You may also specify
`-` which is synonymous with `"@{-1}"`.
You can use the `"@{-N}"` syntax to refer to the N-th last
branch/commit checked out using "git checkout" operation. You may
also specify `-` which is synonymous to `"@{-1}`.
  +
- As a further special case, you may use `"A...B"` as a shortcut for the
+ As a special case, you may use `"A...B"` as a shortcut for the
  merge base of `A` and `B` if there is exactly one merge base. You can
  leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.