summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJunio C Hamano <junkio@cox.net>2005-05-28 00:05:38 -0700
committerLinus Torvalds <torvalds@ppc970.osdl.org>2005-05-29 11:40:40 -0700
commit6af1f0192ff8740fe77db7cf02c739ccfbdf119c (patch)
tree944858d4fb8a907b52ea340eefd6b66d5f156393 /Documentation
parent2bc2564145835996734d6ed5d1880f85b17233d6 (diff)
downloadgit-6af1f0192ff8740fe77db7cf02c739ccfbdf119c.tar.gz
[PATCH] Rewrite ls-tree to behave more like "/bin/ls -a"
This is a complete rewrite of ls-tree to make it behave more like what "/bin/ls -a" does in the current working directory. Namely, the changes are: - Unlike the old ls-tree behaviour that used paths arguments to restrict output (not that it worked as intended---as pointed out in the mailing list discussion, it was quite incoherent), this rewrite uses paths arguments to specify what to show. - Without arguments, it implicitly uses the root level as its sole argument ("/bin/ls -a" behaves as if "." is given without argument). - Without -r (recursive) flag, it shows the named blob (either file or symlink), or the named tree and its immediate children. - With -r flag, it shows the named path, and recursively descends into it if it is a tree. - With -d flag, it shows the named path and does not show its children even if the path is a tree, nor descends into it recursively. This is still request-for-comments patch. There is no mailing list consensus that this proposed new behaviour is a good one. The patch to t/t3100-ls-tree-restrict.sh illustrates user-visible behaviour changes. Namely: * "git-ls-tree $tree path1 path0" lists path1 first and then path0. It used to use paths as an output restrictor and showed output in cache entry order (i.e. path0 first and then path1) regardless of the order of paths arguments. * "git-ls-tree $tree path2" lists path2 and its immediate children but having explicit paths argument does not imply recursive behaviour anymore, hence paths/baz is shown but not paths/baz/b. Signed-off-by: Junio C Hamano <junkio@cox.net> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/git-ls-tree.txt20
1 files changed, 12 insertions, 8 deletions
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index a113c359c1..958b56d8f4 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -4,23 +4,26 @@ v0.1, May 2005
NAME
----
-git-ls-tree - Displays a tree object in human readable form
+git-ls-tree - Lists the contents of a tree object.
SYNOPSIS
--------
-'git-ls-tree' [-r] [-z] <tree-ish> [paths...]
+'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...]
DESCRIPTION
-----------
-Converts the tree object to a human readable (and script processable)
-form.
+Lists the contents of a tree object, like what "/bin/ls -a" does
+in the current working directory.
OPTIONS
-------
<tree-ish>::
Id of a tree.
+-d::
+ show only the named tree entry itself, not its children
+
-r::
recurse into sub-trees
@@ -28,18 +31,19 @@ OPTIONS
\0 line termination on output
paths::
- Optionally, restrict the output of git-ls-tree to specific
- paths. Directories will only list their tree blob ids.
- Implies -r.
+ When paths are given, shows them. Otherwise implicitly
+ uses the root level of the tree as the sole path argument.
+
Output Format
-------------
- <mode>\t <type>\t <object>\t <file>
+ <mode> SP <type> SP <object> TAB <file>
Author
------
Written by Linus Torvalds <torvalds@osdl.org>
+Completely rewritten from scratch by Junio C Hamano <junkio@cox.net>
Documentation
--------------