From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 13 Dec 2017 21:28:57 +0000 (-0800)
Subject: Merge branch 'ks/doc-checkout-previous'
X-Git-Tag: v2.16.0-rc0~58
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/706566524ef59a97e89ba895b800398ef823d109?ds=inline;hp=-c

Merge branch 'ks/doc-checkout-previous'

@{-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
---

706566524ef59a97e89ba895b800398ef823d109
diff --combined Documentation/git-checkout.txt
index bfa64ca5c9,66372512f7..ca5fc9c798
--- a/Documentation/git-checkout.txt
+++ b/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
@@@ -274,11 -263,11 +274,11 @@@
  	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`.