source: project/wiki/eggref/4/git @ 26791

Last change on this file since 26791 was 26791, checked in by evhan, 8 years ago

git: fix incorrect note about tree-diffing #f

File size: 27.4 KB
Line 
1[[tags: egg]]
2
3== git
4
5[[toc:]]
6
7=== Description
8
9Bindings to the [[http://libgit2.github.com|libgit2]] library.
10
11This library requires libgit2 0.16.0 and Chicken 4.7 or newer.
12
13The source for this egg is available at [[http://github.com/evhan/chicken-git]].
14
15=== Documentation
16
17{{git}} provides an interface for reading & manipulating git repositories.
18The library is split into two modules, {{git}} and {{git-lolevel}}:
19
20* {{git-lolevel}} is essentially just the libgit2 API, thinly wrapped. Most of
21  the function signatures remain the same, with a few exceptions:
22
23** Structures & pointers that would go on the stack are allocated
24automatically.
25
26** Return values are checked where appropriate, signaling an exception of type
27{{git}} when negative.
28
29** Pointer arrays are converted to rest arguments.
30
31* {{git}} is a higher-level interface around {{git-lolevel}}, providing
32  record types for each libgit2 structure.
33
34The following documentation applies to the {{git}} module.
35
36=== Usage
37
38  (use git) ; or...
39  (use git-lolevel)
40
41It's not recommended to mix the two without prefixing one or the other's
42imports, as the two libraries share many identifiers.
43
44=== API
45
46==== Repository
47
48<record>repository</record>
49<procedure>(repository? obj) => boolean</procedure>
50
51A {{repository}} corresponds to an on-disk Git repository.
52
53Many objects are invalidated when the repository to which they belong is GC'd.
54As such, a handle to a repository should be kept for as long as its objects are
55in use.
56
57<procedure>(create-repository [path] [bare]) => repository</procedure>
58
59Creates & returns a new repository at the given {{path}}, or the value of
60{{current-directory}} if no path is given. If {{bare}} is given and not {{#f}},
61the repository will be created without a working directory. An error is
62signaled if the path is invalid or the repository cannot be created.
63
64<procedure>(repository-open [path]) => repository</procedure>
65
66Opens the Git repository indicated by {{path}}, or the value of
67{{current-directory}} if no {{path}} is given. {{path}} may point to a bare
68repository, a working directory containing a ".git" directory, or a ".git"
69directory directly.
70
71<procedure>(repository-path repository [type]) => string</procedure>
72
73Returns the absolute path to the given {{repository}}. A {{type}} symbol may be
74given in order to retrieve alternate paths for the repository, and should be
75one of {{path}} (the default), {{index}}, {{odb}} or {{workdir}}.
76
77<procedure>(repository-ref repository ref) => object</procedure>
78
79Looks up a Git object in the given {{repository}}. {{ref}} may be a SHA1 string,
80{{oid}}, {{reference}}, {{blob*}}, {{commit}}, {{tag}} or {{tree}}. The returned
81object will be of type {{blob*}}, {{commit}}, {{tag}} or {{tree}}, or {{#f}} if
82no object matching the given {{ref}} is found.
83
84<procedure>(repository-empty? repository) => boolean</procedure>
85<procedure>(repository-bare? repositoy) => boolean</procedure>
86
87Returns a boolean indicating whether the given {{repository}} is empty
88(contains no commits) or bare (an exposed git directory without a working
89directory).
90
91<procedure>(pack-references repository) => void</procedure>
92
93Writes all loose references in the given {{repository}} into its "pack-refs"
94file and removes them from the on-disk repository. Calling this function will
95invalidate any existing {{reference}} objects belonging to the repository.
96
97==== OID
98
99<record>oid</record>
100<procedure>(oid? obj) => boolean</procedure>
101
102An {{oid}} is a unique reference to a Git object, corresponding to a
10340-character SHA1 object name.
104
105<procedure>(string->oid string) => oid</procedure>
106
107Creates an {{oid}} from the given string, which should be a 40-character SHA1
108hash. An error is signaled if the string is not a valid hash.
109
110<procedure>(oid->string oid [length]) => string</procedure>
111
112Returns the string representation of the given {{oid}}. The optional integer
113{{length}} specifies the length of the returned string, up to 40 characters.
114
115<procedure>(oid->path oid) => string</procedure>
116
117Returns the string representation of the given {{oid}} in the form "xx/...",
118where "xx" is the first two characters of the SHA1 and "..." is the remainder.
119
120==== Reference
121
122<record>reference</record>
123<procedure>(reference? obj) => boolean</procedure>
124
125A {{reference}} is a direct or indirect pointer to a Git commit object. A
126repository's {{"HEAD"}} is a common example: it is a symbolic reference,
127referring to the immediate reference {{"refs/heads/master"}}, which in turn
128points at a {{commit}}.
129
130<procedure>(reference repository ref) => reference</procedure>
131
132Returns the {{reference}} specified by the given string {{ref}} from the
133{{repository}}. {{ref}} must be a string referring to a valid reference, such
134as {{"HEAD"}}, {{"ref/heads/master"}}, or {{"refs/tags/v0.1.0"}}. An error is
135signalled if the reference doesn't exists.
136
137<procedure>(references repository) => list</procedure>
138
139Returns a list of all references in the given {{repository}}.
140
141<procedure>(reference-id reference) => oid</procedure>
142
143Returns the {{oid}} of the object referred to by the given {{reference}}.
144
145<procedure>(reference-owner reference) => repository</procedure>
146
147Returns the {{repository}} to which the given {{reference}} belongs.
148
149<procedure>(reference-resolve reference) => reference</procedure>
150
151Dereferences the given (possibly symbolic) {{reference}}, returning a new
152non-symbolic {{reference}} pointing directly to a {{commit}}.
153
154<procedure>(reference-target reference) => string</procedure>
155
156Returns the name of the reference referred to by the given symbolic
157{{reference}}. It is an error if the given {{reference}} is not symbolic.
158
159<procedure>(reference-rename reference name) => void</procedure>
160<procedure>(reference-target-set reference target) => void</procedure>
161
162{{reference-rename}} changes the name of the given {{reference}} to the string
163{{name}}.
164
165{{reference-target-set}} updates a {{reference}} to refer to the given
166{{target}}. If {{reference}} is an immediate reference (referring to an object
167ID), {{target}} must be an {{oid}}, {{commit}}, or SHA1 string. If
168{{reference}} is symbolic, {{target}} must be a {{reference}} or reference
169name. It is an error to assign a symbolic reference an OID target and
170vice-versa.
171
172On success, the on-disk repository is updated immediately.
173
174<procedure>(create-reference repository #!key name target [symbolic] [force]) => reference</procedure>
175
176Creates & returns a new reference in the given {{repository}} for the specified
177{{name}} and {{target}}. If {{symbolic}} is given and not {{#f}}, the created
178reference will be so, and {{target}} must be a reference name or {{reference}}.
179Otherwise, {{target}} must be a SHA1 string, {{oid}}, {{commit}} or
180{{reference}} to a {{commit}}. If a reference of the given {{name}} exists and
181{{force}} is not given or {{#f}}, an error is signalled. Otherwise, creation
182is forced and the old reference will be overwritten.
183
184On success, the on-disk repository is updated immediately.
185
186==== Generic
187
188<procedure>(object-id object) => oid</procedure>
189
190Returns the {{oid}} referring to the given object, which must be a {{commit}},
191{{tree}}, {{tag}} or {{blob*}}.
192
193<procedure>(object-sha object [length]) => string</procedure>
194
195Returns the SHA1 identifier corresponding to the given object, which may be a
196{{commit}}, {{tree}}, {{tag}} {{blob*}}, {{reference}}, {{oid}} or {{string}}.
197
198<procedure>(object-type object) => symbol</procedure>
199
200Returns a symbol specifying the type of the given object, which must be one of
201{{commit}}, {{tree}}, {{tag}} or {{blob*}}. {{#f}} is returned if the type
202cannot be determined.
203
204==== Blob*
205
206<record>blob*</record>
207<procedure>(blob*? obj) => boolean</procedure>
208
209A {{blob*}} corresponds to Git's Blob object type, renamed in order to avoid
210name clashes with Chicken's built-in {{blob}} type. It represents a file.
211
212<procedure>(blob* repository ref) => blob*</procedure>
213
214Returns the {{blob*}} specified by the given {{ref}} from the repository.
215{{ref}} may be a SHA1 string, {{oid}}, or {{blob*}}. An error is signaled if
216no such {{blob*}} exists.
217
218<procedure>(blob*-content blob*) => blob</procedure>
219
220Returns a {{blob}} (of the Chicken built-in type) with the contents of the given
221{{blob*}} (of the Git object type).
222
223<procedure>(blob*-size blob*) => int</procedure>
224
225Returns the size in bytes of the given {{blob*}}.
226
227==== Commit
228
229<record>commit</record>
230<procedure>(commit? obj) => boolean</procedure>
231
232A {{commit}} corresponds to Git's commit object type.
233
234<procedure>(commit repository ref) => commit</procedure>
235
236Returns the {{commit}} specified by the given {{ref}} from the repository.
237{{ref}} may be a SHA1 string, {{oid}}, {{reference}} or {{commit}}. An error
238is signaled if no such {{commit}} exists.
239
240<procedure>(commits-fold kons knil repository #!key [initial] [hide] [sort]) => list</procedure>
241
242Folds over the given {{repository}}'s commits. If an {{initial}} {{commit}} or
243SHA1 is given, only commits that are ancestors of that revision will be
244returned. If a list of revisions to {{hide}} is given, they and their ancestors
245will be ignored. If a {{sort}} is specified, commits will be collected in the
246given order; this sort order must be one of the symbols {{none}}, {{topo}},
247{{time}} or {{rev}}.
248
249<procedure>(commits repository #!rest args) => list</procedure>
250
251Returns a list of the {{commit}}s in the given {{repository}}. {{args}} follows
252the {{#!key}} arguments specification for {{commits-fold}}.
253
254<procedure>(commit-id commit) => oid</procedure>
255
256Returns the {{oid}} for the given {{commit}}.
257
258<procedure>(commit-time commit) => int</procedure>
259<procedure>(commit-time-offset commit) => int</procedure>
260
261{{commit-time}} and {{commit-time-offset}} return the timestamp of the given
262{{commit}} and its UTC offset in minutes, respectively.
263
264<procedure>(commit-message commit) => string</procedure>
265
266Returns the full commit message of the given {{commit}}.
267
268<procedure>(commit-tree commit) => tree</procedure>
269<procedure>(commit-tree-id commit) => oid</procedure>
270
271Return the {{tree}} associated with the given {{commit}} and its {{oid}},
272respectively.
273
274<procedure>(commit-author commit) => signature</procedure>
275<procedure>(commit-committer commit) => signature</procedure>
276
277{{commit-author}} and {{commit-committer}} return the given {{commit}}'s
278respective {{signature}}s.
279
280<procedure>(commit-parentcount commit) => int</procedure>
281<procedure>(commit-parent commit [n]) => commit</procedure>
282
283{{commit-parentcount}} returns the number of parents for a given {{commit}}.
284
285{{commit-parent}} returns the {{n}}th parent of the given {{commit}}, or the
286first if no {{n}} is given. If the {{commit}} has no parent, {{#f}} is
287returned.
288
289<procedure>(create-commit repository #!key message tree [parents] author [committer] [reference]) => commit</procedure>
290
291Creates & returns a new commit in the given {{repository}}. The string
292{{message}} will be used as the commit's message and {{tree}} will be the file
293tree of the commit. {{parents}} should be be a (possibly empty) list of commits
294to be used as this commit's parents. {{author}} and {{committer}} should be
295signatures; if {{committer}} is not given, {{author}} will be used for both.
296{{reference}}, if given and not {{#f}}, should be the {{reference}} that will
297be updated to point to the newly-created commit.
298
299Note that if no {{reference}} is given, the commit will be created in Git's
300database but will not be reflected in any of the repository's branches. To
301update the the working branch with the new commit, for example, use "HEAD".
302
303On success, the on-disk repository is updated immediately.
304
305==== Tag
306
307<record>tag</record>
308<procedure>(tag? obj) => boolean</procedure>
309
310A {{tag}} corresponds to Git's Tag object type, which is a way to mark a
311specific object as special in some way.
312
313<procedure>(tag repository ref) => tag</procedure>
314
315Creates & returns the {{tag}} specified by the given {{ref}} from the
316repository. {{ref}} may be a SHA1 string, {{oid}}, or {{tag}}. An error is
317signaled if no such {{tag}} exists.
318
319<procedure>(tags repository) => list</procedure>
320
321Returns a list of all tags in the given {{repository}}.
322
323<procedure>(tag-id tag) => oid</procedure>
324
325Returns the {{oid}} for the given {{tag}}.
326
327<procedure>(tag-type tag) => symbol</procedure>
328
329Returns the object type symbol of the target of the given {{tag}}, which will
330be one of {{commit}}, {{tree}}, {{blob}}, or {{tag}}.
331
332<procedure>(tag-name tag) => string</procedure>
333<procedure>(tag-message tag) => string</procedure>
334
335Return the name or message of the given {{tag}}.
336
337<procedure>(tag-tagger tag) => signature</procedure>
338
339Returns the {{signature}} of the {{tag}}'s creator.
340
341<procedure>(tag-target tag) => object</procedure>
342
343Returns the object referred to by {{tag}}, which will be of type {{commit}},
344{{tree}}, {{blob}} or {{tag}}.
345
346<procedure>(tag-delete tag) => void</procedure>
347
348Destroys the given {{tag}}.
349
350On success, the on-disk repository is updated immediately.
351
352<procedure>(create-tag repository #!key target name message tagger [force]) => tag</procedure>
353
354Creates & returns a new tag in the given {{repository}} for the specified
355{{name}}, {{message}} and {{target}}. {{name}} and {{message}} must be strings,
356{{tagger}} must be a {{signature}},and {{target}} must be a {{commit}},
357{{tree}} or {{blob*}}. If a tag of the given {{name}} exists and {{force}} is
358not given or {{#f}}, an error is signalled.  Otherwise, creation is forced and
359the old tag will be overwritten.
360
361On success, the on-disk repository is updated immediately.
362
363==== Tree
364
365<record>tree</record>
366<procedure>(tree? obj) => boolean</procedure>
367
368A {{tree}} corresponds to Git's Tree object type, which represents a directory
369tree.
370
371<procedure>(tree repository ref) => tree</procedure>
372
373Returns the {{tree}} specified by the given {{ref}} from the repository. {{ref}}
374may be a SHA1 string, {{oid}}, or {{tree}}. An error is signaled if no such
375{{tree}} exists.
376
377<procedure>(tree-id tree) => oid</procedure>
378
379Returns the {{oid}} for the given {{tree}}.
380
381<procedure>(tree-entrycount tree) => int</procedure>
382
383Returns the number of entries in the given {{tree}}. This count does not
384include entries of contained directories.
385
386<procedure>(tree-ref tree key) => tree-entry</procedure>
387
388Returns a {{tree-entry}} object for the given {{key}} from the tree, or
389{{#f}} if no such tree entry is found. {{key}} may be a zero-based integer
390index or a pathname string.
391
392<procedure>(tree->list tree [repository]) => list</procedure>
393
394Returns a list of {{tree-entry}} objects for the given {{tree}}. If a
395{{repository}} is given, this function will recurse into it, returning a nested
396list of entries spanning the full directory tree.
397
398<procedure>(create-tree repository index) => tree</procedure>
399
400Creates and returns a {{tree}} object from the state of the given {{index}}.
401
402==== Tree Entry
403
404<record>tree-entry</record>
405<procedure>(tree-entry? obj) => boolean</procedure>
406
407A {{tree-entry}} represents a single node in a {{tree}} object.
408
409<procedure>(tree-entry-id tree-entry) => oid</procedure>
410
411Returns the {{oid}} of the given {{tree-entry}}.
412
413<procedure>(tree-entry-name tree-entry) => string</procedure>
414
415Returns the name of the given {{tree-entry}}.
416
417<procedure>(tree-entry-attributes tree-entry) => int</procedure>
418
419Returns the Unix file attributes of the given {{tree-entry}}.
420
421<procedure>(tree-entry-type tree-entry) => symbol</procedure>
422
423Returns the object type symbol, either {{tree}} or {{blob}}, of the given
424{{tree-entry}}.
425
426<procedure>(tree-entry->object repository tree-entry) => object</procedure>
427
428Returns an object of type {{tree}} or {{blob*}} from the given {{tree-entry}}
429and {{repository}}, which must be the owner of the {{tree-entry}}.
430
431==== Tree Builder
432
433<record>tree-builder</record>
434<procedure>(tree-builder? obj) => boolean</procedure>
435
436A tree builder provides a way to construct {{tree}} objects in memory and write
437them to a repository, without using an index as an intermediary.
438
439<procedure>(make-tree-builder [tree]) => tree-builder</procedure>
440
441Creates a new {{tree-builder}}. If a {{tree}} is given, it is used as the
442constructed tree's initial state. Otherwise, it must be populated manually
443using {{tree-builder-insert}}.
444
445<procedure>(tree-builder-insert tree-builder object name attributes) => tree-entry</procedure>
446
447Inserts {{object}} into the {{tree-builder}}'s tree under the given filename
448{{name}}. The inserted object must be a {{tree}} or {{blob*}}, and will have
449the given {{attributes}} (an integer file mode).
450
451<procedure>(tree-builder-ref tree-builder path) => tree-entry</procedure>
452
453Returns the {{tree-entry}} from the given {{tree-builder}} at {{path}}, which
454should be a filename string. If the requested file doesn't exist, {{#f}} is
455returned.
456
457<procedure>(tree-builder-remove tree-builder path) => void</procedure>
458
459Removes the object at the given {{path}} from the {{tree-builder}}'s tree.
460
461<procedure>(tree-builder-write repo tree-builder) => tree</procedure>
462
463Writes the {{tree-builder}}'s tree to the given {{repository}}, modifying the
464on-disk repository on success. The resulting {{tree}} is returned.
465
466==== Tree Diff
467
468<record>tree-diff</record>
469<procedure>(tree-diff? obj) => boolean</procedure>
470
471A {{tree-diff}} is the difference of a single file across two Git {{tree}}s.
472Each tree-diff has a path, status, and a pair of {{oid}}s and Unix file
473attributes (for the older & newer file, respectively).
474
475<procedure>(tree-diff repository tree1 tree2) => list</procedure>
476
477Compares two {{tree}}s in the given {{repository}}, returning a list of
478{{tree-diff}} objects for every difference between them.
479
480<procedure>(tree-diff-status tree-diff) => symbol</procedure>
481
482Returns a symbol representing the diff status of a {{tree-diff}}, which will be
483one of {{added}}, {{deleted}}, or {{modified}}.
484
485<procedure>(tree-diff-path tree-diff)</procedure>
486
487Returns the path of the given {{tree-diff}}, relative to the repository's
488root.
489
490<procedure>(tree-diff-old-id tree-diff) => oid</procedure>
491<procedure>(tree-diff-new-id tree-diff) => oid</procedure>
492
493Returns the older or newer {{oid}} of the given {{tree-diff}}.
494
495<procedure>(tree-diff-old-attr tree-diff) => int</procedure>
496<procedure>(tree-diff-new-attr tree-diff) => int</procedure>
497
498Returns the older or newer Unix file attributes of the given {{tree-diff}}.
499
500==== Status
501
502<procedure>(file-status repository path) => symbol</procedure>
503
504Returns the status of the file specified by {{path}} in the given
505{{repository}}.
506
507This status will be one of the following symbols:
508
509    current
510    index/new
511    index/modified
512    index/deleted
513    worktree/new
514    worktree/modified
515    worktree/deleted
516    ignored
517
518Currently, if a file is of two statuses (for example, partially-staged, so it
519is both {{index/modified}} and {{worktree/modified}}) this function will return
520the empty list.
521
522<procedure>(file-ignored? repository path) => boolean</procedure>
523
524Returns a boolean indicating whether the given {{path}} in {{repository}} is
525ignored by Git or not.
526
527==== Index
528
529<record>index</record>
530<procedure>(index? obj) => boolean</procedure>
531
532An {{index}} represents the on-disk state of Git's working tree. Changes made
533to a given {{index}} exist only in memory until written to disk using
534{{index-write}}.
535
536<procedure>(index-open repo-or-path) => index</procedure>
537
538It {{repo-or-path}} is a {{repository}}, returns the repository's index.  If it
539is a string, creates and returns the index at the given path, signaling an
540error if such an index doesn't exist. It is not possible to open the index of a
541bare repository, and doing so will result in an exception.
542
543<procedure>(index-entrycount index) => int</procedure>
544<procedure>(index-entrycount-unmerged index) => int</procedure>
545
546Returns the total number of index entries and unmerged index entries of the
547given {{index}}, respectively. This is essentially a count of all files tracked
548by Git in a given repository.
549
550<procedure>(index-read index) => void</procedure>
551
552Updates the given {{index}} to reflect the current state of the on-disk
553repository.
554
555<procedure>(index-write index) => void</procedure>
556
557Writes the state of the given {{index}} from memory onto disk, modifying the
558repository on success.
559
560<procedure>(index-clear index) => void</procedure>
561
562Removes all enries from a given {{index}}.
563
564<procedure>(index-add index path [stage]) => void</procedure>
565
566Adds a given {{path}}, which must refer to a file relative to the index's
567repository, to the {{index}}. If an integer {{stage}} is given, it will be used
568as the staging number for the changes.
569
570<procedure>(index-remove index ref) => void</procedure>
571
572Removes an entry from the given {{index}}. {{ref}} may be a file path string or
573an zero-based integer index. If no entry is removed, {{#f}} is returned.
574
575<procedure>(index-find index path) => int</procedure>
576
577Returns the zero-based integer index of the file specified by {{path}} in the
578given {{index}}, signaling an error if it doesn't exist.
579
580<procedure>(index-ref index key [type]) => index-entry</procedure>
581
582Returns the {{index-entry}} from the {{index}} for the given {{key}}, which may
583be an zero-based integer index or a pathname string, or {{#f}} if no such entry
584exists. If a type symbol is given, either {{merged}} (the default behavior) or
585{{unmerged}}, the search will be limited to such entries.
586
587<procedure>(index->list index [type]) => list</procedure>
588
589Returns a list of all {{index-entry}} objects in the given {{index}}. If a type
590symbol is given, either {{merged}} (the default behavior) or {{unmerged}}, the
591returned list will be limited to such entries.
592
593==== Index Entry
594
595<record>index-entry</record>
596<procedure>(index-entry? obj) => boolean</procedure>
597
598An {{index-entry}} represents a tracked file in Git's working directory,
599belonging to an {{index}}.
600
601<procedure>(index-entry-id index-entry) => oid</procedure>
602
603Returns the {{oid}} referring to the given {{index-entry}}.
604
605<procedure>(index-entry-path index-entry) => string</procedure>
606
607Returns the file path of the given {{index-entry}} relative to the owning
608repository's working directory.
609
610<procedure>(index-entry-ctime index-entry) => int</procedure>
611<procedure>(index-entry-mtime index-entry) => int</procedure>
612<procedure>(index-entry-dev index-entry) => int</procedure>
613<procedure>(index-entry-ino index-entry) => int</procedure>
614<procedure>(index-entry-size index-entry) => int</procedure>
615<procedure>(index-entry-stage index-entry) => int</procedure>
616<procedure>(index-entry-uid index-entry) => int</procedure>
617<procedure>(index-entry-gid index-entry) => int</procedure>
618<procedure>(index-entry-mode index-entry) => int</procedure>
619<procedure>(index-entry-flags index-entry) => int</procedure>
620<procedure>(index-entry-extended index-entry) => int</procedure>
621
622These methods return the file attributes for the given {{index-entry}} as it
623exists in its in-memory {{index}}.
624
625==== ODB
626
627<record>odb</record>
628<procedure>(odb? obj) => boolean</procedure>
629
630An {{odb}} offers a direct interface to Git's internal object database.
631
632<procedure>(odb-open repo-or-path) => odb</procedure>
633
634It {{repo-or-path}} is a {{repository}}, returns the repository's object
635database. If it is a string, creates and returns the object database at the
636given path, signaling an error if no such database exists.
637
638<procedure>(odb-has-object? odb ref) => boolean</procedure>
639
640Determines if the given {{odb}} contains the given object {{ref}}, which should
641be a SHA1 string, {{oid}} or Git object of type {{commit}}, {{blob*}}, {{tree}}
642or {{tag}}.
643
644<procedure>(odb-read odb ref) => odb-object</procedure>
645
646Reads the given object {{ref}} from the database, signaling an error if it
647doesn't exist. {{ref}} should be a SHA1 string, {{oid}} or Git object of type
648{{commit}}, {{blob*}}, {{tree}} or {{tag}}.
649
650<procedure>(odb-write odb data [type]) => oid</procedure>
651
652Writes a given data {{blob}} to the {{odb}}, returning an {{oid}} referring to
653the newly-created object. The type of the stored data can be specified by an
654optional {{type}} symbol, which defaults to {{blob}}.
655
656<procedure>(odb-hash odb data [type]) => oid</procedure>
657
658Returns an {{oid}} reference for the given data {{blob}} as though it had been
659stored to the given {{odb}} but without writing it to disk. The type of the
660hashed data can be specified by an optional {{type}} symbol, which defaults to
661{{blob}}.
662
663==== ODB Object
664
665<record>odb-object</record>
666<procedure>(odb-object? obj) => boolean</procedure>
667
668An {{odb-object}} is a reference to a blob of data in a Git object database.
669
670<procedure>(odb-object-id odb-object) => oid</procedure>
671
672Returns the {{oid}} for the given {{odb-object}}.
673
674<procedure>(odb-object-size odb-object) => int</procedure>
675
676Returns the size of the {{odb-object}}'s data in bytes.
677
678<procedure>(odb-object-type odb-object) => symbol</procedure>
679
680Returns the object type symbol of the given {{odb-object}}.
681
682<procedure>(odb-object-data odb-object) => blob</procedure>
683
684Returns a blob consisting of the {{odb-object}}'s data.
685
686==== Signature
687
688<record>signature</record>
689<procedure>(signature? obj) => boolean</procedure>
690
691A signature is a record of the name, email, time and UTC offset of a given Git
692object.
693
694<procedure>(make-signature name email [time [offset]]) => signature</procedure>
695
696Returns a new {{signature}} for the given name and email strings. If a
697timestamp {{time}} and integer {{offset}} are given, they will be used as the
698signature time; otherwise, the current time will be used.
699
700Unlike the {{create-*}} functions, no representation of this signature is
701created in the repository; it exists only in memory until associated with a
702{{commit}} or {{tag}}.
703
704<procedure>(signature-name signature) => string</procedure>
705<procedure>(signature-email signature) => string</procedure>
706
707{{signature-name}} and {{signature-email}} return strings for the
708given {{signature}}'s respective fields.
709
710<procedure>(signature-time signature) => int</procedure>
711<procedure>(signature-time-offset signature) => int</procedure>
712
713{{signature-time}} and {{signature-time-offset}} return the timestamp of the
714given {{signature}} and its UTC offset in minutes, respectively.
715
716==== Config
717
718<record>config</record>
719<procedure>(config? obj) => boolean</procedure>
720
721A {{config}} represents a Git configuration file, associated with either a
722repository, the current user, or the system-wide Git installation.
723
724<procedure>(config-path [type]) => string</procedure>
725
726Returns the path to a Git configuration file. {{type}} may be a symbol, either
727{{user}} or {{system}}, to request the path to the configuration for either the
728current user or the system-wide Git installation, respectively. {{type}}
729defaults to {{user}}. An error is signalled if no configuration file is found
730at the requested location.
731
732<procedure>(config-open [source]) => config</procedure>
733
734Reads the Git configuration file indicated by {{source}}, which may be a
735{{repository}}, path, or symbol as expected by {{config-path}}. An
736error is signalled if no configuration file is found at the requested location.
737
738<procedure>(config-get config name [type]) => object</procedure>
739
740Returns the value of the property {{name}} in the given {{config}} object. The
741value is returned as a string, unless an alternative return type is specified
742by the given symbol {{type}}, which should be {{string}}, {{symbol}}, or
743{{number}}. An error is signaled if the requested property doesn't exist, or if
744it cannot be converted to the specified return type.
745
746<procedure>(config-set config name value) => object</procedure>
747
748Sets the value of the property {{name}} in the given {{config}} object to the
749given {{value}}.
750
751On success, the new value is written immediately to disk.
752
753<procedure>(config-unset config name) => void</procedure>
754
755Deletes the property {{name}} from the given {{config}} object.
756
757On success, the change is written immediately to disk.
758
759=== History
760
761* 0.0.14 - libgit2 0.17.0 compatibility
762* 0.0.13 - libgit2 0.16.0
763
764=== Author
765
766Evan Hanson
767
768=== License
769
770Copyright (c) 2012, Evan Hanson, 3-Clause BSD License
Note: See TracBrowser for help on using the repository browser.