From: Junio C Hamano Date: Mon, 25 Aug 2025 21:22:01 +0000 (-0700) Subject: Merge branch 'ja/doc-lint-sections-and-synopsis' X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=0d8f4ccfe3b13bb5eb95f030dc5fe76efb255397;p=thirdparty%2Fgit.git Merge branch 'ja/doc-lint-sections-and-synopsis' Doc lint updates to encourage the newer and easier-to-use `synopsis` format, with fixes to a handful of existing uses. * ja/doc-lint-sections-and-synopsis: doc lint: check that synopsis manpages have synopsis inlines doc:git-for-each-ref: fix styling and typos doc: check for absence of the form --[no-]parameter doc: check for absence of multiple terms in each entry of desc list doc: check well-formedness of delimited sections doc: test linkgit macros for well-formedness --- 0d8f4ccfe3b13bb5eb95f030dc5fe76efb255397 diff --cc Documentation/for-each-ref-options.adoc index 4a033d3e16,0000000000..f13efb5f25 mode 100644,000000..100644 --- a/Documentation/for-each-ref-options.adoc +++ b/Documentation/for-each-ref-options.adoc @@@ -1,88 -1,0 +1,85 @@@ - ...:: - If one or more patterns are given, only refs are shown that - match against at least one pattern, either using fnmatch(3) or ++`...`:: ++ If one or more __ parameters 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. ++`--stdin`:: ++ The list of patterns is read from standard input instead of from ++ the argument list. + - --count=:: - By default the command shows all refs that match - ``. This option makes it stop after showing - that many refs. ++`--count=`:: ++ Stop after showing __ refs. + - --sort=:: - A field name to sort on. Prefix `-` to sort in ++`--sort=`:: ++ Sort on the field name __. Prefix `-` to sort in + descending order of the value. When unspecified, - `refname` is used. You may use the --sort= option ++ `refname` is used. You may use the `--sort=` 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, `` defaults to `%(objectname) SPC %(objecttype) ++ `\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_). ++ ++When unspecified, __ defaults to `%(objectname) SPC %(objecttype) +TAB %(refname)`. + - --color[=]:: ++`--color[=]`:: + Respect any colors specified in the `--format` option. The - `` field must be one of `always`, `never`, or `auto` (if ++ _` is absent, behave as if `always` was given). + - --shell:: - --perl:: - --python:: - --tcl:: ++`--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. ++ a scriptlet that can directly be "eval"ed. + - --points-at=:: ++`--points-at=`:: + Only list refs which points at the given object. + - --merged[=]:: ++`--merged[=]`:: + Only list refs whose tips are reachable from the - specified commit (HEAD if not specified). - - --no-merged[=]:: - Only list refs whose tips are not reachable from the - specified commit (HEAD if not specified). ++ specified commit (`HEAD` if not specified). + - --contains[=]:: - Only list refs which contain the specified commit (HEAD if not ++`--no-merged[=]`:: ++ Only list refs whose tips are not reachable from __(`HEAD` if not + specified). + - --no-contains[=]:: - Only list refs which don't contain the specified commit (HEAD ++`--contains[=]`:: ++ Only list refs which contain __(`HEAD` if not specified). ++ ++`--no-contains[=]`:: ++ Only list refs which don't contain __ (`HEAD` + if not specified). + - --ignore-case:: ++`--ignore-case`:: + Sorting and filtering refs are case insensitive. + - --omit-empty:: ++`--omit-empty`:: + Do not print a newline after formatted refs where the format expands + to the empty string. + - --exclude=:: - 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 `` above. ++`--exclude=`:: ++ If one or more `--exclude` options are given, only refs which do not ++ match any __ parameters are shown. Matching is done ++ using the same rules as __ above. + - --include-root-refs:: - List root refs (HEAD and pseudorefs) apart from regular refs. ++`--include-root-refs`:: ++ List root refs (`HEAD` and pseudorefs) apart from regular refs. + - --start-after=:: ++`--start-after=`:: + 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=` or `--stdin` options, or the __ argument(s) + to limit the refs. diff --cc Documentation/git-refs.adoc index e608980711,5d26de8acb..d462953fb5 --- a/Documentation/git-refs.adoc +++ b/Documentation/git-refs.adoc @@@ -11,13 -11,6 +11,13 @@@ SYNOPSI [synopsis] git refs migrate --ref-format= [--no-reflog] [--dry-run] git refs verify [--strict] [--verbose] +git refs list [--count=] [--shell|--perl|--python|--tcl] + [(--sort=)...] [--format=] + [--include-root-refs] [--points-at=] + [--merged[=]] [--no-merged[=]] + [--contains[=]] [--no-contains[=]] + [(--exclude=)...] [--start-after=] - [ --stdin | ... ] ++ [ --stdin | (...)] DESCRIPTION ----------- @@@ -27,17 -20,12 +27,17 @@@ This command provides low-level access COMMANDS -------- - migrate:: + `migrate`:: Migrate ref store between different formats. - verify:: + `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 ------- @@@ -66,13 -54,9 +66,13 @@@ The following options are specific to ` Enable stricter error checking. This will cause warnings to be reported as errors. See linkgit:git-fsck[1]. - --verbose:: + `--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 --cc for-each-ref.h index a5e0b6d17a,0000000000..c8d0219179 mode 100644,000000..100644 --- a/for-each-ref.h +++ b/for-each-ref.h @@@ -1,26 -1,0 +1,26 @@@ +#ifndef FOR_EACH_REF_H +#define FOR_EACH_REF_H + +struct repository; + +/* + * Shared usage string for options common to git-for-each-ref(1) + * and git-refs-list(1). The command-specific part (e.g., "git refs list ") + * must be prepended by the caller. + */ +#define COMMON_USAGE_FOR_EACH_REF \ + "[--count=] [--shell|--perl|--python|--tcl]\n" \ + " [(--sort=)...] [--format=]\n" \ + " [--include-root-refs] [--points-at=]\n" \ + " [--merged[=]] [--no-merged[=]]\n" \ + " [--contains[=]] [--no-contains[=]]\n" \ + " [(--exclude=)...] [--start-after=]\n" \ - " [ --stdin | ... ]" ++ " [ --stdin | (...)]" + +/* + * The core logic for for-each-ref and its clones. + */ +int for_each_ref_core(int argc, const char **argv, const char *prefix, + struct repository *repo, const char *const *usage); + +#endif /* FOR_EACH_REF_H */