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>

diff --git a/Documentation/for-each-ref-options.adoc b/Documentation/for-each-ref-options.adoc
new file mode 100644 (file)
index 0000000..4a033d3
--- /dev/null
+++ b/Documentation/for-each-ref-options.adoc
@@ -0,0 +1,88 @@
+<pattern>...::
+       If one or more patterns are given, only refs are shown that
+       match against at least one pattern, either using fnmatch(3) or
+       literally, in the latter case matching completely or from the
+       beginning up to a slash.
+
+--stdin::
+       If `--stdin` is supplied, then the list of patterns is read from
+       standard input instead of from the argument list.
+
+--count=<count>::
+       By default the command shows all refs that match
+       `<pattern>`.  This option makes it stop after showing
+       that many refs.
+
+--sort=<key>::
+       A field name to sort on.  Prefix `-` to sort in
+       descending order of the value.  When unspecified,
+       `refname` is used.  You may use the --sort=<key> option
+       multiple times, in which case the last key becomes the primary
+       key.
+
+--format=<format>::
+       A string that interpolates `%(fieldname)` from a ref being shown and
+       the object it points at. In addition, the string literal `%%`
+       renders as `%` and `%xx` - where `xx` are hex digits - renders as
+       the character with hex code `xx`. For example, `%00` interpolates to
+       `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).
++
+When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)
+TAB %(refname)`.
+
+--color[=<when>]::
+       Respect any colors specified in the `--format` option. The
+       `<when>` field must be one of `always`, `never`, or `auto` (if
+       `<when>` is absent, behave as if `always` was given).
+
+--shell::
+--perl::
+--python::
+--tcl::
+       If given, strings that substitute `%(fieldname)`
+       placeholders are quoted as string literals suitable for
+       the specified host language.  This is meant to produce
+       a scriptlet that can directly be `eval`ed.
+
+--points-at=<object>::
+       Only list refs which points at the given object.
+
+--merged[=<object>]::
+       Only list refs whose tips are reachable from the
+       specified commit (HEAD if not specified).
+
+--no-merged[=<object>]::
+       Only list refs whose tips are not reachable from the
+       specified commit (HEAD if not specified).
+
+--contains[=<object>]::
+       Only list refs which contain the specified commit (HEAD if not
+       specified).
+
+--no-contains[=<object>]::
+       Only list refs which don't contain the specified commit (HEAD
+       if not specified).
+
+--ignore-case::
+       Sorting and filtering refs are case insensitive.
+
+--omit-empty::
+       Do not print a newline after formatted refs where the format expands
+       to the empty string.
+
+--exclude=<pattern>::
+       If one or more patterns are given, only refs which do not match
+       any excluded pattern(s) are shown. Matching is done using the
+       same rules as `<pattern>` above.
+
+--include-root-refs::
+       List root refs (HEAD and pseudorefs) apart from regular refs.
+
+--start-after=<marker>::
+    Allows paginating the output by skipping references up to and including the
+    specified marker. When paging, it should be noted that references may be
+    deleted, modified or added between invocations. Output will only yield those
+    references which follow the marker lexicographically. Output begins from the
+    first reference that would come after the marker alphabetically. Cannot be
+    used with `--sort=<key>` or `--stdin` options, or the _<pattern>_ argument(s)
+    to limit the refs.

diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc
index 060940904da21cb7d8b2cbace8c2d169a49080df..130d452de0efe18a7272522d148619c8d929eff7 100644 (file)
--- a/Documentation/git-for-each-ref.adoc
+++ b/Documentation/git-for-each-ref.adoc
@@ -28,94 +28,7 @@ host language allowing their direct evaluation in that language.
 
 OPTIONS
 -------
-<pattern>...::
-       If one or more patterns are given, only refs are shown that
-       match against at least one pattern, either using fnmatch(3) or
-       literally, in the latter case matching completely or from the
-       beginning up to a slash.
-
---stdin::
-       If `--stdin` is supplied, then the list of patterns is read from
-       standard input instead of from the argument list.
-
---count=<count>::
-       By default the command shows all refs that match
-       `<pattern>`.  This option makes it stop after showing
-       that many refs.
-
---sort=<key>::
-       A field name to sort on.  Prefix `-` to sort in
-       descending order of the value.  When unspecified,
-       `refname` is used.  You may use the --sort=<key> option
-       multiple times, in which case the last key becomes the primary
-       key.
-
---format=<format>::
-       A string that interpolates `%(fieldname)` from a ref being shown and
-       the object it points at. In addition, the string literal `%%`
-       renders as `%` and `%xx` - where `xx` are hex digits - renders as
-       the character with hex code `xx`. For example, `%00` interpolates to
-       `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).
-+
-When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)
-TAB %(refname)`.
-
---color[=<when>]::
-       Respect any colors specified in the `--format` option. The
-       `<when>` field must be one of `always`, `never`, or `auto` (if
-       `<when>` is absent, behave as if `always` was given).
-
---shell::
---perl::
---python::
---tcl::
-       If given, strings that substitute `%(fieldname)`
-       placeholders are quoted as string literals suitable for
-       the specified host language.  This is meant to produce
-       a scriptlet that can directly be `eval`ed.
-
---points-at=<object>::
-       Only list refs which points at the given object.
-
---merged[=<object>]::
-       Only list refs whose tips are reachable from the
-       specified commit (HEAD if not specified).
-
---no-merged[=<object>]::
-       Only list refs whose tips are not reachable from the
-       specified commit (HEAD if not specified).
-
---contains[=<object>]::
-       Only list refs which contain the specified commit (HEAD if not
-       specified).
-
---no-contains[=<object>]::
-       Only list refs which don't contain the specified commit (HEAD
-       if not specified).
-
---ignore-case::
-       Sorting and filtering refs are case insensitive.
-
---omit-empty::
-       Do not print a newline after formatted refs where the format expands
-       to the empty string.
-
---exclude=<pattern>::
-       If one or more patterns are given, only refs which do not match
-       any excluded pattern(s) are shown. Matching is done using the
-       same rules as `<pattern>` above.
-
---include-root-refs::
-       List root refs (HEAD and pseudorefs) apart from regular refs.
-
---start-after=<marker>::
-    Allows paginating the output by skipping references up to and including the
-    specified marker. When paging, it should be noted that references may be
-    deleted, modified or added between invocations. Output will only yield those
-    references which follow the marker lexicographically. Output begins from the
-    first reference that would come after the marker alphabetically. Cannot be
-    used with `--sort=<key>` or `--stdin` options, or the _<pattern>_ argument(s)
-    to limit the refs.
+include::for-each-ref-options.adoc[]
 
 FIELD NAMES
 -----------