[PATCH] git-show.txt: mention that object path must be relative in EXAMPLES.

Signed-off-by: Jari Aalto <redacted>
---
 Documentation/git-show.txt |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index 48b612e..2a014cc 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt

@@ -57,7 +57,11 @@ git show v1.0.0^\{tree\}::
 git show next~10:Documentation/README::
 	Shows the contents of the file `Documentation/README` as
 	they were current in the 10th last commit of the branch
-	`next`.
+	`next`. *Note:* the 'object' path must always be relative to git
+	project root. This wouldn't have worked:
+
+	$ cd Documentation
+	$ git show next~10:README
 
 git show master:Makefile master:t/Makefile::
 	Concatenates the contents of said Makefiles in the head

-- 
1.5.6.5

Jari Aalto [off-list ref] writes:

Actually that is not exactly true.  In the <tree-ish>:<path> the
'object' path must be always relative to <tree-ish), in this case
to "next~10", which means relative to project root at given commit
(important in case of subtree merge).

Although in practice <tree-ish> is always commit.

 
 git show master:Makefile master:t/Makefile::
 	Concatenates the contents of said Makefiles in the head
-- 
1.5.6.5

-- 
Jakub Narebski
Poland
ShadeHawk on #git

On Saturday 07 February 2009 17:31:47 Jakub Narebski wrote:

Jari Aalto [off-list ref] writes:

quoted

@@ -57,7 +57,11 @@ git show v1.0.0^\{tree\}::
 git show next~10:Documentation/README::
 	Shows the contents of the file `Documentation/README` as
 	they were current in the 10th last commit of the branch
-	`next`.
+	`next`. *Note:* the 'object' path must always be relative to git
+	project root. This wouldn't have worked:
+
+	$ cd Documentation
+	$ git show next~10:README

Actually that is not exactly true.  In the <tree-ish>:<path> the
'object' path must be always relative to <tree-ish), in this case
to "next~10", which means relative to project root at given commit
(important in case of subtree merge).

Also important if one of your commits moves everything into a subdirectory in 
preparation for adding new top-level directories.  Sure, everyone on this list 
always knows exactly what their project tree should look like from the first 
commit, but there may be users of git that aren't that sophisticated.  ;)

So, I think better additional text would simply be:
*Note:* the path is interpreted relative to the tree-ish.

A example of what not to do is probably not useful in this case.
-- 
Boyd Stephen Smith Jr.                   ,= ,-_-. =.
bss@iguanasuicide.net                   ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy         `-'(. .)`-'
http://iguanasuicide.net/                    \_/