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 <ps@pks.im> Mentored-by: shejialuo <shejialuo@gmail.com> Mentored-by: Karthik Nayak <karthik.188@gmail.com> Signed-off-by: Meet Soni <meetsoni3017@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Meet Soni committed
Aug 5, 2025 at 14:57 UTC
19623eb97e4edf76d585100c605037f9e51f6987
2 files changed
+89
-88
Documentation/for-each-ref-options.adoc
new
+88
@@ -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
+1
-88
@@ -28,94 +28,7 @@ host language allowing their direct evaluation in that language.
28
29
OPTIONS
30
-------
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[]
32
33
FIELD NAMES
34
-----------