▼Libgit2:   Bindings for the libgit2 Git Library
►25 Object IDs
On this page:
git_  oid_  fromstr
git_  oid?
git-oid-string/  c
GIT_  OID_  HEXSZ
git_  oid_  cpy
25.1 Object ID Comparisons
git_  oid_  is_  zero
git_  oid_  equal
git_  oid_  streq
git_  oid_  cmp
git_  oid_  strcmp
git_  oid_  ncmp
25.2 Formatting Object IDs
git_  oid_  fmt
git_  oid_  nfmt
git_  oid_  pathfmt
25.3 Short Object IDs
git_  oid_  shorten_  new
git_  oid_  shorten?
git_  oid_  shorten_  add
8.16.0.1
  top  contents    up   

25 Object IDs🔗ℹ

 (require libgit2/include/oid) package: libgit2

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.1 Object ID Comparisons🔗ℹ

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 a b) → boolean?

  a : git_oid?
  b : git_oid?

procedure

(git_oid_streq a b) → 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 a b) → (or/c '< '= '>)

  a : git_oid?
  b : git_oid?

procedure

(git_oid_strcmp id str) → (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 a b n) → (or/c '= #f)

  a : git_oid?
  b : git_oid?
  n : (integer-in 0 GIT_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.2 Formatting Object IDs🔗ℹ

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 id n) → (and/c string? immutable?)

  id : git_oid?
  n : (integer-in 0 GIT_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 id 6)

"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.3 Short Object IDs🔗ℹ

procedure

(git_oid_shorten_new [min-length]) → git_oid_shorten?

  min-length : (integer-in 0 GIT_OID_HEXSZ) = 0

procedure

(git_oid_shorten? v) → boolean?

  v : any/c

procedure

(git_oid_shorten_add shortener oid-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 shortener str))))
> (sort (for/list ([str (in-set oid-strings)])
          (substring str 0 min-length))
        string<?)

'("00000000000"

  "821ac0038a6"

  "ad1b3cc099b"

  "ad1b3cc099c"

  "db775d20c16"

  "db785d20c16")

  top  contents    up