Re: [RFC PATCH 5/5] ref-filter: add docs for new options

[Junio C Hamano]

Olga Telezhnaya  writes:

>  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=`, where the minimum length is MINIMUM_ABBREV. The
>   length may be exceeded to ensure unique object names.
> +deltabase::
> + If the object is stored as a delta on-disk, this expands to the 40-hex
> + sha1 of the delta base object. Otherwise, expands to the null sha1
> + (40 zeroes). See `CAVEATS` section below.

I know existing description for other things nearby still talk about
SHA-1, but we can prepare ourselves better with something like:

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).

> +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.

OK.


>  SEE ALSO
>  
>  linkgit:git-show-ref[1]
>
> --
> https://github.com/git/git/pull/552

[RFC PATCH 5/5] ref-filter: add docs for new options

[Olga Telezhnaya]

Add documentation for formatting options objectsize:disk
and deltabase.

Signed-off-by: Olga Telezhnaia 
---
 Documentation/git-for-each-ref.txt | 21 -
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-for-each-ref.txt 
b/Documentation/git-for-each-ref.txt
index 901faef1bfdce..22d2ff88110cd 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -128,13 +128,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=`, where the minimum length is MINIMUM_ABBREV. The
length may be exceeded to ensure unique object names.
+deltabase::
+   If the object is stored as a delta on-disk, this expands to the 40-hex
+   sha1 of the delta base object. Otherwise, expands to the null sha1
+   (40 zeroes). See `CAVEATS` section below.
 
 upstream::
The name of a local ref which can be considered ``upstream''
@@ -361,6 +366,20 @@ 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.
+
 SEE ALSO
 
 linkgit:git-show-ref[1]

--
https://github.com/git/git/pull/552