ref-filter: add docs for new options
Add documentation for formatting options objectsize:disk and deltabase. Signed-off-by: Olga Telezhnaia <olyatelezhnaya@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Olga Telezhnaya committed
Dec 24, 2018 at 13:24 UTC
59012fe5e8f7485a48544324054f24aebfff3b38
1 file changed
+20
-1
Documentation/git-for-each-ref.txt
+20
-1
@@ -128,13 +128,18 @@ objecttype::
128
129
objectsize::
130
The size of the object (the same as 'git cat-file -s' reports).
131
-
131
+ Append `:disk` to get the size, in bytes, that the object takes up on
132
+ disk. See the note about on-disk sizes in the `CAVEATS` section below.
133
objectname::
134
The object name (aka SHA-1).
135
For a non-ambiguous abbreviation of the object name append `:short`.
136
For an abbreviation of the object name with desired length append
137
`:short=<length>`, where the minimum length is MINIMUM_ABBREV. The
138
length may be exceeded to ensure unique object names.
139
+deltabase::
140
+ This expands to the object name of the delta base for the
141
+ given object, if it is stored as a delta. Otherwise it
142
+ expands to the null object name (all zeroes).
143
144
upstream::
145
The name of a local ref which can be considered ``upstream''
@@ -361,6 +366,20 @@ This prints the authorname, if present.
366
git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
367
------------
368
369
+CAVEATS
370
+-------
371
+
372
+Note that the sizes of objects on disk are reported accurately, but care
373
+should be taken in drawing conclusions about which refs or objects are
374
+responsible for disk usage. The size of a packed non-delta object may be
375
+much larger than the size of objects which delta against it, but the
376
+choice of which object is the base and which is the delta is arbitrary
377
+and is subject to change during a repack.
378
+
379
+Note also that multiple copies of an object may be present in the object
380
+database; in this case, it is undefined which copy's size or delta base
381
+will be reported.
382
+
383
SEE ALSO
384
--------
385
linkgit:git-show-ref[1]