1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-10-31 06:17:56 +01:00
git/Documentation/technical/api-oid-array.txt
Ævar Arnfjörð Bjarmason 5cc044e025 get_short_oid: sort ambiguous objects by type, then SHA-1
Change the output emitted when an ambiguous object is encountered so
that we show tags first, then commits, followed by trees, and finally
blobs. Within each type we show objects in hashcmp() order. Before
this change the objects were only ordered by hashcmp().

The reason for doing this is that the output looks better as a result,
e.g. the v2.17.0 tag before this change on "git show e8f2" would
display:

    hint: The candidates are:
    hint:   e8f2093055 tree
    hint:   e8f21caf94 commit 2013-06-24 - bash prompt: print unique detached HEAD abbreviated object name
    hint:   e8f21d02f7 blob
    hint:   e8f21d577c blob
    hint:   e8f25a3a50 tree
    hint:   e8f26250fa commit 2017-02-03 - Merge pull request #996 from jeffhostetler/jeffhostetler/register_rename_src
    hint:   e8f2650052 tag v2.17.0
    hint:   e8f2867228 blob
    hint:   e8f28d537c tree
    hint:   e8f2a35526 blob
    hint:   e8f2bc0c06 commit 2015-05-10 - Documentation: note behavior for multiple remote.url entries
    hint:   e8f2cf6ec0 tree

Now we'll instead show:

    hint:   e8f2650052 tag v2.17.0
    hint:   e8f21caf94 commit 2013-06-24 - bash prompt: print unique detached HEAD abbreviated object name
    hint:   e8f26250fa commit 2017-02-03 - Merge pull request #996 from jeffhostetler/jeffhostetler/register_rename_src
    hint:   e8f2bc0c06 commit 2015-05-10 - Documentation: note behavior for multiple remote.url entries
    hint:   e8f2093055 tree
    hint:   e8f25a3a50 tree
    hint:   e8f28d537c tree
    hint:   e8f2cf6ec0 tree
    hint:   e8f21d02f7 blob
    hint:   e8f21d577c blob
    hint:   e8f2867228 blob
    hint:   e8f2a35526 blob

Since we show the commit data in the output that's nicely aligned once
we sort by object type. The decision to show tags before commits is
pretty arbitrary. I don't want to order by object_type since there
tags come last after blobs, which doesn't make sense if we want to
show the most important things first.

I could display them after commits, but it's much less likely that
we'll display a tag, so if there is one it makes sense to show it
prominently at the top.

A note on the implementation: Derrick rightly pointed out[1] that
we're bending over backwards here in get_short_oid() to first
de-duplicate the list, and then emit it, but could simply do it in one
step.

The reason for that is that oid_array_for_each_unique() doesn't
actually require that the array be sorted by oid_array_sort(), it just
needs to be sorted in some order that guarantees that all objects with
the same ID are adjacent to one another, which (barring a hash
collision, which'll be someone else's problem) the sort_ambiguous()
function does.

I agree that would be simpler for this code, and had forgotten why I
initially wrote it like this[2]. But on further reflection I think
it's better to do more work here just so we're not underhandedly using
the oid-array API where we lie about the list being sorted. That would
break any subsequent use of oid_array_lookup() in subtle ways.

I could get around that by hacking the API itself to support this
use-case and documenting it, which I did as a WIP patch in [3], but I
think it's too much code smell just for this one call site. It's
simpler for the API to just introduce a oid_array_for_each() function
to eagerly spew out the list without sorting or de-duplication, and
then do the de-duplication and sorting in two passes.

1. https://public-inbox.org/git/20180501130318.58251-1-dstolee@microsoft.com/
2. https://public-inbox.org/git/876047ze9v.fsf@evledraar.gmail.com/
3. https://public-inbox.org/git/874ljrzctc.fsf@evledraar.gmail.com/

Helped-by: Derrick Stolee <dstolee@microsoft.com>
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-11 14:43:23 +09:00

85 lines
2.6 KiB
Text

oid-array API
==============
The oid-array API provides storage and manipulation of sets of object
identifiers. The emphasis is on storage and processing efficiency,
making them suitable for large lists. Note that the ordering of items is
not preserved over some operations.
Data Structures
---------------
`struct oid_array`::
A single array of object IDs. This should be initialized by
assignment from `OID_ARRAY_INIT`. The `oid` member contains
the actual data. The `nr` member contains the number of items in
the set. The `alloc` and `sorted` members are used internally,
and should not be needed by API callers.
Functions
---------
`oid_array_append`::
Add an item to the set. The object ID will be placed at the end of
the array (but note that some operations below may lose this
ordering).
`oid_array_lookup`::
Perform a binary search of the array for a specific object ID.
If found, returns the offset (in number of elements) of the
object ID. If not found, returns a negative integer. If the array
is not sorted, this function has the side effect of sorting it.
`oid_array_clear`::
Free all memory associated with the array and return it to the
initial, empty state.
`oid_array_for_each`::
Iterate over each element of the list, executing the callback
function for each one. Does not sort the list, so any custom
hash order is retained. If the callback returns a non-zero
value, the iteration ends immediately and the callback's
return is propagated; otherwise, 0 is returned.
`oid_array_for_each_unique`::
Iterate over each unique element of the list in sorted order,
but otherwise behave like `oid_array_for_each`. If the array
is not sorted, this function has the side effect of sorting
it.
Examples
--------
-----------------------------------------
int print_callback(const struct object_id *oid,
void *data)
{
printf("%s\n", oid_to_hex(oid));
return 0; /* always continue */
}
void some_func(void)
{
struct sha1_array hashes = OID_ARRAY_INIT;
struct object_id oid;
/* Read objects into our set */
while (read_object_from_stdin(oid.hash))
oid_array_append(&hashes, &oid);
/* Check if some objects are in our set */
while (read_object_from_stdin(oid.hash)) {
if (oid_array_lookup(&hashes, &oid) >= 0)
printf("it's in there!\n");
/*
* Print the unique set of objects. We could also have
* avoided adding duplicate objects in the first place,
* but we would end up re-sorting the array repeatedly.
* Instead, this will sort once and then skip duplicates
* in linear time.
*/
oid_array_for_each_unique(&hashes, print_callback, NULL);
}
-----------------------------------------