freshlybakedca.ke / git
Git fork
fork atom

doc:git-for-each-ref: fix styling and typos

This commit fixes the synopsis syntax and changes the wording of a few
descriptions to be more consistent with the rest of the documentation.

It is a prepartion for the next commit that checks that synopsis style is
applied consistently across a manual page.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

authored by

Jean-Noël Avila and committed by
Junio C Hamano 93203872 03a353bb

+131 -131
unified split
+131 -131
Documentation/git-for-each-ref.adoc
··· 14 14 [--merged[=<object>]] [--no-merged[=<object>]] 15 15 [--contains[=<object>]] [--no-contains[=<object>]] 16 16 [(--exclude=<pattern>)...] [--start-after=<marker>] 17 - [ --stdin | <pattern>... ] 17 + [ --stdin | (<pattern>...)] 18 18 19 19 DESCRIPTION 20 20 ----------- 21 21 22 - Iterate over all refs that match `<pattern>` and show them 23 - according to the given `<format>`, after sorting them according 24 - to the given set of `<key>`. If `<count>` is given, stop after 25 - showing that many refs. The interpolated values in `<format>` 22 + Iterate over all refs that match _<pattern>_ and show them 23 + according to the given _<format>_, after sorting them according 24 + to the given set of _<key>_. If _<count>_ is given, stop after 25 + showing that many refs. The interpolated values in _<format>_ 26 26 can optionally be quoted as string literals in the specified 27 27 host language allowing their direct evaluation in that language. 28 28 29 29 OPTIONS 30 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 31 + `<pattern>...`:: 32 + If one or more _<pattern>_ parameters are given, only refs are shown that 33 + match against at least one pattern, either using `fnmatch`(3) or 34 34 literally, in the latter case matching completely or from the 35 35 beginning up to a slash. 36 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. 37 + `--stdin`:: 38 + The list of patterns is read from standard input instead of from 39 + the argument list. 40 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. 41 + `--count=<count>`:: 42 + Stop after showing _<count>_ refs. 45 43 46 - --sort=<key>:: 47 - A field name to sort on. Prefix `-` to sort in 44 + `--sort=<key>`:: 45 + Sort on the field name _<key>_. Prefix `-` to sort in 48 46 descending order of the value. When unspecified, 49 - `refname` is used. You may use the --sort=<key> option 47 + `refname` is used. You may use the `--sort=<key>` option 50 48 multiple times, in which case the last key becomes the primary 51 49 key. 52 50 53 - --format=<format>:: 51 + `--format[=<format>]`:: 54 52 A string that interpolates `%(fieldname)` from a ref being shown and 55 53 the object it points at. In addition, the string literal `%%` 56 54 renders as `%` and `%xx` - where `xx` are hex digits - renders as 57 55 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) 56 + `\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_). 57 + 58 + When unspecified, _<format>_ defaults to `%(objectname) SPC %(objecttype) 61 59 TAB %(refname)`. 62 60 63 - --color[=<when>]:: 61 + `--color[=<when>]`:: 64 62 Respect any colors specified in the `--format` option. The 65 - `<when>` field must be one of `always`, `never`, or `auto` (if 63 + _<when__ field must be one of `always`, `never`, or `auto` (if 66 64 `<when>` is absent, behave as if `always` was given). 67 65 68 - --shell:: 69 - --perl:: 70 - --python:: 71 - --tcl:: 66 + `--shell`:: 67 + `--perl`:: 68 + `--python`:: 69 + `--tcl`:: 72 70 If given, strings that substitute `%(fieldname)` 73 71 placeholders are quoted as string literals suitable for 74 72 the specified host language. This is meant to produce 75 - a scriptlet that can directly be `eval`ed. 73 + a scriptlet that can directly be "eval"ed. 76 74 77 - --points-at=<object>:: 75 + `--points-at=<object>`:: 78 76 Only list refs which points at the given object. 79 77 80 - --merged[=<object>]:: 78 + `--merged[=<object>]`:: 81 79 Only list refs whose tips are reachable from the 82 - specified commit (HEAD if not specified). 80 + specified commit (`HEAD` if not specified). 83 81 84 - --no-merged[=<object>]:: 85 - Only list refs whose tips are not reachable from the 86 - specified commit (HEAD if not specified). 82 + `--no-merged[=<object>]`:: 83 + Only list refs whose tips are not reachable from _<object>_(`HEAD` if not 84 + specified). 87 85 88 - --contains[=<object>]:: 89 - Only list refs which contain the specified commit (HEAD if not 90 - specified). 86 + `--contains[=<object>]`:: 87 + Only list refs which contain _<object>_(`HEAD` if not specified). 91 88 92 - --no-contains[=<object>]:: 93 - Only list refs which don't contain the specified commit (HEAD 89 + `--no-contains[=<object>]`:: 90 + Only list refs which don't contain _<object>_ (`HEAD` 94 91 if not specified). 95 92 96 - --ignore-case:: 93 + `--ignore-case`:: 97 94 Sorting and filtering refs are case insensitive. 98 95 99 - --omit-empty:: 96 + `--omit-empty`:: 100 97 Do not print a newline after formatted refs where the format expands 101 98 to the empty string. 102 99 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. 100 + `--exclude=<excluded-pattern>`:: 101 + If one or more `--exclude` options are given, only refs which do not 102 + match any _<excluded-pattern>_ parameters are shown. Matching is done 103 + using the same rules as _<pattern>_ above. 107 104 108 - --include-root-refs:: 109 - List root refs (HEAD and pseudorefs) apart from regular refs. 105 + `--include-root-refs`:: 106 + List root refs (`HEAD` and pseudorefs) apart from regular refs. 110 107 111 - --start-after=<marker>:: 108 + `--start-after=<marker>`:: 112 109 Allows paginating the output by skipping references up to and including the 113 110 specified marker. When paging, it should be noted that references may be 114 111 deleted, modified or added between invocations. Output will only yield those ··· 126 123 127 124 For all objects, the following names can be used: 128 125 129 - refname:: 130 - The name of the ref (the part after $GIT_DIR/). 126 + `refname`:: 127 + The name of the ref (the part after `$GIT_DIR/`). 131 128 For a non-ambiguous short name of the ref append `:short`. 132 - The option core.warnAmbiguousRefs is used to select the strict 133 - abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>` 129 + The option `core.warnAmbiguousRefs` is used to select the strict 130 + abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_ 134 131 slash-separated path components from the front (back) of the refname 135 132 (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and 136 133 `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). 137 - If `<N>` is a negative number, strip as many path components as 138 - necessary from the specified end to leave `-<N>` path components 134 + If _<n>_ is a negative number, strip as many path components as 135 + necessary from the specified end to leave `-<n>` path components 139 136 (e.g. `%(refname:lstrip=-2)` turns 140 137 `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` 141 138 turns `refs/tags/foo` into `refs`). When the ref does not have 142 139 enough components, the result becomes an empty string if 143 - stripping with positive <N>, or it becomes the full refname if 144 - stripping with negative <N>. Neither is an error. 140 + stripping with positive _<n>_, or it becomes the full refname if 141 + stripping with negative _<N>_. Neither is an error. 145 142 + 146 143 `strip` can be used as a synonym to `lstrip`. 147 144 148 - objecttype:: 145 + `objecttype`:: 149 146 The type of the object (`blob`, `tree`, `commit`, `tag`). 150 147 151 - objectsize:: 148 + `objectsize`:: 152 149 The size of the object (the same as 'git cat-file -s' reports). 153 150 Append `:disk` to get the size, in bytes, that the object takes up on 154 - disk. See the note about on-disk sizes in the `CAVEATS` section below. 155 - objectname:: 151 + disk. See the note about on-disk sizes in the 'CAVEATS' section below. 152 + `objectname`:: 156 153 The object name (aka SHA-1). 157 154 For a non-ambiguous abbreviation of the object name append `:short`. 158 155 For an abbreviation of the object name with desired length append 159 - `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The 156 + `:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The 160 157 length may be exceeded to ensure unique object names. 161 - deltabase:: 158 + `deltabase`:: 162 159 This expands to the object name of the delta base for the 163 160 given object, if it is stored as a delta. Otherwise it 164 161 expands to the null object name (all zeroes). 165 162 166 - upstream:: 163 + `upstream`:: 167 164 The name of a local ref which can be considered ``upstream'' 168 165 from the displayed ref. Respects `:short`, `:lstrip` and 169 166 `:rstrip` in the same way as `refname` above. Additionally ··· 185 182 with it. All the options apart from `nobracket` are mutually exclusive, 186 183 but if used together the last option is selected. 187 184 188 - push:: 185 + `push`:: 189 186 The name of a local ref which represents the `@{push}` 190 187 location for the displayed ref. Respects `:short`, `:lstrip`, 191 188 `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref` 192 189 options as `upstream` does. Produces an empty string if no `@{push}` 193 190 ref is configured. 194 191 195 - HEAD:: 196 - '*' if HEAD matches current ref (the checked out branch), ' ' 192 + `HEAD`:: 193 + `*` if `HEAD` matches current ref (the checked out branch), ' ' 197 194 otherwise. 198 195 199 - color:: 196 + `color`:: 200 197 Change output color. Followed by `:<colorname>`, where color 201 198 names are described under Values in the "CONFIGURATION FILE" 202 199 section of linkgit:git-config[1]. For example, 203 200 `%(color:bold red)`. 204 201 205 - align:: 202 + `align`:: 206 203 Left-, middle-, or right-align the content between 207 - %(align:...) and %(end). The "align:" is followed by 204 + `%(align:...)` and `%(end)`. The "`align:`" is followed by 208 205 `width=<width>` and `position=<position>` in any order 209 - separated by a comma, where the `<position>` is either left, 210 - right or middle, default being left and `<width>` is the total 206 + separated by a comma, where the _<position>_ is either `left`, 207 + `right` or `middle`, default being `left` and _<width>_ is the total 211 208 length of the content with alignment. For brevity, the 212 209 "width=" and/or "position=" prefixes may be omitted, and bare 213 - <width> and <position> used instead. For instance, 210 + _<width>_ and _<position>_ used instead. For instance, 214 211 `%(align:<width>,<position>)`. If the contents length is more 215 212 than the width then no alignment is performed. If used with 216 - `--quote` everything in between %(align:...) and %(end) is 213 + `--quote` everything in between `%(align:...)` and `%(end)` is 217 214 quoted, but if nested then only the topmost level performs 218 215 quoting. 219 216 220 - if:: 221 - Used as %(if)...%(then)...%(end) or 222 - %(if)...%(then)...%(else)...%(end). If there is an atom with 223 - value or string literal after the %(if) then everything after 224 - the %(then) is printed, else if the %(else) atom is used, then 217 + `if`:: 218 + Used as `%(if)...%(then)...%(end)` or 219 + `%(if)...%(then)...%(else)...%(end)`. If there is an atom with 220 + value or string literal after the `%(if)` then everything after 221 + the `%(then)` is printed, else if the `%(else)` atom is used, then 225 222 everything after %(else) is printed. We ignore space when 226 - evaluating the string before %(then), this is useful when we 227 - use the %(HEAD) atom which prints either "*" or " " and we 228 - want to apply the 'if' condition only on the 'HEAD' ref. 229 - Append ":equals=<string>" or ":notequals=<string>" to compare 230 - the value between the %(if:...) and %(then) atoms with the 223 + evaluating the string before `%(then)`, this is useful when we 224 + use the `%(HEAD)` atom which prints either "`*`" or " " and we 225 + want to apply the 'if' condition only on the `HEAD` ref. 226 + Append "`:equals=<string>`" or "`:notequals=<string>`" to compare 227 + the value between the `%(if:...)` and `%(then)` atoms with the 231 228 given string. 232 229 233 - symref:: 230 + `symref`:: 234 231 The ref which the given symbolic ref refers to. If not a 235 232 symbolic ref, nothing is printed. Respects the `:short`, 236 233 `:lstrip` and `:rstrip` options in the same way as `refname` 237 234 above. 238 235 239 - signature:: 236 + `signature`:: 240 237 The GPG signature of a commit. 241 238 242 - signature:grade:: 243 - Show "G" for a good (valid) signature, "B" for a bad 244 - signature, "U" for a good signature with unknown validity, "X" 245 - for a good signature that has expired, "Y" for a good 246 - signature made by an expired key, "R" for a good signature 247 - made by a revoked key, "E" if the signature cannot be 248 - checked (e.g. missing key) and "N" for no signature. 239 + `signature:grade`:: 240 + Show 241 + `G`;; for a good (valid) signature 242 + `B`;; for a bad signature 243 + `U`;; for a good signature with unknown validity 244 + `X`;; for a good signature that has expired 245 + `Y`;; for a good signature made by an expired key 246 + `R`;; for a good signature made by a revoked key 247 + `E`;; if the signature cannot be checked (e.g. missing key) 248 + `N`;; for no signature. 249 249 250 - signature:signer:: 250 + `signature:signer`:: 251 251 The signer of the GPG signature of a commit. 252 252 253 - signature:key:: 253 + `signature:key`:: 254 254 The key of the GPG signature of a commit. 255 255 256 - signature:fingerprint:: 256 + `signature:fingerprint`:: 257 257 The fingerprint of the GPG signature of a commit. 258 258 259 - signature:primarykeyfingerprint:: 259 + `signature:primarykeyfingerprint`:: 260 260 The primary key fingerprint of the GPG signature of a commit. 261 261 262 - signature:trustlevel:: 262 + `signature:trustlevel`:: 263 263 The trust level of the GPG signature of a commit. Possible 264 264 outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. 265 265 266 - worktreepath:: 266 + `worktreepath`:: 267 267 The absolute path to the worktree in which the ref is checked 268 268 out, if it is checked out in any linked worktree. Empty string 269 269 otherwise. 270 270 271 - ahead-behind:<committish>:: 271 + `ahead-behind:<commit-ish>`:: 272 272 Two integers, separated by a space, demonstrating the number of 273 273 commits ahead and behind, respectively, when comparing the output 274 - ref to the `<committish>` specified in the format. 274 + ref to the _<committish>_ specified in the format. 275 275 276 - is-base:<committish>:: 277 - In at most one row, `(<committish>)` will appear to indicate the ref 276 + `is-base:<commit-ish>`:: 277 + In at most one row, `(<commit-ish>)` will appear to indicate the ref 278 278 that is most likely the ref used as a starting point for the branch 279 - that produced `<committish>`. This choice is made using a heuristic: 279 + that produced _<commit-ish>_. This choice is made using a heuristic: 280 280 choose the ref that minimizes the number of commits in the 281 - first-parent history of `<committish>` and not in the first-parent 281 + first-parent history of _<commit-ish>_ and not in the first-parent 282 282 history of the ref. 283 283 + 284 284 For example, consider the following figure of first-parent histories of ··· 312 312 earliest ref in the sorted order. 313 313 + 314 314 Note that this token will not appear if the first-parent history of 315 - `<committish>` does not intersect the first-parent histories of the 315 + _<commit-ish>_ does not intersect the first-parent histories of the 316 316 filtered refs. 317 317 318 - describe[:options]:: 318 + `describe[:<option>,...]`:: 319 319 A human-readable name, like linkgit:git-describe[1]; 320 320 empty string for undescribable commits. The `describe` string may 321 321 be followed by a colon and one or more comma-separated options. 322 322 + 323 323 -- 324 - tags=<bool-value>;; 324 + `tags=<bool-value>`;; 325 325 Instead of only considering annotated tags, consider 326 326 lightweight tags as well; see the corresponding option in 327 327 linkgit:git-describe[1] for details. 328 - abbrev=<number>;; 329 - Use at least <number> hexadecimal digits; see the corresponding 328 + `abbrev=<number>`;; 329 + Use at least _<number>_ hexadecimal digits; see the corresponding 330 330 option in linkgit:git-describe[1] for details. 331 - match=<pattern>;; 332 - Only consider tags matching the given `glob(7)` pattern, 333 - excluding the "refs/tags/" prefix; see the corresponding option 331 + `match=<pattern>`;; 332 + Only consider tags matching the `glob`(7) _<pattern>_, 333 + excluding the `refs/tags/` prefix; see the corresponding option 334 334 in linkgit:git-describe[1] for details. 335 - exclude=<pattern>;; 336 - Do not consider tags matching the given `glob(7)` pattern, 337 - excluding the "refs/tags/" prefix; see the corresponding option 335 + `exclude=<pattern>`;; 336 + Do not consider tags matching the `glob`(7) _<pattern>_, 337 + excluding the `refs/tags/` prefix; see the corresponding option 338 338 in linkgit:git-describe[1] for details. 339 339 -- 340 340 ··· 366 366 367 367 The raw data in an object is `raw`. 368 368 369 - raw:size:: 369 + `raw:size`:: 370 370 The raw data size of the object. 371 371 372 372 Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`, ··· 376 376 The message in a commit or a tag object is `contents`, from which 377 377 `contents:<part>` can be used to extract various parts out of: 378 378 379 - contents:size:: 379 + `contents:size`:: 380 380 The size in bytes of the commit or tag message. 381 381 382 - contents:subject:: 382 + `contents:subject`:: 383 383 The first paragraph of the message, which typically is a 384 384 single line, is taken as the "subject" of the commit or the 385 385 tag message. ··· 387 387 obtain same results. `:sanitize` can be appended to `subject` for 388 388 subject line suitable for filename. 389 389 390 - contents:body:: 390 + `contents:body`:: 391 391 The remainder of the commit or the tag message that follows 392 392 the "subject". 393 393 394 - contents:signature:: 394 + `contents:signature`:: 395 395 The optional GPG signature of the tag. 396 396 397 - contents:lines=N:: 398 - The first `N` lines of the message. 397 + `contents:lines=<n>`:: 398 + The first _<n>_ lines of the message. 399 399 400 400 Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] 401 - are obtained as `trailers[:options]` (or by using the historical alias 402 - `contents:trailers[:options]`). For valid [:option] values see `trailers` 401 + are obtained as `trailers[:<option>,...]` (or by using the historical alias 402 + `contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers` 403 403 section of linkgit:git-log[1]. 404 404 405 405 For sorting purposes, fields with numeric values sort in numeric order ··· 419 419 a `--sort` key, references will be sorted according to the byte-value of the 420 420 formatted string rather than the numeric value of the underlying timestamp. 421 421 422 - Some atoms like %(align) and %(if) always require a matching %(end). 423 - We call them "opening atoms" and sometimes denote them as %($open). 422 + Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`. 423 + We call them "opening atoms" and sometimes denote them as `%($open)`. 424 424 425 425 When a scripting language specific quoting is in effect, everything 426 426 between a top-level opening atom and its matching %(end) is evaluated ··· 438 438 #!/bin/sh 439 439 440 440 git for-each-ref --count=3 --sort='-*authordate' \ 441 - --format='From: %(*authorname) %(*authoremail) 441 + `--format='From: %(*authorname) %(*authoremail) 442 442 Subject: %(*subject) 443 443 Date: %(*authordate) 444 444 Ref: %(*refname) ··· 449 449 450 450 451 451 A simple example showing the use of shell eval on the output, 452 - demonstrating the use of --shell. List the prefixes of all heads: 452 + demonstrating the use of `--shell`. List the prefixes of all heads: 453 453 454 454 ------------ 455 455 #!/bin/sh ··· 517 517 ------------ 518 518 519 519 520 - An example to show the usage of %(if)...%(then)...%(else)...%(end). 520 + An example to show the usage of `%(if)...%(then)...%(else)...%(end)`. 521 521 This prefixes the current branch with a star. 522 522 523 523 ------------ ··· 525 525 ------------ 526 526 527 527 528 - An example to show the usage of %(if)...%(then)...%(end). 528 + An example to show the usage of `%(if)...%(then)...%(end)`. 529 529 This prints the authorname, if present. 530 530 531 531 ------------