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

Last change on this file since 25885 was 25885, checked in by evhan, 9 years ago

git: update for libgit2 v0.16.0

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