Autogenerated HTML docs for v2.51.0-87-g1fa68
diff --git a/RelNotes/2.52.0.adoc b/RelNotes/2.52.0.adoc
index 1919e03..f96aa8d 100644
--- a/RelNotes/2.52.0.adoc
+++ b/RelNotes/2.52.0.adoc
@@ -4,6 +4,9 @@
UI, Workflows & Features
------------------------
+ * The "list" subcommand of "git refs" acts as a front-end for
+ "git for-each-ref".
+
Performance, Internal Implementation, Development Support etc.
--------------------------------------------------------------
@@ -21,6 +24,7 @@
contained wildcards; now they take advantage of the filter when
they can.
+
Fixes since v2.51
-----------------
@@ -52,7 +56,26 @@
been fixed.
(merge f6ecb603ff en/ort-rename-fixes later to maint).
+ * "git jump" (in contrib/) fails to parse the diff header correctly
+ when a file has a space in its name, which has been corrected.
+ (merge 621ce9c1c6 gh/git-jump-pathname-with-sp later to maint).
+
+ * "git diff --no-index" run inside a subdirectory under control of a
+ Git repository operated at the top of the working tree and stripped
+ the prefix from the output, and oddballs like "-" (stdin) did not
+ work correctly because of it. Correct the set-up by undoing what
+ the set-up sequence did to cwd and prefix.
+ (merge e1d3d61a45 jc/diff-no-index-in-subdir later to maint).
+
+ * Various options to "git diff" that makes comparison ignore certain
+ aspects of the differences (like "space changes are ignored",
+ "differences in lines that match these regular expressions are
+ ignored") did not work well with "--name-only" and friends.
+ (merge b55e6d36eb ly/diff-name-only-with-diff-from-content later to maint).
+
* Other code cleanup, docfix, build fix, etc.
(merge 823d537fa7 kh/doc-git-log-markup-fix later to maint).
(merge cf7efa4f33 rj/t6137-cygwin-fix later to maint).
(merge 529a60a885 ua/t1517-short-help-tests later to maint).
+ (merge 22d421fed9 ac/deglobal-fmt-merge-log-config later to maint).
+ (merge 741f36c7d9 kr/clone-synopsis-fix later to maint).
diff --git a/for-each-ref-options.adoc b/for-each-ref-options.adoc
new file mode 100644
index 0000000..4a033d3
--- /dev/null
+++ b/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/git-clone.adoc b/git-clone.adoc
index 222d558..d829206 100644
--- a/git-clone.adoc
+++ b/git-clone.adoc
@@ -16,7 +16,7 @@
[--depth <depth>] [--[no-]single-branch] [--[no-]tags]
[--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
[--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
- [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+ [--filter=<filter-spec> [--also-filter-submodules]] [--] <repository>
[<directory>]
DESCRIPTION
diff --git a/git-clone.html b/git-clone.html
index 54f1215..5f50abc 100644
--- a/git-clone.html
+++ b/git-clone.html
@@ -459,7 +459,7 @@
[<code>--depth</code> <em><depth></em>] [<code>--</code>[<code>no-</code>]<code>single-branch</code>] [<code>--</code>[<code>no-</code>]<code>tags</code>]
[<code>--recurse-submodules</code>[<code>=</code><em><pathspec></em>]] [<code>--</code>[<code>no-</code>]<code>shallow-submodules</code>]
[<code>--</code>[<code>no-</code>]<code>remote-submodules</code>] [<code>--jobs</code> <em><n></em>] [<code>--sparse</code>] [<code>--</code>[<code>no-</code>]<code>reject-shallow</code>]
- [<code>--filter=</code><em><filter-spec></em>] [<code>--also-filter-submodules</code>]] [<code>--</code>] <em><repository></em>
+ [<code>--filter=</code><em><filter-spec></em> [<code>--also-filter-submodules</code>]] [<code>--</code>] <em><repository></em>
[<em><directory></em>]</pre>
</div>
</div>
@@ -1151,7 +1151,7 @@
</div>
<div id="footer">
<div id="footer-text">
-Last updated 2025-06-20 18:10:42 -0700
+Last updated 2025-08-22 13:19:47 -0700
</div>
</div>
</body>
diff --git a/git-for-each-ref.adoc b/git-for-each-ref.adoc
index 0609409..130d452 100644
--- a/git-for-each-ref.adoc
+++ b/git-for-each-ref.adoc
@@ -28,94 +28,7 @@
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
-----------
diff --git a/git-refs.adoc b/git-refs.adoc
index 4d6dc99..e608980 100644
--- a/git-refs.adoc
+++ b/git-refs.adoc
@@ -11,6 +11,13 @@
[synopsis]
git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]
git refs verify [--strict] [--verbose]
+git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
+ [(--sort=<key>)...] [--format=<format>]
+ [--include-root-refs] [--points-at=<object>]
+ [--merged[=<object>]] [--no-merged[=<object>]]
+ [--contains[=<object>]] [--no-contains[=<object>]]
+ [(--exclude=<pattern>)...] [--start-after=<marker>]
+ [ --stdin | <pattern>... ]
DESCRIPTION
-----------
@@ -26,6 +33,11 @@
verify::
Verify reference database consistency.
+list::
+ List references in the repository with support for filtering,
+ formatting, and sorting. This subcommand is an alias for
+ linkgit:git-for-each-ref[1] and offers identical functionality.
+
OPTIONS
-------
@@ -57,6 +69,10 @@
--verbose::
When verifying the reference database consistency, be chatty.
+The following options are specific to 'git refs list':
+
+include::for-each-ref-options.adoc[]
+
KNOWN LIMITATIONS
-----------------
diff --git a/git-refs.html b/git-refs.html
index 556d375..f464d11 100644
--- a/git-refs.html
+++ b/git-refs.html
@@ -453,7 +453,14 @@
<div class="sectionbody">
<div class="verseblock">
<pre class="content"><code>git</code> <code>refs</code> <code>migrate</code> <code>--ref-format=</code><em><format></em> [<code>--no-reflog</code>] [<code>--dry-run</code>]
-<code>git</code> <code>refs</code> <code>verify</code> [<code>--strict</code>] [<code>--verbose</code>]</pre>
+<code>git</code> <code>refs</code> <code>verify</code> [<code>--strict</code>] [<code>--verbose</code>]
+<code>git</code> <code>refs</code> <code>list</code> [<code>--count=</code><em><count></em>] [<code>--shell</code>|<code>--perl</code>|<code>--python</code>|<code>--tcl</code>]
+ [(<code>--sort=</code><em><key></em>)…​] [<code>--format=</code><em><format></em>]
+ [<code>--include-root-refs</code>] [<code>--points-at=</code><em><object></em>]
+ [<code>--merged</code>[<code>=</code><em><object></em>]] [<code>--no-merged</code>[<code>=</code><em><object></em>]]
+ [<code>--contains</code>[<code>=</code><em><object></em>]] [<code>--no-contains</code>[<code>=</code><em><object></em>]]
+ [(<code>--exclude=</code><em><pattern></em>)…​] [<code>--start-after=</code><em><marker></em>]
+ [ <code>--stdin</code> | <em><pattern></em>…​ ]</pre>
</div>
</div>
</div>
@@ -478,6 +485,12 @@
<dd>
<p>Verify reference database consistency.</p>
</dd>
+<dt class="hdlist1">list</dt>
+<dd>
+<p>List references in the repository with support for filtering,
+formatting, and sorting. This subcommand is an alias for
+<a href="git-for-each-ref.html">git-for-each-ref(1)</a> and offers identical functionality.</p>
+</dd>
</dl>
</div>
</div>
@@ -537,6 +550,120 @@
</dd>
</dl>
</div>
+<div class="paragraph">
+<p>The following options are specific to <em>git refs list</em>:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><pattern>…​</dt>
+<dd>
+<p>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.</p>
+</dd>
+<dt class="hdlist1">--stdin</dt>
+<dd>
+<p>If <code>--stdin</code> is supplied, then the list of patterns is read from
+standard input instead of from the argument list.</p>
+</dd>
+<dt class="hdlist1">--count=<count></dt>
+<dd>
+<p>By default the command shows all refs that match
+<em><pattern></em>. This option makes it stop after showing
+that many refs.</p>
+</dd>
+<dt class="hdlist1">--sort=<key></dt>
+<dd>
+<p>A field name to sort on. Prefix <code>-</code> to sort in
+descending order of the value. When unspecified,
+<code>refname</code> is used. You may use the --sort=<key> option
+multiple times, in which case the last key becomes the primary
+key.</p>
+</dd>
+<dt class="hdlist1">--format=<format></dt>
+<dd>
+<p>A string that interpolates <code>%</code>(<code>fieldname</code>) from a ref being shown and
+the object it points at. In addition, the string literal <code>%%</code>
+renders as <code>%</code> and <code>%xx</code> - where <code>xx</code> are hex digits - renders as
+the character with hex code <code>xx</code>. For example, <code>%00</code> interpolates to
+<code>\0</code> (NUL), <code>%09</code> to <code>\t</code> (TAB), and <code>%0a</code> to <code>\n</code> (LF).</p>
+<div class="paragraph">
+<p>When unspecified, <em><format></em> defaults to <code>%</code>(<code>objectname</code>) <code>SPC</code> <code>%</code>(<code>objecttype</code>)
+<code>TAB</code> <code>%</code>(<code>refname</code>).</p>
+</div>
+</dd>
+<dt class="hdlist1">--color[=<when>]</dt>
+<dd>
+<p>Respect any colors specified in the <code>--format</code> option. The
+<em><when></em> field must be one of <code>always</code>, <code>never</code>, or <code>auto</code> (if
+<em><when></em> is absent, behave as if <code>always</code> was given).</p>
+</dd>
+<dt class="hdlist1">--shell</dt>
+<dt class="hdlist1">--perl</dt>
+<dt class="hdlist1">--python</dt>
+<dt class="hdlist1">--tcl</dt>
+<dd>
+<p>If given, strings that substitute <code>%</code>(<code>fieldname</code>)
+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.</p>
+</dd>
+<dt class="hdlist1">--points-at=<object></dt>
+<dd>
+<p>Only list refs which points at the given object.</p>
+</dd>
+<dt class="hdlist1">--merged[=<object>]</dt>
+<dd>
+<p>Only list refs whose tips are reachable from the
+specified commit (HEAD if not specified).</p>
+</dd>
+<dt class="hdlist1">--no-merged[=<object>]</dt>
+<dd>
+<p>Only list refs whose tips are not reachable from the
+specified commit (HEAD if not specified).</p>
+</dd>
+<dt class="hdlist1">--contains[=<object>]</dt>
+<dd>
+<p>Only list refs which contain the specified commit (HEAD if not
+specified).</p>
+</dd>
+<dt class="hdlist1">--no-contains[=<object>]</dt>
+<dd>
+<p>Only list refs which don’t contain the specified commit (HEAD
+if not specified).</p>
+</dd>
+<dt class="hdlist1">--ignore-case</dt>
+<dd>
+<p>Sorting and filtering refs are case insensitive.</p>
+</dd>
+<dt class="hdlist1">--omit-empty</dt>
+<dd>
+<p>Do not print a newline after formatted refs where the format expands
+to the empty string.</p>
+</dd>
+<dt class="hdlist1">--exclude=<pattern></dt>
+<dd>
+<p>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 <em><pattern></em> above.</p>
+</dd>
+<dt class="hdlist1">--include-root-refs</dt>
+<dd>
+<p>List root refs (HEAD and pseudorefs) apart from regular refs.</p>
+</dd>
+<dt class="hdlist1">--start-after=<marker></dt>
+<dd>
+<p>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 <code>--sort=</code><em><key></em> or <code>--stdin</code> options, or the <em><pattern></em> argument(s)
+to limit the refs.</p>
+</dd>
+</dl>
+</div>
</div>
</div>
<div class="sect1">
@@ -575,7 +702,7 @@
</div>
<div id="footer">
<div id="footer-text">
-Last updated 2025-06-20 18:10:42 -0700
+Last updated 2025-08-22 13:19:47 -0700
</div>
</div>
</body>
