25 Object IDs

procedure
( git_oid_fromstr str)→git_oid?
str:git-oid-string/c

procedure
( git_oid? v)→boolean?
v:any/c

value
git-oid-string/c :flat-contract?

value
GIT_OID_HEXSZ :exact-positive-integer? =40

An object ID (or OID) value uniquely identifies any Git object, including commits, trees, blobs, tags. An object id is usually written as a hexidecimal string, but libgit2 uses a binary representation internally, which is recognized by the predicate git_oid? .

The function git_oid_fromstr parses a string into an object ID value, case-insensitively. The string form of an OID must be GIT_OID_HEXSZ characters long, which is enforced by the contract git-oid-string/c .

Examples:

> (git_oid_fromstr "555c0bd2b220e74e77a2d4ead659ffad79175dfa")

#<cpointer+offset>
;too short
> (git_oid_fromstr "bda0839")

git_oid_fromstr: contract violation;

given string is the wrong length

length: 7

expected: 40

given string: "bda0839"

in: the 1st argument of

(-> git-oid-string/c git_oid?)

contract from:

<pkgs>/libgit2/include/oid.rkt

blaming: top-level

(assuming the contract is correct)

at: <pkgs>/libgit2/include/oid.rkt:20:24
;not a hex string
> (git_oid_fromstr (make-string GIT_OID_HEXSZ #\z))

git_oid_fromstr:

error code: 'GIT_ERROR

error class: 'GIT_ERROR_NONE

procedure
( git_oid_cpy src)→git_oid?
src:git_oid?

Returns a new object ID value equivalent to src.

Examples:

> (define a
(git_oid_fromstr "555c0bd2b220e74e77a2d4ead659ffad79175dfa"))
> (git_oid_equal a(git_oid_cpy a))

#t

25.1Object ID Comparisons🔗 i

procedure
( git_oid_is_zero id)→boolean?
id:git_oid?

Recognizes object ID values equivalent to the hex string "0000000000000000000000000000000000000000".

Examples:

> (git_oid_is_zero (git_oid_fromstr (make-string GIT_OID_HEXSZ #0円)))

#t

> (git_oid_is_zero
(git_oid_fromstr "555c0bd2b220e74e77a2d4ead659ffad79175dfa"))

#f

procedure
( git_oid_equal ab)→boolean?
a:git_oid?
b:git_oid?

procedure
( git_oid_streq ab)→boolean?
a:git_oid?
b:git-oid-string/c

Equivalence test on object ID values, where git_oid_streq is like git_oid_equal , except that git_oid_streq takes its second argument in string form.

Examples:

> (define str
"7b70fdd9970245505229ef2127586350aaa8ad38")
> (git_oid_equal (git_oid_fromstr str)(git_oid_fromstr str))

#t
> (git_oid_streq (git_oid_fromstr str)str)

#t

> (git_oid_streq (git_oid_fromstr str)
"ad1b3cc099b788dcb066c56346fc8854e70e821c")

#f

procedure
( git_oid_cmp ab)→(or/c '<'='>)
a:git_oid?
b:git_oid?

procedure
( git_oid_strcmp idstr)→(or/c '<'='>)
id:git_oid?
str:git-oid-string/c

Like git_oid_equal and git_oid_streq , respectively, but tests the ordering of the OIDs.

procedure
( git_oid_ncmp abn)→(or/c '=#f)
a:git_oid?
b:git_oid?
n:(integer-in 0GIT_OID_HEXSZ )

Like git_oid_equal , but only considers the first n hexidecimal digits. Note that, unlike git_oid_cmp , git_oid_ncmp does not report the ordering of the OIDs.

25.2Formatting Object IDs🔗 i

procedure
( git_oid_fmt id)→(and/c string? immutable? )
id:git_oid?

Converts the object ID id to a hexidecimal string. Any letters in the resulting string will be in lower case.

Example:

> (git_oid_fmt (git_oid_fromstr "AD1B3CC099B788DCB066C56346FC8854E70E821C"))

"ad1b3cc099b788dcb066c56346fc8854e70e821c"

procedure
( git_oid_nfmt idn)→(and/c string? immutable? )
id:git_oid?
n:(integer-in 0GIT_OID_HEXSZ )

Like git_oid_fmt , but only converts the first n hexidecimal digits of id.

Examples:

> (define id
(git_oid_fromstr "AD1B3CC099B788DCB066C56346FC8854E70E821C"))
> (git_oid_nfmt id6)

"ad1b3c"

procedure
( git_oid_pathfmt id)→path?
id:git_oid?

Like git_oid_fmt , but converts id to a relative loose-object path (for the current platform).

The first two hexidecimal digits of id are used as a directory name, and the remaining 38 digits are treated as a path within that directory.

Example:

> (git_oid_pathfmt (git_oid_fromstr "40dc88bde003670bae6df1f0cffb1ffb5d93dee4"))

#<path:40/dc88bde003670bae6df1f0cffb1ffb5d93dee4>

25.3Short Object IDs🔗 i

procedure
( git_oid_shorten_new [min-length])→git_oid_shorten?
min-length:(integer-in 0GIT_OID_HEXSZ )=0

procedure
( git_oid_shorten? v)→boolean?
v:any/c

procedure
( git_oid_shorten_add shorteneroid-str)→natural-number/c
shortener:git_oid_shorten?
oid-str:git-oid-string/c

An OID shortener consumes a set of object IDs in string form and computes the minimum string length needed to distinguish all of them.

Calling git_oid_shorten_add with a hex string OID oid-str returns the minimum number of digits needed to distinguish all of the strings that have been supplied to git_oid_shorten_add so far with the same shortener argument. If the OID shortener is created with a non-zero min-length, git_oid_shorten_add will never return a length less than min-length.

Calling git_oid_shorten_add more than once with the same shortener and equivalent oid-str arguments will produce unhelpful results.

Note that, “for performance reasons, [libgit2 imposes] a hard limit of how many OIDs can be added to a single set (around 32000, assuming a mostly randomized distribution), which should be enough for any kind of program, and keeps the algorithm fast and memory-efficient.”

Examples:

> (define oid-strings
(set "ad1b3cc099b788dcb066c56346fc8854e70e821c"
"db775d20c1655c72a95dd40d1a75c0ad4f243461"
"821ac0038a6b196a93c48182bdde5ac42c6f5b6e"
"0000000000000000000000000000000000000000"
"db785d20c1655c72a95dd40d1a75c0ad4f243461"
"ad1b3cc099c788dcb066c56346fc8854e70e821c"))

> (define min-length
(let ([shortener(git_oid_shorten_new )])
(for/last ([str(in-set oid-strings)])
(git_oid_shorten_add shortenerstr))))

> (sort (for/list ([str(in-set oid-strings)])
(substring str0min-length))
string<? )

'("00000000000"

"821ac0038a6"

"ad1b3cc099b"

"ad1b3cc099c"

"db775d20c16"

"db785d20c16")

top ← prev up next →