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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 12, 2018, 05:24 UTC
Message-ID: <xmqqmuqe3m1o.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <01020166f76d851b-3a0f5414-48ce-4172-8200-0a59fd3f66d9-000000@eu-west-1.amazonses.com>

Olga Telezhnaya <olyatelezhnaya@gmail.com> writes:

Show 10 quoted lines

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

Show 10 quoted lines

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

Show 6 quoted lines

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