@matheusbsbs / matheus-bagliano / commits / 331b51d240
Fork 0

Documentation: Split description of pretty formats of commit log

Split description of pretty formats into list of pretty options (--pretty and --encoding) in new file Documentation/pretty-options.txt and description of formats itself as a separate "PRETTY FORMATS" section in pretty-formats.txt While at it correct formatting a bit, to be better laid out in the resulting manpages: git-rev-list(1), git-show(1), git-log(1) and git-diff-tree(1). Those manpages now include pretty options in the same place as it was before, and description of formats just after all options. Inspired by the split into two filesdocumentation for merge strategies: Documentation/merge-options.txt and Documentation/merge-strategies.txt Signed-off-by: Jakub Narebski <jnareb@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>

Jakub Narebski committed May 14, 2007 at 01:25 UTC 331b51d24050c221221049421a924c1a150887db
6 files changed +60 -39
Documentation/git-diff-tree.txt
+4 -1
@@ -73,7 +73,7 @@ separated with a single space are given.
73 This flag causes "git-diff-tree --stdin" to also show
74 the commit message before the differences.
75
76 -include::pretty-formats.txt[]
76 +include::pretty-options.txt[]
77
78 --no-commit-id::
79 git-diff-tree outputs a line with the commit ID when
@@ -104,6 +104,9 @@ include::pretty-formats.txt[]
104 if the diff itself is empty.
105
106
107 +include::pretty-formats.txt[]
108 +
109 +
110 Limiting Output
111 ---------------
112 If you're only interested in differences in a subset of files, for
Documentation/git-log.txt
+4 -1
@@ -25,7 +25,7 @@ This manual page describes only the most frequently used options.
25 OPTIONS
26 -------
27
28 -include::pretty-formats.txt[]
28 +include::pretty-options.txt[]
29
30 -<n>::
31 Limits the number of commits to show.
@@ -58,6 +58,9 @@ include::pretty-formats.txt[]
58 Show only commits that affect the specified paths.
59
60
61 +include::pretty-formats.txt[]
62 +
63 +
64 Examples
65 --------
66 git log --no-merges::
Documentation/git-rev-list.txt
+5 -1
@@ -87,7 +87,7 @@ Using these options, gitlink:git-rev-list[1] will act similar to the
87 more specialized family of commit log tools: gitlink:git-log[1],
88 gitlink:git-show[1], and gitlink:git-whatchanged[1]
89
90 -include::pretty-formats.txt[]
90 +include::pretty-options.txt[]
91
92 --relative-date::
93
@@ -367,6 +367,10 @@ These options are mostly targeted for packing of git repositories.
367 Only useful with '--objects'; print the object IDs that are not
368 in packs.
369
370 +
371 +include::pretty-formats.txt[]
372 +
373 +
374 Author
375 ------
376 Written by Linus Torvalds <torvalds@osdl.org>
Documentation/git-show.txt
+3
@@ -38,6 +38,9 @@ OPTIONS
38 For a more complete list of ways to spell object names, see
39 "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
40
41 +include::pretty-options.txt[]
42 +
43 +
44 include::pretty-formats.txt[]
45
46
Documentation/pretty-formats.txt
+30 -36
@@ -1,31 +1,32 @@
1 ---pretty[='<format>']::
2 -
3 - Pretty-prints the details of a commit. `--pretty`
4 - without an explicit `=<format>` defaults to 'medium'.
5 - If the commit is a merge, and if the pretty-format
6 - is not 'oneline', 'email' or 'raw', an additional line is
7 - inserted before the 'Author:' line. This line begins with
8 - "Merge: " and the sha1s of ancestral commits are printed,
9 - separated by spaces. Note that the listed commits may not
10 - necessarily be the list of the *direct* parent commits if you
11 - have limited your view of history: for example, if you are
12 - only interested in changes related to a certain directory or
13 - file. Here are some additional details for each format:
14 -
15 - * 'oneline'
1 +PRETTY FORMATS
2 +--------------
3 +
4 +If the commit is a merge, and if the pretty-format
5 +is not 'oneline', 'email' or 'raw', an additional line is
6 +inserted before the 'Author:' line. This line begins with
7 +"Merge: " and the sha1s of ancestral commits are printed,
8 +separated by spaces. Note that the listed commits may not
9 +necessarily be the list of the *direct* parent commits if you
10 +have limited your view of history: for example, if you are
11 +only interested in changes related to a certain directory or
12 +file.
13 +
14 +Here are some additional details for each format:
15 +
16 +* 'oneline'
17
18 <sha1> <title line>
19 +
20 This is designed to be as compact as possible.
21
21 - * 'short'
22 +* 'short'
23
24 commit <sha1>
25 Author: <author>
26
27 <title line>
28
28 - * 'medium'
29 +* 'medium'
30
31 commit <sha1>
32 Author: <author>
@@ -35,7 +36,7 @@ This is designed to be as compact as possible.
36
37 <full commit message>
38
38 - * 'full'
39 +* 'full'
40
41 commit <sha1>
42 Author: <author>
@@ -45,7 +46,7 @@ This is designed to be as compact as possible.
46
47 <full commit message>
48
48 - * 'fuller'
49 +* 'fuller'
50
51 commit <sha1>
52 Author: <author>
@@ -57,18 +58,16 @@ This is designed to be as compact as possible.
58
59 <full commit message>
60
60 -
61 - * 'email'
61 +* 'email'
62
63 From <sha1> <date>
64 From: <author>
65 Date: <date & time>
66 Subject: [PATCH] <title line>
67
68 - full commit message>
69 -
68 + <full commit message>
69
71 - * 'raw'
70 +* 'raw'
71 +
72 The 'raw' format shows the entire commit exactly as
73 stored in the commit object. Notably, the SHA1s are
@@ -77,19 +76,22 @@ displayed in full, regardless of whether --abbrev or
76 true parent commits, without taking grafts nor history
77 simplification into account.
78
80 - * 'format:'
79 +* 'format:'
80 +
81 The 'format:' format allows you to specify which information
82 you want to show. It works a little bit like printf format,
83 with the notable exception that you get a newline with '%n'
84 instead of '\n'.
86 -
87 -E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<"'
85 ++
86 +E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"'
87 would show something like this:
89 -
88 ++
89 +-------
90 The author of fe6e0ee was Junio C Hamano, 23 hours ago
91 The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
92
93 +--------
94 ++
95 The placeholders are:
96
97 - '%H': commit hash
@@ -120,11 +122,3 @@ The placeholders are:
122 - '%m': left, right or boundary mark
123 - '%n': newline
124
123 -
124 ---encoding[=<encoding>]::
125 - The commit objects record the encoding used for the log message
126 - in their encoding header; this option can be used to tell the
127 - command to re-code the commit log message in the encoding
128 - preferred by the user. For non plumbing commands this
129 - defaults to UTF-8.
130 -
Documentation/pretty-options.txt new
+14
@@ -0,0 +1,14 @@
1 +--pretty[='<format>']::
2 +
3 + Pretty print the contents of the commit logs in a given format,
4 + where '<format>' can be one of 'oneline', 'short', 'medium',
5 + 'full', 'fuller', 'email', 'raw' and 'format:<string>'.
6 + When left out the format default to 'medium'.
7 +
8 +--encoding[=<encoding>]::
9 + The commit objects record the encoding used for the log message
10 + in their encoding header; this option can be used to tell the
11 + command to re-code the commit log message in the encoding
12 + preferred by the user. For non plumbing commands this
13 + defaults to UTF-8.
14 +