@matheusbsbs / matheus-bagliano / commits / 7b9b4c452c
Fork 0

Update the git-ls-tree documentation

This patch aims to freshen up a bit the git-ls-tree documentation. It hints that the list of paths are in fact patterns to be matched, explains the new -t, --name-only and --name-status options, corrects the original autorship information to refer to yours sincerely, corrects several grammar mistakes, etc. Since the documentation still deserves some significant work (at least proper description of the pattern matching), I also added the stub notice. Signed-off-by: Petr Baudis <pasky@suse.cz> Signed-off-by: Junio C Hamano <junkio@cox.net>

Petr Baudis committed Dec 5, 2005 at 00:31 UTC 7b9b4c452c793d0f8e3ff9f0b7fe526448fc314a
1 file changed +29 -14
Documentation/git-ls-tree.txt
+29 -14
@@ -8,12 +8,15 @@ git-ls-tree - Lists the contents of a tree object.
8
9 SYNOPSIS
10 --------
11 -'git-ls-tree' [-d] [-r] [-z] <tree-ish> [paths...]
11 +'git-ls-tree' [-d] [-r] [-t] [-z] [--name-only] [--name-status] <tree-ish> [paths...]
12
13 DESCRIPTION
14 -----------
15 -Lists the contents of a tree object, like what "/bin/ls -a" does
16 -in the current working directory.
15 +Lists the contents of a given tree object, like what "/bin/ls -a" does
16 +in the current working directory. Note that the usage is subtly different,
17 +though - 'paths' denote just a list of patterns to match, e.g. so specifying
18 +directory name (without '-r') will behave differently, and order of the
19 +arguments does not matter.
20
21 OPTIONS
22 -------
@@ -21,36 +24,48 @@ OPTIONS
24 Id of a tree-ish.
25
26 -d::
24 - show only the named tree entry itself, not its children
27 + Show only the named tree entry itself, not its children.
28
29 -r::
27 - recurse into sub-trees
30 + Recurse into sub-trees.
31 +
32 +-t::
33 + Show tree entries even when going to recurse them. Has no effect
34 + if '-r' was not passed. '-d' implies '-t'.
35
36 -z::
30 - \0 line termination on output
37 + \0 line termination on output.
38 +
39 +--name-only::
40 +--name-status::
41 + List only filenames (instead of the "long" output), one per line.
42
43 paths::
33 - When paths are given, show them. Otherwise implicitly
34 - uses the root level of the tree as the sole path argument.
44 + When paths are given, show them (note that this isn't really raw
45 + pathnames, but rather a list of patterns to match). Otherwise
46 + implicitly uses the root level of the tree as the sole path argument.
47
48
49 Output Format
50 -------------
51 <mode> SP <type> SP <object> TAB <file>
52
41 -When `-z` option is not used, TAB, LF, and backslash characters
42 -in pathnames are represented as `\t`, `\n`, and `\\`,
43 -respectively.
53 +When the `-z` option is not used, TAB, LF, and backslash characters
54 +in pathnames are represented as `\t`, `\n`, and `\\`, respectively.
55
56
57 Author
58 ------
48 -Written by Linus Torvalds <torvalds@osdl.org>
49 -Completely rewritten from scratch by Junio C Hamano <junkio@cox.net>
59 +Written by Petr Baudis <pasky@suse.cz>
60 +Completely rewritten from scratch by Junio C Hamano <junkio@cox.net>,
61 +another major rewrite by Linus Torvalds <torvalds@osdl.org>
62
63 Documentation
64 --------------
53 -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
65 +Documentation by David Greaves, Junio C Hamano and the git-list
66 +<git@vger.kernel.org>.
67 +
68 +This manual page is a stub. You can help the git documentation by expanding it.
69
70 GIT
71 ---