diff options
Diffstat (limited to 'Documentation/git-for-each-ref.txt')
| -rw-r--r-- | Documentation/git-for-each-ref.txt | 86 |
1 files changed, 67 insertions, 19 deletions
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 901faef1bf..2ae2478de7 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -11,7 +11,7 @@ SYNOPSIS 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)...] [--format=<format>] [<pattern>...] [--points-at=<object>] - (--merged[=<object>] | --no-merged[=<object>]) + [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] DESCRIPTION @@ -76,13 +76,11 @@ OPTIONS --merged[=<object>]:: Only list refs whose tips are reachable from the - specified commit (HEAD if not specified), - incompatible with `--no-merged`. + 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), - incompatible with `--merged`. + specified commit (HEAD if not specified). --contains[=<object>]:: Only list refs which contain the specified commit (HEAD if not @@ -128,13 +126,18 @@ objecttype:: objectsize:: The size of the object (the same as 'git cat-file -s' reports). - + Append `:disk` to get the size, in bytes, that the object takes up on + disk. See the note about on-disk sizes in the `CAVEATS` section below. objectname:: The object name (aka SHA-1). For a non-ambiguous abbreviation of the object name append `:short`. For an abbreviation of the object name with desired length append `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The length may be exceeded to ensure unique object names. +deltabase:: + This expands to the object name of the delta base for the + given object, if it is stored as a delta. Otherwise it + expands to the null object name (all zeroes). upstream:: The name of a local ref which can be considered ``upstream'' @@ -209,9 +212,16 @@ symref:: `:lstrip` and `:rstrip` options in the same way as `refname` above. +worktreepath:: + The absolute path to the worktree in which the ref is checked + out, if it is checked out in any linked worktree. Empty string + otherwise. + In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can be used to specify the value in the header field. +Fields `tree` and `parent` can also be used with modifier `:short` and +`:short=<length>` just like `objectname`. For commit and tag objects, the special `creatordate` and `creator` fields will correspond to the appropriate date or name-email-date tuple @@ -220,20 +230,39 @@ These are intended for working on a mix of annotated and lightweight tags. Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, -and `date` to extract the named component. - -The complete message in a commit and tag object is `contents`. -Its first line is `contents:subject`, where subject is the concatenation -of all lines of the commit message up to the first blank line. The next -line is `contents:body`, where body is all of the lines after the first -blank line. The optional GPG signature is `contents:signature`. The -first `N` lines of the message is obtained using `contents:lines=N`. +and `date` to extract the named component. For email fields (`authoremail`, +`committeremail` and `taggeremail`), `:trim` can be appended to get the email +without angle brackets, and `:localpart` to get the part before the `@` symbol +out of the trimmed email. + +The message in a commit or a tag object is `contents`, from which +`contents:<part>` can be used to extract various parts out of: + +contents:size:: + The size in bytes of the commit or tag message. + +contents:subject:: + The first paragraph of the message, which typically is a + single line, is taken as the "subject" of the commit or the + tag message. + Instead of `contents:subject`, field `subject` can also be used to + obtain same results. `:sanitize` can be appended to `subject` for + subject line suitable for filename. + +contents:body:: + The remainder of the commit or the tag message that follows + the "subject". + +contents:signature:: + The optional GPG signature of the tag. + +contents:lines=N:: + The first `N` lines of the message. + Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] -are obtained as `trailers` (or by using the historical alias -`contents:trailers`). Non-trailer lines from the trailer block can be omitted -with `trailers:only`. Whitespace-continuations can be removed from trailers so -that each trailer appears on a line by itself with its full content with -`trailers:unfold`. Both can be used together as `trailers:unfold,only`. +are obtained as `trailers[:options]` (or by using the historical alias +`contents:trailers[:options]`). For valid [:option] values see `trailers` +section of linkgit:git-log[1]. For sorting purposes, fields with numeric values sort in numeric order (`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`). @@ -361,6 +390,25 @@ This prints the authorname, if present. git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)" ------------ +CAVEATS +------- + +Note that the sizes of objects on disk are reported accurately, but care +should be taken in drawing conclusions about which refs or objects are +responsible for disk usage. The size of a packed non-delta object may be +much larger than the size of objects which delta against it, but the +choice of which object is the base and which is the delta is arbitrary +and is subject to change during a repack. + +Note also that multiple copies of an object may be present in the object +database; in this case, it is undefined which copy's size or delta base +will be reported. + +NOTES +----- + +include::ref-reachability-filters.txt[] + SEE ALSO -------- linkgit:git-show-ref[1] |