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

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

git: docs for new 0.17.0 bindings & diff api changes

File size: 30.9 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==== Branch
187
188<procedure>(create-branch repository name target [force]) => reference</procedure>
189
190Creates a new branch in the given {{repository}} of the given {{name}} and
191{{target}} and returns a {{reference}} to the new branch. {{target}} must be a
192{{commit}} or {{tag}} belonging to the repository. If a branch of the given
193{{name}} exists and {{force}} is not given or {{#f}}, an error is signalled.
194Otherwise, creation is forced and the old branch is be overwritten.
195
196On success, the on-disk repository is updated immediately.
197
198<procedure>(branches repository [type]) => list</procedure>
199
200Returns a list {{reference}}s to each branch in the given {{repository}}. A
201{{type}} symbol may be given, either {{'local}} or {{'remote}}, to specify what
202type of branches should be listed; by default, {{'local}} is used.
203
204<procedure>(branch-rename repository old new [force]) => void</procedure>
205
206Renames a branch in the given repository from the {{old}} to {{new}}, which
207should be strings. If a true-valued {{force}} is given and a branch with the
208new name already exists, it will be overwritten.
209
210On success, the on-disk repository is updated immediately.
211
212<procedure>(branch-delete repository name [type]) => void</procedure>
213
214Deletes the branch with the given {{name}} in the {{repository}}. A {{type}}
215symbol may be given, either {{'local}} or {{'remote}}, to specify what type of
216branch should be deleted; by default, {{'local}} is used.
217
218On success, the on-disk repository is updated immediately.
219
220==== Generic
221
222<procedure>(object-id object) => oid</procedure>
223
224Returns the {{oid}} referring to the given object, which must be a {{commit}},
225{{tree}}, {{tag}} or {{blob*}}.
226
227<procedure>(object-sha object [length]) => string</procedure>
228
229Returns the SHA1 identifier corresponding to the given object, which may be a
230{{commit}}, {{tree}}, {{tag}} {{blob*}}, {{reference}}, {{oid}} or {{string}}.
231
232<procedure>(object-type object) => symbol</procedure>
233
234Returns a symbol specifying the type of the given object, which must be one of
235{{commit}}, {{tree}}, {{tag}} or {{blob*}}. {{#f}} is returned if the type
236cannot be determined.
237
238==== Blob*
239
240<record>blob*</record>
241<procedure>(blob*? obj) => boolean</procedure>
242
243A {{blob*}} corresponds to Git's Blob object type, renamed in order to avoid
244name clashes with Chicken's built-in {{blob}} type. It represents a file.
245
246<procedure>(blob* repository ref) => blob*</procedure>
247
248Returns the {{blob*}} specified by the given {{ref}} from the repository.
249{{ref}} may be a SHA1 string, {{oid}}, or {{blob*}}. An error is signaled if
250no such {{blob*}} exists.
251
252<procedure>(blob*-content blob*) => blob</procedure>
253
254Returns a {{blob}} (of the Chicken built-in type) with the contents of the given
255{{blob*}} (of the Git object type).
256
257<procedure>(blob*-size blob*) => int</procedure>
258
259Returns the size in bytes of the given {{blob*}}.
260
261==== Commit
262
263<record>commit</record>
264<procedure>(commit? obj) => boolean</procedure>
265
266A {{commit}} corresponds to Git's commit object type.
267
268<procedure>(commit repository ref) => commit</procedure>
269
270Returns the {{commit}} specified by the given {{ref}} from the repository.
271{{ref}} may be a SHA1 string, {{oid}}, {{reference}} or {{commit}}. An error
272is signaled if no such {{commit}} exists.
273
274<procedure>(commits-fold kons knil repository #!key [initial] [hide] [sort]) => list</procedure>
275
276Folds over the given {{repository}}'s commits. If an {{initial}} {{commit}} or
277SHA1 is given, only commits that are ancestors of that revision will be
278returned. If a list of revisions to {{hide}} is given, they and their ancestors
279will be ignored. If a {{sort}} is specified, commits will be collected in the
280given order; this sort order must be one of the symbols {{none}}, {{topo}},
281{{time}} or {{rev}}.
282
283<procedure>(commits repository #!rest args) => list</procedure>
284
285Returns a list of the {{commit}}s in the given {{repository}}. {{args}} follows
286the {{#!key}} arguments specification for {{commits-fold}}.
287
288<procedure>(commit-id commit) => oid</procedure>
289
290Returns the {{oid}} for the given {{commit}}.
291
292<procedure>(commit-time commit) => int</procedure>
293<procedure>(commit-time-offset commit) => int</procedure>
294
295{{commit-time}} and {{commit-time-offset}} return the timestamp of the given
296{{commit}} and its UTC offset in minutes, respectively.
297
298<procedure>(commit-message commit) => string</procedure>
299
300Returns the full commit message of the given {{commit}}.
301
302<procedure>(commit-tree commit) => tree</procedure>
303<procedure>(commit-tree-id commit) => oid</procedure>
304
305Return the {{tree}} associated with the given {{commit}} and its {{oid}},
306respectively.
307
308<procedure>(commit-author commit) => signature</procedure>
309<procedure>(commit-committer commit) => signature</procedure>
310
311{{commit-author}} and {{commit-committer}} return the given {{commit}}'s
312respective {{signature}}s.
313
314<procedure>(commit-parentcount commit) => int</procedure>
315<procedure>(commit-parent commit [n]) => commit</procedure>
316
317{{commit-parentcount}} returns the number of parents for a given {{commit}}.
318
319{{commit-parent}} returns the {{n}}th parent of the given {{commit}}, or the
320first if no {{n}} is given. If the {{commit}} has no parent, {{#f}} is
321returned.
322
323<procedure>(create-commit repository #!key message tree [parents] author [committer] [reference]) => commit</procedure>
324
325Creates & returns a new commit in the given {{repository}}. The string
326{{message}} will be used as the commit's message and {{tree}} will be the file
327tree of the commit. {{parents}} should be be a (possibly empty) list of commits
328to be used as this commit's parents. {{author}} and {{committer}} should be
329signatures; if {{committer}} is not given, {{author}} will be used for both.
330{{reference}}, if given and not {{#f}}, should be the {{reference}} that will
331be updated to point to the newly-created commit.
332
333Note that if no {{reference}} is given, the commit will be created in Git's
334database but will not be reflected in any of the repository's branches. To
335update the the working branch with the new commit, for example, use "HEAD".
336
337On success, the on-disk repository is updated immediately.
338
339<procedure>(merge-base repository commit1 commit2) => commit</procedure>
340
341Returns the nearest common ancestor for the given commits. {{commit1}} and
342{{commit2}} may be {{commit}}s, commit {{oid}}s, or SHA1 hashes.
343
344==== Tag
345
346<record>tag</record>
347<procedure>(tag? obj) => boolean</procedure>
348
349A {{tag}} corresponds to Git's Tag object type, which is a way to mark a
350specific object as special in some way.
351
352<procedure>(tag repository ref) => tag</procedure>
353
354Creates & returns the {{tag}} specified by the given {{ref}} from the
355repository. {{ref}} may be a SHA1 string, {{oid}}, or {{tag}}. An error is
356signaled if no such {{tag}} exists.
357
358<procedure>(tags repository) => list</procedure>
359
360Returns a list of all tags in the given {{repository}}.
361
362<procedure>(tag-id tag) => oid</procedure>
363
364Returns the {{oid}} for the given {{tag}}.
365
366<procedure>(tag-type tag) => symbol</procedure>
367
368Returns the object type symbol of the target of the given {{tag}}, which will
369be one of {{commit}}, {{tree}}, {{blob}}, or {{tag}}.
370
371<procedure>(tag-name tag) => string</procedure>
372<procedure>(tag-message tag) => string</procedure>
373
374Return the name or message of the given {{tag}}.
375
376<procedure>(tag-tagger tag) => signature</procedure>
377
378Returns the {{signature}} of the {{tag}}'s creator.
379
380<procedure>(tag-target tag) => object</procedure>
381<procedure>(tag-peel tag) => object</procedure>
382
383{{tag-target}} returns the object referred to by {{tag}}, which will be of type
384{{commit}}, {{tree}}, {{blob}} or {{tag}}.
385
386{{tag-peel}} is similar to {{tag-target}}, except that it recursively
387dereferences the given {{tag}} until a non-tag object is found and returned.
388
389<procedure>(tag-delete tag) => void</procedure>
390
391Destroys the given {{tag}}.
392
393On success, the on-disk repository is updated immediately.
394
395<procedure>(create-tag repository #!key target name message tagger [force]) => tag</procedure>
396
397Creates & returns a new tag in the given {{repository}} for the specified
398{{name}}, {{message}} and {{target}}. {{name}} and {{message}} must be strings,
399{{tagger}} must be a {{signature}},and {{target}} must be a {{commit}},
400{{tree}} or {{blob*}}. If a tag of the given {{name}} exists and {{force}} is
401not given or {{#f}}, an error is signalled.  Otherwise, creation is forced and
402the old tag will be overwritten.
403
404On success, the on-disk repository is updated immediately.
405
406==== Tree
407
408<record>tree</record>
409<procedure>(tree? obj) => boolean</procedure>
410
411A {{tree}} corresponds to Git's Tree object type, which represents a directory
412tree.
413
414<procedure>(tree repository ref) => tree</procedure>
415
416Returns the {{tree}} specified by the given {{ref}} from the repository. {{ref}}
417may be a SHA1 string, {{oid}}, or {{tree}}. An error is signaled if no such
418{{tree}} exists.
419
420<procedure>(tree-id tree) => oid</procedure>
421
422Returns the {{oid}} for the given {{tree}}.
423
424<procedure>(tree-entrycount tree) => int</procedure>
425
426Returns the number of entries in the given {{tree}}. This count does not
427include entries of contained directories.
428
429<procedure>(tree-ref tree key) => tree-entry</procedure>
430
431Returns a {{tree-entry}} object for the given {{key}} from the tree, or
432{{#f}} if no such tree entry is found. {{key}} may be a zero-based integer
433index or a pathname string.
434
435<procedure>(tree->list tree [repository]) => list</procedure>
436
437Returns a list of {{tree-entry}} objects for the given {{tree}}. If a
438{{repository}} is given, this function will recurse into it, returning a nested
439list of entries spanning the full directory tree.
440
441<procedure>(create-tree repository index) => tree</procedure>
442
443Creates and returns a {{tree}} object from the state of the given {{index}}.
444
445<procedure>(tree-walk tree fn [mode]) => void</procedure>
446
447Invokes the given function {{fn}} on each {{tree-entry}} in the given {{tree}}.
448A walk order may be specified by the symbol {{mode}}, which should be one of
449{{'pre}} or {{'post}}.
450
451==== Tree Entry
452
453<record>tree-entry</record>
454<procedure>(tree-entry? obj) => boolean</procedure>
455
456A {{tree-entry}} represents a single node in a {{tree}} object.
457
458<procedure>(tree-entry-id tree-entry) => oid</procedure>
459
460Returns the {{oid}} of the given {{tree-entry}}.
461
462<procedure>(tree-entry-name tree-entry) => string</procedure>
463
464Returns the name of the given {{tree-entry}}.
465
466<procedure>(tree-entry-attributes tree-entry) => int</procedure>
467
468Returns the Unix file attributes of the given {{tree-entry}}.
469
470<procedure>(tree-entry-type tree-entry) => symbol</procedure>
471
472Returns the object type symbol, either {{tree}} or {{blob}}, of the given
473{{tree-entry}}.
474
475<procedure>(tree-entry->object repository tree-entry) => object</procedure>
476
477Returns an object of type {{tree}} or {{blob*}} from the given {{tree-entry}}
478and {{repository}}, which must be the owner of the {{tree-entry}}.
479
480==== Tree Builder
481
482<record>tree-builder</record>
483<procedure>(tree-builder? obj) => boolean</procedure>
484
485A tree builder provides a way to construct {{tree}} objects in memory and write
486them to a repository, without using an index as an intermediary.
487
488<procedure>(make-tree-builder [tree]) => tree-builder</procedure>
489
490Creates a new {{tree-builder}}. If a {{tree}} is given, it is used as the
491constructed tree's initial state. Otherwise, it must be populated manually
492using {{tree-builder-insert}}.
493
494<procedure>(tree-builder-insert tree-builder object name attributes) => tree-entry</procedure>
495
496Inserts {{object}} into the {{tree-builder}}'s tree under the given filename
497{{name}}. The inserted object must be a {{tree}} or {{blob*}}, and will have
498the given {{attributes}} (an integer file mode).
499
500<procedure>(tree-builder-ref tree-builder path) => tree-entry</procedure>
501
502Returns the {{tree-entry}} from the given {{tree-builder}} at {{path}}, which
503should be a filename string. If the requested file doesn't exist, {{#f}} is
504returned.
505
506<procedure>(tree-builder-remove tree-builder path) => void</procedure>
507
508Removes the object at the given {{path}} from the {{tree-builder}}'s tree.
509
510<procedure>(tree-builder-write repo tree-builder) => tree</procedure>
511
512Writes the {{tree-builder}}'s tree to the given {{repository}}, modifying the
513on-disk repository on success. The resulting {{tree}} is returned.
514
515==== Diff
516
517<record>diff</record>
518<procedure>(diff? obj) => boolean</procedure>
519<record>diff-file</record>
520<procedure>(diff-file? obj) => boolean</procedure>
521
522A {{diff}} is the difference in a single file between two Git {{tree}}s. Each
523diff has a status, similarity, and a pair of {{diff-file}}s for the old and new
524files, respectively.
525
526Each diff-file has an {{oid}}, {{path}}, and {{mode}} (Unix file attributes).
527
528<procedure>(diff repository [tree object]) => list</procedure>
529
530Compares a tree to another object in the given {{repository}}, or compares a
531repository's working directory to its index if no other arguments are given.
532Returns a list of {{diff}} objects is for every difference between them.
533
534{{object}} may be an {{index}}, {{tree}}, or one of the symbols {{'index}} or
535{{'workdir}} to specify a diff target indirectly.
536
537<procedure>(diff-status diff) => symbol</procedure>
538
539Returns a symbol representing the status of a {{diff}}, which will be
540one of the following symbols:
541
542    modified
543    added
544    deleted
545    modified
546    renamed
547    copied
548    ignored
549    untracked
550
551<procedure>(diff-similarity diff) => integer</procedure>
552
553Returns an integer value from 0 to 100 representing the similarity between a
554{{diff}}'s old and new files, high values being representing greater
555similarity.
556
557<procedure>(diff-old-file diff)</procedure>
558<procedure>(diff-new-file diff)</procedure>
559
560Returns the {{diff-file}} object for the old and new file of the given
561{{diff}}, respectively. If the file is added or deleted, {{#f}} will be
562returned for the diff's old or new file, respectively.
563
564<procedure>(diff-file-path diff-file) => string</procedure>
565
566Returns the path of the given {{diff-file}}, relative to the repository's root.
567In the case of a rename, the paths of the old and new {{diff-file}} for a given
568{{diff}} may be different.
569
570<procedure>(diff-file-id diff-file) => oid</procedure>
571
572Returns the {{oid}} of the given {{diff-file}}.
573
574<procedure>(diff-file-mode diff-file) => int</procedure>
575
576Returns the Unix file attributes of the given {{diff-file}}.
577
578<procedure>(diff-old-id diff) => oid</procedure>
579<procedure>(diff-new-id diff) => oid</procedure>
580<procedure>(diff-old-mode diff) => int</procedure>
581<procedure>(diff-new-mode diff) => int</procedure>
582<procedure>(diff-old-path diff) => string</procedure>
583<procedure>(diff-new-path diff) => string</procedure>
584
585Convenience procedures for accessing the fields of a {{diff}} objects's old &
586new {{diff-file}}s.
587
588    (diff-old-id diff) => (diff-file-id (diff-old-file diff))
589
590==== Status
591
592<procedure>(file-status repository path) => symbol</procedure>
593
594Returns the status of the file specified by {{path}} in the given
595{{repository}}.
596
597This status will be one of the following symbols:
598
599    current
600    index/new
601    index/modified
602    index/deleted
603    worktree/new
604    worktree/modified
605    worktree/deleted
606    ignored
607
608Currently, if a file is of two statuses (for example, partially-staged, so it
609is both {{index/modified}} and {{worktree/modified}}) this function will return
610the empty list.
611
612<procedure>(file-ignored? repository path) => boolean</procedure>
613
614Returns a boolean indicating whether the given {{path}} in {{repository}} is
615ignored by Git or not.
616
617==== Index
618
619<record>index</record>
620<procedure>(index? obj) => boolean</procedure>
621
622An {{index}} represents the on-disk state of Git's working tree. Changes made
623to a given {{index}} exist only in memory until written to disk using
624{{index-write}}.
625
626<procedure>(index-open repo-or-path) => index</procedure>
627
628It {{repo-or-path}} is a {{repository}}, returns the repository's index.  If it
629is a string, creates and returns the index at the given path, signaling an
630error if such an index doesn't exist. It is not possible to open the index of a
631bare repository, and doing so will result in an exception.
632
633<procedure>(index-entrycount index) => int</procedure>
634<procedure>(index-entrycount-unmerged index) => int</procedure>
635
636Returns the total number of index entries and unmerged index entries of the
637given {{index}}, respectively. This is essentially a count of all files tracked
638by Git in a given repository.
639
640<procedure>(index-read index) => void</procedure>
641
642Updates the given {{index}} to reflect the current state of the on-disk
643repository.
644
645<procedure>(index-write index) => void</procedure>
646
647Writes the state of the given {{index}} from memory onto disk, modifying the
648repository on success.
649
650<procedure>(index-clear index) => void</procedure>
651
652Removes all enries from a given {{index}}.
653
654<procedure>(index-add index path [stage]) => void</procedure>
655
656Adds a given {{path}}, which must refer to a file relative to the index's
657repository, to the {{index}}. If an integer {{stage}} is given, it will be used
658as the staging number for the changes.
659
660<procedure>(index-remove index ref) => void</procedure>
661
662Removes an entry from the given {{index}}. {{ref}} may be a file path string or
663an zero-based integer index. If no entry is removed, {{#f}} is returned.
664
665<procedure>(index-find index path) => int</procedure>
666
667Returns the zero-based integer index of the file specified by {{path}} in the
668given {{index}}, signaling an error if it doesn't exist.
669
670<procedure>(index-ref index key [type]) => index-entry</procedure>
671
672Returns the {{index-entry}} from the {{index}} for the given {{key}}, which may
673be an zero-based integer index or a pathname string, or {{#f}} if no such entry
674exists. If a type symbol is given, either {{merged}} (the default behavior) or
675{{unmerged}}, the search will be limited to such entries.
676
677<procedure>(index->list index [type]) => list</procedure>
678
679Returns a list of all {{index-entry}} objects in the given {{index}}. If a type
680symbol is given, either {{merged}} (the default behavior) or {{unmerged}}, the
681returned list will be limited to such entries.
682
683==== Index Entry
684
685<record>index-entry</record>
686<procedure>(index-entry? obj) => boolean</procedure>
687
688An {{index-entry}} represents a tracked file in Git's working directory,
689belonging to an {{index}}.
690
691<procedure>(index-entry-id index-entry) => oid</procedure>
692
693Returns the {{oid}} referring to the given {{index-entry}}.
694
695<procedure>(index-entry-path index-entry) => string</procedure>
696
697Returns the file path of the given {{index-entry}} relative to the owning
698repository's working directory.
699
700<procedure>(index-entry-ctime index-entry) => int</procedure>
701<procedure>(index-entry-mtime index-entry) => int</procedure>
702<procedure>(index-entry-dev index-entry) => int</procedure>
703<procedure>(index-entry-ino index-entry) => int</procedure>
704<procedure>(index-entry-size index-entry) => int</procedure>
705<procedure>(index-entry-stage index-entry) => int</procedure>
706<procedure>(index-entry-uid index-entry) => int</procedure>
707<procedure>(index-entry-gid index-entry) => int</procedure>
708<procedure>(index-entry-mode index-entry) => int</procedure>
709<procedure>(index-entry-flags index-entry) => int</procedure>
710<procedure>(index-entry-extended index-entry) => int</procedure>
711
712These methods return the file attributes for the given {{index-entry}} as it
713exists in its in-memory {{index}}.
714
715==== ODB
716
717<record>odb</record>
718<procedure>(odb? obj) => boolean</procedure>
719
720An {{odb}} offers a direct interface to Git's internal object database.
721
722<procedure>(odb-open repo-or-path) => odb</procedure>
723
724It {{repo-or-path}} is a {{repository}}, returns the repository's object
725database. If it is a string, creates and returns the object database at the
726given path, signaling an error if no such database exists.
727
728<procedure>(odb-has-object? odb ref) => boolean</procedure>
729
730Determines if the given {{odb}} contains the given object {{ref}}, which should
731be a SHA1 string, {{oid}} or Git object of type {{commit}}, {{blob*}}, {{tree}}
732or {{tag}}.
733
734<procedure>(odb-read odb ref) => odb-object</procedure>
735
736Reads the given object {{ref}} from the database, signaling an error if it
737doesn't exist. {{ref}} should be a SHA1 string, {{oid}} or Git object of type
738{{commit}}, {{blob*}}, {{tree}} or {{tag}}.
739
740<procedure>(odb-write odb data [type]) => oid</procedure>
741
742Writes a given data {{blob}} to the {{odb}}, returning an {{oid}} referring to
743the newly-created object. The type of the stored data can be specified by an
744optional {{type}} symbol, which defaults to {{blob}}.
745
746<procedure>(odb-hash odb data [type]) => oid</procedure>
747
748Returns an {{oid}} reference for the given data {{blob}} as though it had been
749stored to the given {{odb}} but without writing it to disk. The type of the
750hashed data can be specified by an optional {{type}} symbol, which defaults to
751{{blob}}.
752
753==== ODB Object
754
755<record>odb-object</record>
756<procedure>(odb-object? obj) => boolean</procedure>
757
758An {{odb-object}} is a reference to a blob of data in a Git object database.
759
760<procedure>(odb-object-id odb-object) => oid</procedure>
761
762Returns the {{oid}} for the given {{odb-object}}.
763
764<procedure>(odb-object-size odb-object) => int</procedure>
765
766Returns the size of the {{odb-object}}'s data in bytes.
767
768<procedure>(odb-object-type odb-object) => symbol</procedure>
769
770Returns the object type symbol of the given {{odb-object}}.
771
772<procedure>(odb-object-data odb-object) => blob</procedure>
773
774Returns a blob consisting of the {{odb-object}}'s data.
775
776==== Signature
777
778<record>signature</record>
779<procedure>(signature? obj) => boolean</procedure>
780
781A signature is a record of the name, email, time and UTC offset of a given Git
782object.
783
784<procedure>(make-signature name email [time [offset]]) => signature</procedure>
785
786Returns a new {{signature}} for the given name and email strings. If a
787timestamp {{time}} and integer {{offset}} are given, they will be used as the
788signature time; otherwise, the current time will be used.
789
790Unlike the {{create-*}} functions, no representation of this signature is
791created in the repository; it exists only in memory until associated with a
792{{commit}} or {{tag}}.
793
794<procedure>(signature-name signature) => string</procedure>
795<procedure>(signature-email signature) => string</procedure>
796
797{{signature-name}} and {{signature-email}} return strings for the
798given {{signature}}'s respective fields.
799
800<procedure>(signature-time signature) => int</procedure>
801<procedure>(signature-time-offset signature) => int</procedure>
802
803{{signature-time}} and {{signature-time-offset}} return the timestamp of the
804given {{signature}} and its UTC offset in minutes, respectively.
805
806==== Config
807
808<record>config</record>
809<procedure>(config? obj) => boolean</procedure>
810
811A {{config}} represents a Git configuration file, associated with either a
812repository, the current user, or the system-wide Git installation.
813
814<procedure>(config-path [type]) => string</procedure>
815
816Returns the path to a Git configuration file. {{type}} may be a symbol, either
817{{user}} or {{system}}, to request the path to the configuration for either the
818current user or the system-wide Git installation, respectively. {{type}}
819defaults to {{user}}. An error is signalled if no configuration file is found
820at the requested location.
821
822<procedure>(config-open [source]) => config</procedure>
823
824Reads the Git configuration file indicated by {{source}}, which may be a
825{{repository}}, path, or symbol as expected by {{config-path}}. An
826error is signalled if no configuration file is found at the requested location.
827
828<procedure>(config-get config name [type]) => object</procedure>
829
830Returns the value of the property {{name}} in the given {{config}} object. The
831value is returned as a string, unless an alternative return type is specified
832by the given symbol {{type}}, which should be {{string}}, {{symbol}}, or
833{{number}}. An error is signaled if the requested property doesn't exist, or if
834it cannot be converted to the specified return type.
835
836<procedure>(config-set config name value) => object</procedure>
837
838Sets the value of the property {{name}} in the given {{config}} object to the
839given {{value}}.
840
841On success, the new value is written immediately to disk.
842
843<procedure>(config-unset config name) => void</procedure>
844
845Deletes the property {{name}} from the given {{config}} object.
846
847On success, the change is written immediately to disk.
848
849=== History
850
851* 0.0.15 - libgit2 0.17.0 bindings & diff api changes
852* 0.0.14 - libgit2 0.17.0 compatibility
853* 0.0.13 - libgit2 0.16.0
854
855=== Author
856
857Evan Hanson
858
859=== License
860
861Copyright (c) 2012, Evan Hanson, 3-Clause BSD License
Note: See TracBrowser for help on using the repository browser.