rev-parse(1): logically group options
The options section of the git-rev-parse manual page has grown organically so that there now does not seem to be much logic behind the ordering of the options. It also does not make it clear that certain options must appear first on the command line. Address this by reorganising the options into groups with subheadings. The text of option descriptions does not change. Signed-off-by: John Keeping <john@keeping.me.uk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
John Keeping committed
Jul 21, 2013 at 13:49 UTC
49c639139cdcae2a50d19bfea227a9f24812e84d
1 file changed
+64
-40
Documentation/git-rev-parse.txt
+64
-40
@@ -24,9 +24,23 @@ distinguish between them.
24
25
OPTIONS
26
-------
27
+
28
+Operation Modes
29
+~~~~~~~~~~~~~~~
30
+
31
+Each of these options must appear first on the command line.
32
+
33
--parseopt::
34
Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
35
36
+--sq-quote::
37
+ Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
38
+ section below). In contrast to the `--sq` option below, this
39
+ mode does only quoting. Nothing else is done to command input.
40
+
41
+Options for --parseopt
42
+~~~~~~~~~~~~~~~~~~~~~~
43
+
44
--keep-dashdash::
45
Only meaningful in `--parseopt` mode. Tells the option parser to echo
46
out the first `--` met instead of skipping it.
@@ -36,10 +50,8 @@ OPTIONS
50
the first non-option argument. This can be used to parse sub-commands
51
that take options themselves.
52
39
---sq-quote::
40
- Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
41
- section below). In contrast to the `--sq` option below, this
42
- mode does only quoting. Nothing else is done to command input.
53
+Options for Filtering
54
+~~~~~~~~~~~~~~~~~~~~~
55
56
--revs-only::
57
Do not output flags and parameters not meant for
@@ -55,6 +67,9 @@ OPTIONS
67
--no-flags::
68
Do not output flag parameters.
69
70
+Options for Output
71
+~~~~~~~~~~~~~~~~~~
72
+
73
--default <arg>::
74
If there is no parameter given by the user, use `<arg>`
75
instead.
@@ -94,6 +109,17 @@ can be used.
109
strip '{caret}' prefix from the object names that already have
110
one.
111
112
+--abbrev-ref[=(strict|loose)]::
113
+ A non-ambiguous short name of the objects name.
114
+ The option core.warnAmbiguousRefs is used to select the strict
115
+ abbreviation mode.
116
+
117
+--short::
118
+--short=number::
119
+ Instead of outputting the full SHA-1 values of object names try to
120
+ abbreviate them to a shorter unique name. When no length is specified
121
+ 7 is used. The minimum length is 4.
122
+
123
--symbolic::
124
Usually the object names are output in SHA-1 form (with
125
possible '{caret}' prefix); this option makes them output in a
@@ -107,16 +133,8 @@ can be used.
133
unfortunately named tag "master"), and show them as full
134
refnames (e.g. "refs/heads/master").
135
110
---abbrev-ref[=(strict|loose)]::
111
- A non-ambiguous short name of the objects name.
112
- The option core.warnAmbiguousRefs is used to select the strict
113
- abbreviation mode.
114
-
115
---disambiguate=<prefix>::
116
- Show every object whose name begins with the given prefix.
117
- The <prefix> must be at least 4 hexadecimal digits long to
118
- avoid listing each and every object in the repository by
119
- mistake.
136
+Options for Objects
137
+~~~~~~~~~~~~~~~~~~~
138
139
--all::
140
Show all refs found in `refs/`.
@@ -139,18 +157,20 @@ shown. If the pattern does not contain a globbing character (`?`,
157
character (`?`, `*`, or `[`), it is turned into a prefix
158
match by appending `/*`.
159
142
---show-toplevel::
143
- Show the absolute path of the top-level directory.
160
+--disambiguate=<prefix>::
161
+ Show every object whose name begins with the given prefix.
162
+ The <prefix> must be at least 4 hexadecimal digits long to
163
+ avoid listing each and every object in the repository by
164
+ mistake.
165
145
---show-prefix::
146
- When the command is invoked from a subdirectory, show the
147
- path of the current directory relative to the top-level
148
- directory.
166
+Options for Files
167
+~~~~~~~~~~~~~~~~~
168
150
---show-cdup::
151
- When the command is invoked from a subdirectory, show the
152
- path of the top-level directory relative to the current
153
- directory (typically a sequence of "../", or an empty string).
169
+--local-env-vars::
170
+ List the GIT_* environment variables that are local to the
171
+ repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
172
+ Only the names of the variables are listed, not their value,
173
+ even if they are set.
174
175
--git-dir::
176
Show `$GIT_DIR` if defined. Otherwise show the path to
@@ -172,17 +192,27 @@ print a message to stderr and exit with nonzero status.
192
--is-bare-repository::
193
When the repository is bare print "true", otherwise "false".
194
175
---local-env-vars::
176
- List the GIT_* environment variables that are local to the
177
- repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
178
- Only the names of the variables are listed, not their value,
179
- even if they are set.
195
+--resolve-git-dir <path>::
196
+ Check if <path> is a valid repository or a gitfile that
197
+ points at a valid repository, and print the location of the
198
+ repository. If <path> is a gitfile then the resolved path
199
+ to the real repository is printed.
200
181
---short::
182
---short=number::
183
- Instead of outputting the full SHA-1 values of object names try to
184
- abbreviate them to a shorter unique name. When no length is specified
185
- 7 is used. The minimum length is 4.
201
+--show-cdup::
202
+ When the command is invoked from a subdirectory, show the
203
+ path of the top-level directory relative to the current
204
+ directory (typically a sequence of "../", or an empty string).
205
+
206
+--show-prefix::
207
+ When the command is invoked from a subdirectory, show the
208
+ path of the current directory relative to the top-level
209
+ directory.
210
+
211
+--show-toplevel::
212
+ Show the absolute path of the top-level directory.
213
+
214
+Other Options
215
+~~~~~~~~~~~~~
216
217
--since=datestring::
218
--after=datestring::
@@ -197,12 +227,6 @@ print a message to stderr and exit with nonzero status.
227
<args>...::
228
Flags and parameters to be parsed.
229
200
---resolve-git-dir <path>::
201
- Check if <path> is a valid repository or a gitfile that
202
- points at a valid repository, and print the location of the
203
- repository. If <path> is a gitfile then the resolved path
204
- to the real repository is printed.
205
-
230
231
include::revisions.txt[]
232