Skip to content

Commit 19623eb

Browse files
inosmeetgitster
inosmeet
authored and
gitster
committed
doc: factor out common option
In preparation for adding documentation for `git refs list`, factor out the common options from the `git-for-each-ref` man page into a shareable file `for-each-ref-options.adoc` and update `git-for-each-ref.adoc` to use an `include::` macro. This change is a pure refactoring and results in no change to the final rendered documentation for `for-each-ref`. Mentored-by: Patrick Steinhardt <[email protected]> Mentored-by: shejialuo <[email protected]> Mentored-by: Karthik Nayak <[email protected]> Signed-off-by: Meet Soni <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent 721c9e5 commit 19623eb

File tree

2 files changed

+89
-88
lines changed

2 files changed

+89
-88
lines changed

‎Documentation/for-each-ref-options.adoc

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
<pattern>...::
2+
If one or more patterns are given, only refs are shown that
3+
match against at least one pattern, either using fnmatch(3) or
4+
literally, in the latter case matching completely or from the
5+
beginning up to a slash.
6+
7+
--stdin::
8+
If `--stdin` is supplied, then the list of patterns is read from
9+
standard input instead of from the argument list.
10+
11+
--count=<count>::
12+
By default the command shows all refs that match
13+
`<pattern>`. This option makes it stop after showing
14+
that many refs.
15+
16+
--sort=<key>::
17+
A field name to sort on. Prefix `-` to sort in
18+
descending order of the value. When unspecified,
19+
`refname` is used. You may use the --sort=<key> option
20+
multiple times, in which case the last key becomes the primary
21+
key.
22+
23+
--format=<format>::
24+
A string that interpolates `%(fieldname)` from a ref being shown and
25+
the object it points at. In addition, the string literal `%%`
26+
renders as `%` and `%xx` - where `xx` are hex digits - renders as
27+
the character with hex code `xx`. For example, `%00` interpolates to
28+
`\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).
29+
+
30+
When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)
31+
TAB %(refname)`.
32+
33+
--color[=<when>]::
34+
Respect any colors specified in the `--format` option. The
35+
`<when>` field must be one of `always`, `never`, or `auto` (if
36+
`<when>` is absent, behave as if `always` was given).
37+
38+
--shell::
39+
--perl::
40+
--python::
41+
--tcl::
42+
If given, strings that substitute `%(fieldname)`
43+
placeholders are quoted as string literals suitable for
44+
the specified host language. This is meant to produce
45+
a scriptlet that can directly be `eval`ed.
46+
47+
--points-at=<object>::
48+
Only list refs which points at the given object.
49+
50+
--merged[=<object>]::
51+
Only list refs whose tips are reachable from the
52+
specified commit (HEAD if not specified).
53+
54+
--no-merged[=<object>]::
55+
Only list refs whose tips are not reachable from the
56+
specified commit (HEAD if not specified).
57+
58+
--contains[=<object>]::
59+
Only list refs which contain the specified commit (HEAD if not
60+
specified).
61+
62+
--no-contains[=<object>]::
63+
Only list refs which don't contain the specified commit (HEAD
64+
if not specified).
65+
66+
--ignore-case::
67+
Sorting and filtering refs are case insensitive.
68+
69+
--omit-empty::
70+
Do not print a newline after formatted refs where the format expands
71+
to the empty string.
72+
73+
--exclude=<pattern>::
74+
If one or more patterns are given, only refs which do not match
75+
any excluded pattern(s) are shown. Matching is done using the
76+
same rules as `<pattern>` above.
77+
78+
--include-root-refs::
79+
List root refs (HEAD and pseudorefs) apart from regular refs.
80+
81+
--start-after=<marker>::
82+
Allows paginating the output by skipping references up to and including the
83+
specified marker. When paging, it should be noted that references may be
84+
deleted, modified or added between invocations. Output will only yield those
85+
references which follow the marker lexicographically. Output begins from the
86+
first reference that would come after the marker alphabetically. Cannot be
87+
used with `--sort=<key>` or `--stdin` options, or the _<pattern>_ argument(s)
88+
to limit the refs.

‎Documentation/git-for-each-ref.adoc

Lines changed: 1 addition & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -28,94 +28,7 @@ host language allowing their direct evaluation in that language.
2828

2929
OPTIONS
3030
-------
31-
<pattern>...::
32-
If one or more patterns are given, only refs are shown that
33-
match against at least one pattern, either using fnmatch(3) or
34-
literally, in the latter case matching completely or from the
35-
beginning up to a slash.
36-
37-
--stdin::
38-
If `--stdin` is supplied, then the list of patterns is read from
39-
standard input instead of from the argument list.
40-
41-
--count=<count>::
42-
By default the command shows all refs that match
43-
`<pattern>`. This option makes it stop after showing
44-
that many refs.
45-
46-
--sort=<key>::
47-
A field name to sort on. Prefix `-` to sort in
48-
descending order of the value. When unspecified,
49-
`refname` is used. You may use the --sort=<key> option
50-
multiple times, in which case the last key becomes the primary
51-
key.
52-
53-
--format=<format>::
54-
A string that interpolates `%(fieldname)` from a ref being shown and
55-
the object it points at. In addition, the string literal `%%`
56-
renders as `%` and `%xx` - where `xx` are hex digits - renders as
57-
the character with hex code `xx`. For example, `%00` interpolates to
58-
`\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).
59-
+
60-
When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)
61-
TAB %(refname)`.
62-
63-
--color[=<when>]::
64-
Respect any colors specified in the `--format` option. The
65-
`<when>` field must be one of `always`, `never`, or `auto` (if
66-
`<when>` is absent, behave as if `always` was given).
67-
68-
--shell::
69-
--perl::
70-
--python::
71-
--tcl::
72-
If given, strings that substitute `%(fieldname)`
73-
placeholders are quoted as string literals suitable for
74-
the specified host language. This is meant to produce
75-
a scriptlet that can directly be `eval`ed.
76-
77-
--points-at=<object>::
78-
Only list refs which points at the given object.
79-
80-
--merged[=<object>]::
81-
Only list refs whose tips are reachable from the
82-
specified commit (HEAD if not specified).
83-
84-
--no-merged[=<object>]::
85-
Only list refs whose tips are not reachable from the
86-
specified commit (HEAD if not specified).
87-
88-
--contains[=<object>]::
89-
Only list refs which contain the specified commit (HEAD if not
90-
specified).
91-
92-
--no-contains[=<object>]::
93-
Only list refs which don't contain the specified commit (HEAD
94-
if not specified).
95-
96-
--ignore-case::
97-
Sorting and filtering refs are case insensitive.
98-
99-
--omit-empty::
100-
Do not print a newline after formatted refs where the format expands
101-
to the empty string.
102-
103-
--exclude=<pattern>::
104-
If one or more patterns are given, only refs which do not match
105-
any excluded pattern(s) are shown. Matching is done using the
106-
same rules as `<pattern>` above.
107-
108-
--include-root-refs::
109-
List root refs (HEAD and pseudorefs) apart from regular refs.
110-
111-
--start-after=<marker>::
112-
Allows paginating the output by skipping references up to and including the
113-
specified marker. When paging, it should be noted that references may be
114-
deleted, modified or added between invocations. Output will only yield those
115-
references which follow the marker lexicographically. Output begins from the
116-
first reference that would come after the marker alphabetically. Cannot be
117-
used with `--sort=<key>` or `--stdin` options, or the _<pattern>_ argument(s)
118-
to limit the refs.
31+
include::for-each-ref-options.adoc[]
11932

12033
FIELD NAMES
12134
-----------

0 commit comments

Comments
 (0)