Error in documentation for @{-n} in gitrevisions

Kevin· Jan 11, 2014, 17:34 UTC · lore

While discussing the behavior of "git checkout -", I apparently was confused because the documentation states:

  The construct @{-<n>} means the <n>th branch checked out before the
current one.

But experimenting with it, it also takes you back to previously checkout commits.

  git-checkout-at-minus-one :: (master) » git checkout origin/master
  Note: checking out 'origin/master'.
  HEAD is now at f8b2f0c... two

  git-checkout-at-minus-one :: (f8b2f0c) » git checkout -
  Switched to branch 'master'

  git-checkout-at-minus-one :: (master) » git checkout -
                                              Note: checking out
'f8b2f0c1419d1fe798159c2c2578d2dbe1323148'.
  HEAD is now at f8b2f0c... two

Either the documentation is wrong, and should be changed to "<n>th branch/commit checkout out before the current one", or the behavior of @{-1} is wrong.

Ramkumar Ramachandra· Jan 12, 2014, 10:19 UTC · re: Kevin · lore

Re: Error in documentation for @{-n} in gitrevisions

Kevin wrote:

> Either the documentation is wrong, and should be changed to "<n>th
> branch/commit checkout out before the current one", or the behavior of
> @{-1} is wrong.

Yeah, the documentation needs to be updated. Patches welcome.

Thomas Rast· Jan 19, 2014, 07:01 UTC · re: Kevin · lore

[PATCH] Documentation: @{-N} can refer to a commit

The @{-N} syntax always referred to the N-th last thing checked out, which can be either a branch or a commit (for detached HEAD cases). However, the documentation only mentioned branches.

Edit in a "/commit" in the appropriate places.

Reported-by: Kevin <ikke@ikke.info>
Signed-off-by: Thomas Rast <tr@thomasrast.ch>
---

This is the "minimal" edit. I'd welcome better wording for the git-commit manpage, I can't come up with any right now.

 Documentation/git-checkout.txt | 4 ++--
 Documentation/revisions.txt    | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 91294f8..33ad2ad 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -232,8 +232,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
 	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
-checks out the branch (instead of detaching).  You may also specify
+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}"`.
 +
 As a further special case, you may use `"A...B"` as a shortcut for the
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 2c06ed3..5a286d0 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -88,7 +88,7 @@ some output processing may assume ref names in UTF-8.
   branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'.
 
 '@\{-<n>\}', e.g. '@\{-1\}'::
-  The construct '@\{-<n>\}' means the <n>th branch checked out
+  The construct '@\{-<n>\}' means the <n>th branch/commit checked out
   before the current one.
 
 '<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::

-- 
1.9.rc0.162.g8980120