Add a notice to the doc of git-ls-tree.
PATCH 1/1 Add a notice to the doc of git-ls-tree.
The notice covers this behaviour:
if you are in the git/ subdirectory of your repository, it will pick the tree corresponding to that directory instead of the root one if you specify the root tree object id.
Compare the output of both of those commands:
git-ls-tree cb44e6571708aa2792c73a289d87586fe3c0c362 git-cat-file -p cb44e6571708aa2792c73a289d87586fe3c0c362
--- Documentation/git-ls-tree.txt | 4 ++++ 1 files changed, 4 insertions(+), 0 deletions(-)
Documentation/git-ls-tree.txt +4 -0
@@ -21,6 +21,10 @@ though - 'paths' denote just a list of patterns to match, e.g. so specifying directory name (without '-r') will behave differently, and order of the arguments does not matter. +Note that if you give ls-tree the sha1 id of a parent of the tree +corresponding to the directory you're in, it will resolve that tree and list +its contents instead of listing the contents of the tree you gave. + OPTIONS ------- <tree-ish>::
Signature · 1 line
1.5.6.2
Quoted 17 lines · Steve Frécinaux
The notice covers this behaviour:
if you are in the git/ subdirectory of your repository, it will pick the tree corresponding to that directory instead of the root one if you specify the root tree object id.Compare the output of both of those commands:
git-ls-treecb44e6571708aa2792c73a289d87586fe3c0c362git-cat-file -pcb44e6571708aa2792c73a289d87586fe3c0c362--- Documentation/git-ls-tree.txt | 4 ++++ 1 files changed, 4 insertions(+), 0 deletions(-)Documentation/git-ls-tree.txt +0
-0
Documentation/git-ls-tree.txt though - 'paths' denote just a list of patterns to match, e.g. so specifying · line 30
Quoted 10 lines
Documentation/git-ls-tree.txt +4
-0@@ -21,6 +21,10 @@ though - 'paths' denote just a list of patterns to match, e.g. so specifying directory name (without '-r') will behave differently, and order of the arguments does not matter. +Note that if you give ls-tree the sha1 id of a parent of the tree +corresponding to the directory you're in, it will resolve that tree and list +its contents instead of listing the contents of the tree you gave. + OPTIONS ------- <tree-ish>::
It's hard to make out what do you mean, the patch description is much clearer, paradoxically. Also, this in fact holds for the root tree instead of the parent tree, and the behaviour changes from "weird" to "simply broken" when you try to list a tree object that is _not_ the root project tree from within a subdirectory:
git$ git ls-tree HEAD Documentation 040000 tree 066c25e86a44d4c7bde2d3e9b91e6891d752efa1 Documentation git/Documentation$ git ls-tree 066c25e86a44d4c7bde2d3e9b91e6891d752efa1 git/Documentation$
I think that ls-tree simply shouldn't auto-fill its pathspec based on current prefix in case no pathspec was supplied. Patch to follow.
Signature · 3 lines
Petr "Pasky" Baudis As in certain cults it is possible to kill a process if you know its true name. -- Ken Thompson and Dennis M. Ritchie
Quoted 2 lines · Petr Baudis
I think that ls-tree simply shouldn't auto-fill its pathspec based on current prefix in case no pathspec was supplied. Patch to follow.
Have you dug the list archive from mid-to-late December 2005 that prompted the current behaviour (and introduction of --full-name)? I haven't. A change to always do the --full-name can only be justified by doing so and rehashing the issues.
On the other hand, "fix" is welcome.
Quoted 11 lines · Junio C Hamano
Quoted 2 lines · Petr Baudis
I think that ls-tree simply shouldn't auto-fill its pathspec based on current prefix in case no pathspec was supplied. Patch to follow.
Have you dug the list archive from mid-to-late December 2005 that prompted the current behaviour (and introduction of --full-name)? I haven't. A change to always do the --full-name can only be justified by doing so and rehashing the issues.
On the other hand, "fix" is welcome.
You are right, now that I understand the issue better, there's no good fix for this except perhaps introducing --no-prefix, which is not my itch to scratch. Here's my original wording improvement:
Note that if you are within a subdirectory of your working copy, 'git ls-tree' will automatically prepend the subdirectory prefix to the specified paths, and assume the prefix specified in case no paths were given - no matter what the tree object is! Thus, within a subdirectory, 'git ls-tree' behaves as expected only when run on a root tree object.
Signature · 3 lines
Petr "Pasky" Baudis As in certain cults it is possible to kill a process if you know its true name. -- Ken Thompson and Dennis M. Ritchie
PATCH 1/1 Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
When run in a working copy subdirectory, git-ls-tree will automagically add the prefix to the pathspec, which can result in an unexpected behavior when the tree object accessed is not the root tree object.
This was originally pointed out and described in a patch by Steve Frénaux <[email protected]>, this is a shot at clearer and more accurate description.
---
Documentation/git-ls-tree.txt | 9 +++++++++ 1 files changed, 9 insertions(+), 0 deletions(-)
Documentation/git-ls-tree.txt +9 -0
@@ -21,6 +21,15 @@ though - 'paths' denote just a list of patterns to match, e.g. so specifying directory name (without '-r') will behave differently, and order of the arguments does not matter. +Note that within a subdirectory of the working copy, 'git ls-tree' +will automatically prepend the subdirectory prefix to the specified +paths and assume just the prefix was specified in case no paths were +given --- no matter what the tree object is! +Thus, within a subdirectory, 'git ls-tree' behaves as expected +only when run on a root tree object (e.g. with a 'HEAD' tree-ish, +but not anymore when passed 'HEAD:Documentation' instead). + + OPTIONS ------- <tree-ish>::
Re: [PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
Documentation/git-ls-tree.txt though - 'paths' denote just a list of patterns to match, e.g. so specifying · line 27
Quoted 4 lines · Petr Baudis
Documentation/git-ls-tree.txt +4
-0+Note that within a subdirectory of the working copy, 'git ls-tree' +will automatically prepend the subdirectory prefix to the specified +paths and assume just the prefix was specified in case no paths were +given --- no matter what the tree object is!
Don't be negative upfront. Explain why this is a good thing first.
... were given. This is useful when you are deep in a subdirectory and want to inspect the list of files in an arbitrary commit. E.g.
$ cd some/deep/path
$ git ls-tree --name-only -r HEAD~20
will list the files in some/deep/path (i.e. where you are) 20 commits ago, just like running "/bin/ls" there will give you the list of files you have right now.
Quoted 8 lines
Documentation/git-ls-tree.txt +5
-0+Thus, within a subdirectory, 'git ls-tree' behaves as expected +only when run on a root tree object (e.g. with a 'HEAD' tree-ish, +but not anymore when passed 'HEAD:Documentation' instead). + + OPTIONS ------- <tree-ish>::
Re: [PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
Quoted 13 lines · Junio C Hamano
Documentation/git-ls-tree.txt though - 'paths' denote just a list of patterns to match, e.g. so specifying · line 27
Quoted 4 lines · Petr Baudis
Documentation/git-ls-tree.txt +4
-0+Note that within a subdirectory of the working copy, 'git ls-tree' +will automatically prepend the subdirectory prefix to the specified +paths and assume just the prefix was specified in case no paths were +given --- no matter what the tree object is!Don't be negative upfront. Explain why this is a good thing first.
... were given. This is useful when you are deep in a subdirectory and want to inspect the list of files in an arbitrary commit. E.g.
Quoted 6 lines
$ cd some/deep/path
$ git ls-tree --name-only -r HEAD~20will list the files in some/deep/path (i.e. where you are) 20 commits ago, just like running "
/bin/ls" there will give you the list of files you have right now.
Frankly, I think this is overdoing it. I'm all for being positive, but it is obvious why this is good thing when you inspect a root tree and there's no need to be too wordy about it - it should be enough to acknowledge this later by the "as expected" as I note below.
The documentation should be detailed and complete, but not too chatty, or it gets too hard to read again.
Quoted 8 lines
Quoted 8 lines
Documentation/git-ls-tree.txt +5
-0+Thus, within a subdirectory, 'git ls-tree' behaves as expected +only when run on a root tree object (e.g. with a 'HEAD' tree-ish, +but not anymore when passed 'HEAD:Documentation' instead). + + OPTIONS ------- <tree-ish>::
Signature · 3 lines
Petr "Pasky" Baudis As in certain cults it is possible to kill a process if you know its true name. -- Ken Thompson and Dennis M. Ritchie
Re: [PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
Quoted 5 lines · Petr Baudis
Quoted 5 lines
commit. E.g. $ cd some/deep/path $ git ls-tree --name-only -r HEAD~20
Quoted 7 lines
Quoted 3 lines
will list the files in some/deep/path (i.e. where you are) 20 commits ago, just like running "
/bin/ls" there will give you the list of files you have right now.Frankly, I think this is overdoing it. I'm all for being positive, but it is obvious why this is good thing when you inspect a root tree and there's no need to be too wordy about it...
I mildly disagree.
If the person had truly understood that, why do we even have this thread to begin with?
Description on *what* it does (i.e. "like what ls -a does in the current working directory" we have in the Description section) obviously was not good enough. It will be better understood if you describe *why* it does it that way at the same time.
Re: [PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
Quoted 11 lines · Junio C Hamano
Quoted 9 lines · Petr Baudis
Quoted 8 lines
commit. E.g.
$ cd some/deep/path
$ git ls-tree --name-only -r HEAD~20will list the files in some/deep/path (i.e. where you are) 20 commits ago, just like running "
/bin/ls" there will give you the list of files you have right now.
Quoted 5 lines
Quoted 3 lines
Frankly, I think this is overdoing it. I'm all for being positive, but it is obvious why this is good thing when you inspect a root tree and there's no need to be too wordy about it...
I mildly disagree.
We may throw a dice or go with your version, I don't care *that* much about this change, I just wouldn't make it personally.
Quoted 2 lines
If the person had truly understood that, why do we even have this thread to begin with?
To nudge the person to the "aha" moment.
Quoted 3 lines
Description on *what* it does (i.e. "like what ls -a does in the current working directory" we have in the Description section) obviously was not good enough.
I don't understand; what does auto-prefixing have to do with the "ls -a" mention?
Quoted 2 lines
It will be better understood if you describe *why* it does it that way at the same time.
My version implies that for examining the root tree, without surplusage.
Signature · 3 lines
Petr "Pasky" Baudis As in certain cults it is possible to kill a process if you know its true name. -- Ken Thompson and Dennis M. Ritchie
Re: [PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
Quoted 12 lines · Petr Baudis
Quoted 11 lines · Junio C Hamano
Quoted 9 lines · Petr Baudis
Quoted 8 lines
commit. E.g.
$ cd some/deep/path
$ git ls-tree --name-only -r HEAD~20will list the files in some/deep/path (i.e. where you are) 20 commits ago, just like running "
/bin/ls" there will give you the list of files you have right now.
Quoted 8 lines
Quoted 5 lines
Quoted 3 lines
Frankly, I think this is overdoing it. I'm all for being positive, but it is obvious why this is good thing when you inspect a root tree and there's no need to be too wordy about it...
I mildly disagree.
We may throw a dice or go with your version, I don't care *that* much about this change, I just wouldn't make it personally.
What is the status of this patch? :-) Dropped altogether?
Petr "Pasky" Baudis
Re: [PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
Quoted 4 lines · Petr Baudis
Quoted 2 lines
We may throw a dice or go with your version, I don't care *that* much about this change, I just wouldn't make it personally.
What is the status of this patch? :-) Dropped altogether?
Left behind on the far side of oblivion; I do not offhand recall what this was about, sorry.
Re: [PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
Quoted 9 lines · Junio C Hamano
Quoted 4 lines · Petr Baudis
Quoted 2 lines
We may throw a dice or go with your version, I don't care *that* much about this change, I just wouldn't make it personally.
What is the status of this patch? :-) Dropped altogether?
Left behind on the far side of oblivion; I do not offhand recall what this was about, sorry.
Ok, I now recall this bit:
You are right, now that I understand the issue better, there's no good fix for this except perhaps introducing --no-prefix, which is not my itch to scratch. Here's my original wording improvement:
Note that if you are within a subdirectory of your working copy, 'git ls-tree' will automatically prepend the subdirectory prefix to the specified paths, and assume the prefix specified in case no paths were given - no matter what the tree object is! Thus, within a subdirectory, 'git ls-tree' behaves as expected only when run on a root tree object.
Eventually somebody may write a Porcelain that benefits from --no-prefix, but it is safe to defer the implementation until the need becomes real.
I'll add some explanatory message to the documentation.
Re: [PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec
In reply to Petr BaudisQuoted 3 lines · Petr Baudis
This was originally pointed out and described in a patch by Steve Frénaux <[email protected]>, this is a shot at clearer and more accurate description.
There is a typo in my name ;-)
Quoted 7 lines · Junio C Hamano
Quoted 2 lines · Petr Baudis
I think that ls-tree simply shouldn't auto-fill its pathspec based on current prefix in case no pathspec was supplied. Patch to follow.
Have you dug the list archive from mid-to-late December 2005 that prompted the current behaviour (and introduction of --full-name)? I haven't.
Now, I did:
http://thread.gmane.org/gmane.comp.version-control.git/13028/focus=13135
I think the answer is --full-name (cf. a69dd58 (ls-tree: chomp leading directories when run from a subdirectory, 2005-12-23)).
Quoted 10 lines · Junio C Hamano
Quoted 7 lines · Junio C Hamano
Quoted 2 lines · Petr Baudis
I think that ls-tree simply shouldn't auto-fill its pathspec based on current prefix in case no pathspec was supplied. Patch to follow.
Have you dug the list archive from mid-to-late December 2005 that prompted the current behaviour (and introduction of --full-name)? I haven't.
Quoted 6 lines
Now, I did:
http://thread.gmane.org/gmane.comp.version-control.git/13028/focus=13135I think the answer is --full-name (cf. a69dd58 (ls-tree: chomp leading directories when run from a subdirectory, 2005-12-23)).
I don't understand your point now. --full-name cares only about the displaying part; do you suggest that it should be extended to also turn off prepending the prefix during the filtering phase? That would make a lot of sense, if you are not worried about compatibility trouble.
Signature · 3 lines
Petr "Pasky, missing something" Baudis As in certain cults it is possible to kill a process if you know its true name. -- Ken Thompson and Dennis M. Ritchie
Quoted 3 lines · Petr Baudis
I don't understand your point now. --full-name cares only about the displaying part; do you suggest that it should be extended to also turn off prepending the prefix...
Ah, sorry, I thought you were talking about the display part.
I never thought you would think "showing relative to tree-root" is even an option. That would make it inconsistent with not just the established semantics of what the plumbing did, but also with what ls-files does.
Quoted 2 lines · Junio C Hamano
I never thought you would think "showing relative to tree-root" is even an option.
I assume you mean "not filtering relative to tree-root"?
Quoted 2 lines
That would make it inconsistent with not just the established semantics of what the plumbing did, but also with what ls-files does.
But ls-files always works on the index; ls-tree can work on trees, and when you're inspecting a non-root tree object from within a subdirectory, this behaviour can be rather unexpected. But as I said, I'm fine with just documenting it.
Signature · 3 lines
Petr "Pasky" Baudis As in certain cults it is possible to kill a process if you know its true name. -- Ken Thompson and Dennis M. Ritchie
Quoted 5 lines · Petr Baudis
Quoted 2 lines · Junio C Hamano
I never thought you would think "showing relative to tree-root" is even an option.
I assume you mean "not filtering relative to tree-root"?
Sorry, I may have been unclear. I meant "showing relative to tree-root, unlike showing relative to cwd like we have done forever".
Changing the behaviour would affect usage like this:
$ cd some/where
$ git ls-files
$ git ls-tree --name-only -r HEAD^cf. http://thread.gmane.org/gmane.comp.version-control.git/13028/focus=13080
Quoted 10 lines · Junio C Hamano
Sorry, I may have been unclear. I meant "showing relative to tree-root, unlike showing relative to cwd like we have done forever".
Changing the behaviour would affect usage like this:
$ cd some/where $ git ls-files $ git ls-tree --name-only -r HEAD^cf. http://thread.gmane.org/gmane.comp.version-control.git/13028/focus=13080
Yes, as I said, by now I agree that this is not acceptable, and thus
opted for just documenting the behaviour. :-)
Petr "Pasky" Baudis
Quoted 2 lines
It's hard to make out what do you mean, the patch description is much clearer, paradoxically.
It is hard to explain such a strange behaviour with a description that is both short and generic enough... But I agree with you. I just got bitten by this and I thought it was important enough to be specified.
Quoted 5 lines
Also, this in fact holds for the root tree
instead of the parent tree, and the behaviour changes from "weird" to "simply broken" when you try to list a tree object that is _not_ the root project tree from within a subdirectory:
Quoted 7 lines
git$ git ls-tree HEAD Documentation 040000 tree 066c25e86a44d4c7bde2d3e9b91e6891d752efa1 Documentation git/Documentation$ git ls-tree 066c25e86a44d4c7bde2d3e9b91e6891d752efa1 git/Documentation$I think that ls-tree simply shouldn't auto-fill its pathspec based on current prefix in case no pathspec was supplied. Patch to follow.
I also thought this behaviour was broken. But I didn't want to patch it because I was afraid of breaking things that would rely on it, despite it seems unexpected enough not to be used...