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

Last change on this file since 30814 was 30814, checked in by evhan, 6 years ago

wiki/git: doc update, diffs

File size: 41.6 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.20.0 and Chicken 4.7 or newer.
12
13The source for this egg is available at [[https://bitbucket.org/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
53<procedure>(create-repository [path [bare]]) => repository</procedure>
54
55Creates & returns a new repository at the given {{path}}, or the value of
56{{current-directory}} if no path is given. If {{bare}} is given and not {{#f}},
57the repository will be created without a working directory. An error is
58signaled if the path is invalid or the repository cannot be created.
59
60<procedure>(repository-open [path]) => repository</procedure>
61
62Opens the Git repository indicated by {{path}}, or the value of
63{{current-directory}} if no {{path}} is given. {{path}} may point to a bare
64repository, a working directory containing a ".git" directory, or a ".git"
65directory directly.
66
67<procedure>(repository-path repository) => string</procedure>
68
69Returns the absolute path to the given {{repository}}'s Git directory,
70either the topmost directory in the project (if the repository is bare)
71or the ".git" subdirectory.
72
73<procedure>(repository-working-directory repository) => string</procedure>
74
75Returns the absolute path to the given {{repository}}'s working directory,
76or {{#f}} if the repository is bare.
77
78<procedure>(repository-ref repository ref) => object</procedure>
79
80Looks up a Git object in the given {{repository}}. {{ref}} may be a SHA1 string,
81{{oid}}, {{reference}}, {{blob}}, {{commit}}, {{tag}} or {{tree}}. The returned
82object will be of type {{blob}}, {{commit}}, {{tag}} or {{tree}}, or {{#f}} if
83no object matching the given {{ref}} is found.
84
85<procedure>(repository-empty? repository) => boolean</procedure>
86<procedure>(repository-bare? repositoy) => boolean</procedure>
87
88Returns a boolean indicating whether the given {{repository}} is empty
89(contains no commits) or bare (an exposed git directory without a working
90directory).
91
92<procedure>(repository-head-orphan? repositoy) => boolean</procedure>
93<procedure>(repository-head-detached? repositoy) => boolean</procedure>
94
95Returns a boolean indicating whether the given repository's {{HEAD}} (a
96symbolic reference) is orphaned (unreferenced under the refs namespace)
97or detached (refering to a commit rather than a branch).
98
99==== OID
100
101<record>oid</record>
102<procedure>(oid? obj) => boolean</procedure>
103
104An {{oid}} is a unique reference to a Git object, corresponding to a
10540-character SHA1 object name.
106
107<procedure>(string->oid string) => oid</procedure>
108
109Creates an {{oid}} from the given string, which should be a 40-character SHA1
110hash. An error is signaled if the string is not a valid hash.
111
112<procedure>(oid->string oid [length]) => string</procedure>
113
114Returns the string representation of the given {{oid}}. The optional integer
115{{length}} specifies the length of the returned string, up to 40 characters.
116
117<procedure>(oid->path oid) => string</procedure>
118
119Returns the string representation of the given {{oid}} in the form "xx/...",
120where "xx" is the first two characters of the SHA1 and "..." is the remainder.
121
122<procedure>(oid=? oid1 oid2) => boolean</procedure>
123
124Indicates whether the two {{oid}}s are the equivalent.
125
126==== Revspec
127
128<procedure>(parse-revision-specification string) => (values object object)</procedure>
129
130Attempts to parse a string as a Git revision specification, returning
131two values:
132
133* If {{string}} specifies a range of revisions, the start & end
134  {{commit}} objects.
135* If {{string}} specifies a single revision, the {{commit}} object and
136  {{#f}}.
137* If {{string}} is invalid or fails to match a revision, {{#f}} for both
138  values.
139
140For more information about specifying revisions, see
141[[http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions]].
142
143==== Reference
144
145<record>reference</record>
146<procedure>(reference? obj) => boolean</procedure>
147
148A {{reference}} is a direct or indirect pointer to a Git commit object. A
149repository's {{HEAD}} is a common example: it is a symbolic reference,
150referring to the immediate reference {{"refs/heads/master"}}, which in turn
151points at a {{commit}}.
152
153<procedure>(reference repository ref) => reference</procedure>
154
155Returns the {{reference}} specified by the given string {{ref}} from the
156{{repository}}. {{ref}} must be a string referring to a valid reference, such
157as {{HEAD}}, {{"ref/heads/master"}}, or {{"refs/tags/v0.1.0"}}. An error is
158signalled if the reference doesn't exists.
159
160<procedure>(reference-name reference) => string</procedure>
161
162Returns the name of the given {{reference}}.
163
164<procedure>(reference-type reference) => symbol</procedure>
165
166Returns the type symbol of the given {{reference}}, which will be either
167{{oid}} or {{symbolic}}.
168
169<procedure>(reference-remote? reference) => boolean</procedure>
170<procedure>(reference-branch? reference) => boolean</procedure>
171
172These procedures return boolean values indicating whether the given
173reference is a remote- or branch-type reference, respectively.
174
175<procedure>(references-fold kons knil repository [type]) => object</procedure>
176
177Folds over the given {{repository}}'s references in unspecified order.
178
179An optional {{type}} symbol may be provided to limit the types of
180references returnd, and may be one of the symbols {{oid}},
181{{symbolic}}, or {{all}}. If no {{type}} is given, {{all}} is used.
182
183<procedure>(references repository [type]) => list</procedure>
184
185Returns a list of all references in the given {{repository}}. A type
186symbol may be given to filter the references, as in {{references-fold}}.
187
188<procedure>(repository-head repository) => reference</procedure>
189
190Returns a reference to this repository's HEAD (resolved to an OID), of
191{{#f}} if it doesn't exist.
192
193<procedure>(reference-resolve reference) => reference</procedure>
194
195Recursively dereferences the given (possibly symbolic) {{reference}},
196returning a new non-symbolic {{reference}} pointing refering directly to
197an {{oid}}.
198
199<procedure>(reference-target reference) => oid</procedure>
200
201Returns the {{oid}} of the object which the given {{reference}} refers.
202Symbolic references are peeled until a non-symbolic reference is found,
203as with {{reference-resolve}}.
204
205<procedure>(reference-rename reference name [force]) => reference</procedure>
206<procedure>(reference-target-set! reference target) => void</procedure>
207
208{{reference-rename}} changes the name of the given {{reference}} to the
209string {{name}} and returns the newly-updated {{reference}}. If
210{{force}} is given and nonfalse, any previously-existing {{reference}}
211of the given {{name}} will be overwritten.
212
213{{reference-target-set!}} updates a {{reference}} to refer to the given
214{{target}}. If {{reference}} is an immediate reference (referring to an object
215ID), {{target}} must be an {{oid}}, {{commit}}, or SHA1 string. If
216{{reference}} is symbolic, {{target}} must be a {{reference}} or reference
217name. It is an error to assign a symbolic reference an OID target and
218vice-versa.
219
220On success, the on-disk repository is updated immediately.
221
222<procedure>(create-reference repository #!key name target [symbolic] [force]) => reference</procedure>
223
224Creates & returns a new reference in the given {{repository}} for the specified
225{{name}} and {{target}}. If {{symbolic}} is given and not {{#f}}, the created
226reference will be so, and {{target}} must be a reference name or {{reference}}.
227Otherwise, {{target}} must be a SHA1 string, {{oid}}, {{commit}} or
228{{reference}} to a {{commit}}. If a reference of the given {{name}} exists and
229{{force}} is not given or {{#f}}, an error is signalled. Otherwise, creation
230is forced and the old reference will be overwritten.
231
232On success, the on-disk repository is updated immediately.
233
234<procedure>(reference-delete reference) => void</procedure>
235
236Deletes the given {{reference}} from its repository.
237
238On success, the on-disk repository is updated immediately.
239
240==== Branch
241
242<procedure>(create-branch repository name target [force]) => reference</procedure>
243
244Creates a new branch in the given {{repository}} of the given {{name}} and
245{{target}} and returns a {{reference}} to the new branch. {{target}} must be a
246{{commit}} or {{tag}} belonging to the repository. If a branch of the given
247{{name}} exists and {{force}} is not given or {{#f}}, an error is signalled.
248Otherwise, creation is forced and the old branch is be overwritten.
249
250On success, the on-disk repository is updated immediately.
251
252<procedure>(branches-fold kons knil repository [type]) => object</procedure>
253
254Folds over the given {{repository}}'s branches in unspecified order.
255
256A {{type}} symbol may be given, either {{local}}, {{remote}}, or
257{{all}}, to specify what type of branches should be listed; by default,
258{{all}} is used.
259
260<procedure>(branches repository [type]) => list</procedure>
261
262Returns a list {{reference}} objects for each branch in the given
263{{repository}}. A type symbol may be given to filter the branches, as in
264{{branches-fold}}.
265
266<procedure>(branch-name reference) => string</procedure>
267
268Returns the name of the given branch {{reference}}. This is similar to
269{{reference-name}}, but the leading reference namespace (e.g.
270"refs/heads") is omitted.
271
272<procedure>(branch-rename reference name [force]) => reference</procedure>
273
274Renames the given branch {{reference}} to {{name}}, which should be a
275string. If {{force}} is given and not false, any existing branch with
276the given name will be overwritten. A new, renamed {{reference}} is
277returned.
278
279On success, the on-disk repository is updated immediately.
280
281<procedure>(branch-delete reference) => void</procedure>
282
283Deletes the given branch {{reference}} from its repository.
284
285On success, the on-disk repository is updated immediately.
286
287==== Generic Procedures
288
289These procedures can be used on any objects of the four main Git object
290types: {{commit}}, {{tree}}, {{tag}} and {{blob*}}.
291
292<procedure>(object-id object) => oid</procedure>
293
294Returns the {{oid}} of the given object, which must be a {{commit}},
295{{tree}}, {{tag}} or {{blob}}.
296
297<procedure>(object-sha object [length]) => string</procedure>
298
299Returns the SHA1 identifier corresponding to the given object, which may be a
300{{commit}}, {{tree}}, {{tag}} {{blob}}, {{reference}}, {{oid}} or {{string}}.
301
302<procedure>(object-type object) => symbol</procedure>
303
304Returns a symbol specifying the type of the given object, which must be
305a {{commit}}, {{tree}}, {{tag}} or {{blob}}. {{#f}} is returned if the
306object's type cannot be determined.
307
308<procedure>(object=? object1 object2) => boolean</procedure>
309
310Indicates whether the two Git objects represent the same thing (judging
311by their respective {{oid}}s). Each object should be of type {{commit}},
312{{tree}}, {{tag}} or {{blob}}.
313
314==== Blob
315
316<record>blob</record>
317<procedure>(blob? obj) => boolean</procedure>
318
319A {{blob}} corresponds to Git's Blob object type. It represents a chunk
320of data, generally a file.
321
322Beware name collisions with CHICKEN's built-in {{blob}} data type.
323
324<procedure>(blob repository ref) => blob</procedure>
325
326Returns the {{blob}} specified by the given {{ref}} from the repository.
327{{ref}} may be a SHA1 string, {{oid}}, or {{blob}}. An error is signaled if
328no such {{blob}} exists.
329
330<procedure>(blob-id commit) => oid</procedure>
331
332Returns the {{oid}} of the given {{blob}}.
333
334<procedure>(blob-content blob) => blob</procedure>
335
336Returns a blob (of the CHICKEN built-in type) of the contents of the
337given {{blob}} (of the Git object type).
338
339<procedure>(blob-length blob) => int</procedure>
340
341Returns the size in bytes of the given {{blob}}.
342
343<procedure>(blob-binary? blob) => boolean</procedure>
344
345Indicates whether the given {{blob}} is (likely to be) a binary chunk
346or not.
347
348<procedure>(create-blob repository source) => blob</procedure>
349
350Creates a new {{blob}} in the given {{repository}}.
351
352{{source}} is the data source for the {{blob}}, and may be a blob (of
353the CHICKEN built-in type) or a pathname string indicating a file on the
354local disk or, if such a file isn't present, a file relative to the
355repository's working directory.
356
357On success, the on-disk repository is updated immediately.
358
359==== Commit
360
361<record>commit</record>
362<procedure>(commit? obj) => boolean</procedure>
363
364A {{commit}} corresponds to Git's commit object type.
365
366<procedure>(commit repository ref) => commit</procedure>
367
368Returns the {{commit}} specified by the given {{ref}} from the repository.
369{{ref}} may be a SHA1 string, {{oid}}, {{reference}} or {{commit}}. An error
370is signaled if no such {{commit}} exists.
371
372<procedure>(commits-fold kons knil repository #!key [initial] [hide] [sort]) => object</procedure>
373
374Folds over the given {{repository}}'s commits. If an {{initial}} {{commit}} or
375SHA1 is given, only commits that are ancestors of that revision will be
376returned. If a list of revisions to {{hide}} is given, they and their ancestors
377will be ignored. If a {{sort}} is specified, commits will be collected in the
378given order; this sort order must be one of the symbols {{none}}, {{topo}},
379{{time}} or {{reverse}}.
380
381<procedure>(commits repository #!rest args) => list</procedure>
382
383Returns a list of the {{commit}}s in the given {{repository}}. {{args}} follows
384the {{#!key}} arguments specification for {{commits-fold}}.
385
386<procedure>(commit-id commit) => oid</procedure>
387
388Returns the {{oid}} for the given {{commit}}.
389
390<procedure>(commit-time commit) => int</procedure>
391<procedure>(commit-time-offset commit) => int</procedure>
392
393{{commit-time}} and {{commit-time-offset}} return the timestamp of the given
394{{commit}} and its UTC offset in minutes, respectively.
395
396<procedure>(commit-message commit) => string</procedure>
397<procedure>(commit-message-encoding commit) => string</procedure>
398
399Returns the full commit message or message encoding for the given
400{{commit}}.
401
402<procedure>(commit-tree commit) => tree</procedure>
403<procedure>(commit-tree-id commit) => oid</procedure>
404
405Return the {{tree}} associated with the given {{commit}} and its {{oid}},
406respectively.
407
408<procedure>(commit-author commit) => signature</procedure>
409<procedure>(commit-committer commit) => signature</procedure>
410
411{{commit-author}} and {{commit-committer}} return the given {{commit}}'s
412respective {{signature}}s.
413
414<procedure>(commit-parentcount commit) => int</procedure>
415<procedure>(commit-parent commit [n]) => commit</procedure>
416<procedure>(commit-parents commit) => list</procedure>
417<procedure>(commit-ancestor commit [n]) => commit</procedure>
418
419{{commit-parentcount}} returns the number of parents of the given
420{{commit}}.
421
422{{commit-parent}} returns the {{n}}th parent of the given {{commit}}, or
423the first parent if no {{n}} is given. If the {{commit}} has no parent,
424{{#f}} is returned.
425
426{{commit-parents}} returns the possibly-empty list of all parents of the
427given {{commit}}. The order of this list is unspecified.
428
429{{commit-ancestor}} returns the {{n}}th ancestor of the given commit, or
430{{#f}} is no such ancestor exists. {{n}} defaults to {{1}}, meaning the
431{{commit}}'s first parent (making {{(commit-ancestor c 1)}} equivalent
432to {{(commit-parent c)}}).
433
434<procedure>(create-commit repository #!key message author [committer] [tree] [parents] [reference]) => commit</procedure>
435
436Creates & returns a new commit in the given {{repository}}. The string
437{{message}} will be used as the commit's message and {{tree}} will be
438the file tree of the commit. If no {{tree}} is given, the current state
439of the repository's {{index}} is used. {{parents}} may be be a (possibly
440empty) list of commits to be used as this commit's ancestors. {{author}}
441and {{committer}} should be signatures; if {{committer}} is not given,
442{{author}} will be used for both. {{reference}}, if given and not
443{{#f}}, should be the {{reference}} or name of a {{reference}} that will
444be updated to point to the newly-created commit.
445
446Note that if no {{reference}} is given, the commit will be created in
447Git's database but will not be reflected in any of the repository's
448branches. To update the the working branch with the new commit, for
449example, use {{"HEAD"}}.
450
451On success, the on-disk repository is updated immediately.
452
453<procedure>(merge-base repository commit1 commit2) => commit</procedure>
454
455Returns the nearest common ancestor for the given commits. {{commit1}} and
456{{commit2}} may be {{commit}}s, commit {{oid}}s, or SHA1 hashes.
457
458==== Tag
459
460<record>tag</record>
461<procedure>(tag? obj) => boolean</procedure>
462
463A {{tag}} corresponds to Git's Tag object type, which is a way to mark a
464specific object as special in some way.
465
466<procedure>(tag repository ref) => tag</procedure>
467
468Creates & returns the {{tag}} specified by the given {{ref}} from the
469repository. {{ref}} may be a SHA1 string, {{oid}}, or {{tag}}. An error is
470signaled if no such {{tag}} exists.
471
472<procedure>(tags-fold kons knil repository) => object</procedure>
473
474Folds over the given repository's {{tag}}s in unspecified order.
475
476<procedure>(tags repository) => list</procedure>
477
478Returns a list of all tags in the given {{repository}}.
479
480<procedure>(tag-id tag) => oid</procedure>
481
482Returns the {{oid}} for the given {{tag}}.
483
484<procedure>(tag-type tag) => symbol</procedure>
485
486Returns the object type symbol of the target of the given {{tag}}, which will
487be one of {{commit}}, {{tree}}, {{blob}}, or {{tag}}.
488
489<procedure>(tag-name tag) => string</procedure>
490<procedure>(tag-message tag) => string</procedure>
491
492Return the name or message of the given {{tag}}.
493
494<procedure>(tag-tagger tag) => signature</procedure>
495
496Returns the {{signature}} of the {{tag}}'s creator.
497
498<procedure>(tag-peel tag) => object</procedure>
499
500Recursively dereferences the given {{tag}} until a non-tag object to
501which it refers is found (and returned).
502
503<procedure>(tag-target tag) => object</procedure>
504<procedure>(tag-peel tag) => object</procedure>
505
506{{tag-target}} returns the object referred to by {{tag}}, which will be of type
507{{commit}}, {{tree}}, {{blob}} or {{tag}}.
508
509Returns the object immediately referred to by {{tag}}, which will be of
510type {{commit}}, {{tree}}, {{blob}} or {{tag}}.
511
512<procedure>(tag-delete tag) => void</procedure>
513
514Destroys the given {{tag}}.
515
516On success, the on-disk repository is updated immediately.
517
518<procedure>(create-tag repository #!key target name message tagger [force]) => tag</procedure>
519
520Creates & returns a new tag in the given {{repository}} for the specified
521{{name}}, {{message}} and {{target}}. {{name}} and {{message}} must be strings,
522{{tagger}} must be a {{signature}},and {{target}} must be a {{commit}},
523{{tree}} or {{blob}}. If a tag of the given {{name}} exists and {{force}} is
524not given or {{#f}}, an error is signalled.  Otherwise, creation is forced and
525the old tag will be overwritten.
526
527On success, the on-disk repository is updated immediately.
528
529==== Tree
530
531<record>tree</record>
532<procedure>(tree? obj) => boolean</procedure>
533
534A {{tree}} corresponds to Git's Tree object type, which represents a directory
535tree.
536
537<procedure>(tree repository ref) => tree</procedure>
538
539Returns the {{tree}} specified by the given {{ref}} from the repository. {{ref}}
540may be a SHA1 string, {{oid}}, or {{tree}}. An error is signaled if no such
541{{tree}} exists.
542
543<procedure>(tree-id tree) => oid</procedure>
544
545Returns the {{oid}} for the given {{tree}}.
546
547<procedure>(tree-entrycount tree) => int</procedure>
548
549Returns the number of entries in the given {{tree}}. This count does not
550include entries of contained directories.
551
552<procedure>(tree-ref tree key) => tree-entry</procedure>
553
554Returns a {{tree-entry}} object for the given {{key}} from the tree, or
555{{#f}} if no such tree entry is found. {{key}} may be a zero-based
556integer index or a pathname string relative to the repository's working
557directory.
558
559<procedure>(tree-fold kons knil tree) => object</procedure>
560
561Folds over each path and {{tree-entry}} objects in the given {{tree}}.
562
563Note that {{kons}} should be a function of three arguments; the path to
564the current {{tree-entry}} (a string, relative to the repository's working
565directory), the current {{tree-entry}}, and the current state of the
566fold.
567
568<procedure>(tree-entries tree) => list</procedure>
569
570Returns an alist of all {{tree-entry}} objects in the given {{tree}},
571whose keys are the pathname strings indicating the {{tree-entry}}'s
572location in the repository and whose keys are the {{tree-entry}} objects
573themselves.
574
575<procedure>(create-tree repository [index]) => tree</procedure>
576
577Creates and returns a new {{tree}} object from the state of the given
578{{index}} in the given {{repository}}.
579
580If {{index}} is not given, a fresh {{index}} for the repository is used.
581This means the resulting {{tree}} will be identical to that of the
582repository's {{HEAD}}.
583
584On success, the new value is written immediately to disk.
585
586==== Tree Entry
587
588<record>tree-entry</record>
589<procedure>(tree-entry? obj) => boolean</procedure>
590
591A {{tree-entry}} represents a single node in a {{tree}} object.
592
593<procedure>(tree-entry-id tree-entry) => oid</procedure>
594
595Returns the {{oid}} of the given {{tree-entry}}.
596
597<procedure>(tree-entry-name tree-entry) => string</procedure>
598
599Returns the name of the given {{tree-entry}}.
600
601<procedure>(tree-entry-attributes tree-entry) => int</procedure>
602
603Returns the Unix file attributes of the given {{tree-entry}}.
604
605<procedure>(tree-entry-type tree-entry) => symbol</procedure>
606
607Returns the object type symbol, either {{tree}} or {{blob}}, of the given
608{{tree-entry}}.
609
610<procedure>(tree-entry->object [repository] tree-entry) => object</procedure>
611
612Returns an object of type {{tree}} or {{blob}} from the given {{tree-entry}}
613and {{repository}}, which must be the owner of the {{tree-entry}}.
614
615If no {{repository}} is given, {{tree-entry->object}} will attempt to
616determine the owning repository from the {{tree-entry}}. This is only
617possible if the {{tree-entry}} belongs to a {{tree}}; if it belongs to a
618{{tree-builder}}, instead, an error will be signaled.
619
620==== Tree Builder
621
622<record>tree-builder</record>
623<procedure>(tree-builder? obj) => boolean</procedure>
624
625A tree builder provides a way to construct {{tree}} objects in memory and write
626them to a repository, without using an index as an intermediary.
627
628<procedure>(make-tree-builder [tree]) => tree-builder</procedure>
629
630Creates a new {{tree-builder}}. If a {{tree}} is given, it is used as the
631constructed tree's initial state. Otherwise, it must be populated manually
632using {{tree-builder-insert}}.
633
634<procedure>(tree-builder-insert tree-builder object name attributes) => tree-entry</procedure>
635
636Inserts {{object}} into the {{tree-builder}}'s tree under the given filename
637{{name}}. The inserted object must be a {{tree}} or {{blob}}, and will have
638the given {{attributes}} (an integer file mode).
639
640<procedure>(tree-builder-ref tree-builder path) => tree-entry</procedure>
641
642Returns the {{tree-entry}} from the given {{tree-builder}} at {{path}}, which
643should be a filename string. If the requested file doesn't exist, {{#f}} is
644returned.
645
646<procedure>(tree-builder-remove tree-builder path) => void</procedure>
647
648Removes the object at the given {{path}} from the {{tree-builder}}'s tree.
649
650<procedure>(tree-builder-write repository tree-builder) => tree</procedure>
651
652Writes the {{tree-builder}}'s current state to the given {{repository}},
653modifying the on-disk repository on success. The resulting {{tree}} is
654returned.
655
656==== Diff
657
658<record>diff</record>
659<procedure>(diff? obj) => boolean</procedure>
660
661A {{diff}} is the cumulative difference between two Git {{tree}}s (or
662{{tree}}-like objects). It consists of a number of {{diff-delta}}s, each
663of which represents the difference in a single file.
664
665<procedure>(diff repository [object1 [object2]]) => diff</procedure>
666
667Returns a {{diff}} between two objects in the {{repository}}.
668
669{{diff}}'s behavior is as follows, given the following arguments:
670
671* {{()}}: diff the repository's index to its working directory
672* {{(index)}}: diff the given index to the repository's working directory
673* {{(tree)}}: diff the given tree to the repository's working directory
674* {{(tree tree)}}: diff the given trees
675* {{(tree index)}}: diff the given tree to the given index
676
677<procedure>(diff-fold kons knil diff) => object</procedure>
678
679Folds over the given {{diff}}'s {{diff-delta}}s in unspecified (but
680consistent) order.
681
682<procedure>(diffs repository [object1 [object2]]) => (list-of diff-delta)</procedure>
683
684Returns a list of {{diff-deltas}} for the {{diff}} between two objects
685in the given {{repository}}. This is equivalent to calling {{(diff
686repository object1 object2)}}, then immediately building a list from the
687resulting {{diff}} record with {{diff-fold}}.
688
689<record>diff-delta</record>
690<procedure>(diff-delta-path diff) => string</procedure>
691<procedure>(diff-delta-status diff) => symbol</procedure>
692<procedure>(diff-delta-old-file diff) => diff-file</procedure>
693<procedure>(diff-delta-new-file diff) => diff-file</procedure>
694<record>diff-file</record>
695<procedure>(diff-file? obj) => boolean</procedure>
696<procedure>(diff-file-id diff-file) => oid</procedure>
697<procedure>(diff-file-path diff-file) => string</procedure>
698<procedure>(diff-file-size diff-file) => integer</procedure>
699<procedure>(diff-file-mode diff-file) => integer</procedure>
700
701A {{diff-delta}} is the difference in a single file between two Git {{tree}}s.
702Each diff has a path, a status, a pair of {{diff-file}}s for the old and
703new files (retrieved by {{diff-old-file}} and {{diff-new-file}},
704respectively), and a list of {{diff-hunk}}s representing individual
705changes.
706
707Each {{diff-file}} has an {{id}}, {{path}}, {{size}} and {{mode}} (Unix
708file attributes).
709
710<procedure>(diff-status diff) => symbol</procedure>
711
712Returns a symbol representing the status of a {{diff}}, which will be
713one of the following symbols, or a list of them if the {{diff}}'s file
714is in multiple statuses:
715
716    modified
717    added
718    deleted
719    modified
720    renamed
721    copied
722    ignored
723    untracked
724
725<procedure>(diff-old-file diff) => diff-file</procedure>
726<procedure>(diff-new-file diff) => diff-file</procedure>
727
728Returns the {{diff-file}} object for the old and new file of the given
729{{diff}}, respectively. If the file is added or deleted, {{#f}} will be
730returned for the diff's old or new file, respectively.
731
732<procedure>(diff-hunks diff) => (list-of diff-hunk)</procedure>
733
734Returns the list of {{diff-hunk}}s in the given {{diff}}.
735
736<record>diff-hunk</record>
737<procedure>(diff-hunk? obj) => boolean</procedure>
738<procedure>(diff-hunk-header diff) => string</procedure>
739<procedure>(diff-hunk-old-lines diff) => integer</procedure>
740<procedure>(diff-hunk-old-start diff) => integer</procedure>
741<procedure>(diff-hunk-new-lines diff) => integer</procedure>
742<procedure>(diff-hunk-new-start diff) => integer</procedure>
743
744A {{diff-hunk}} represents a group of changes in a diff, with some
745surrounding context. Each has a header describing the change, line
746counts and start offsets for the old and new versions of the hunk, and a
747list of {{diff-line}}s representing each added or deleted range of bytes
748in the group of changes.
749
750<procedure>(diff-hunk-lines diff) => (list-of diff-line)</procedure>
751
752<record>diff-line</record>
753<procedure>(diff-line? obj) => boolean</procedure>
754<procedure>(diff-line-origin diff) => char</procedure>
755<procedure>(diff-line-content diff) => string</procedure>
756<procedure>(diff-line-num-lines diff) => integer</procedure>
757<procedure>(diff-line-old-lineno diff) => integer</procedure>
758<procedure>(diff-line-new-lineno diff) => integer</procedure>
759
760A {{diff-line}} is a range of bytes in a {{diff-hunk}} and represents
761either an addition, a deletion, or a range that is present in both the
762old and new versions of the hunk but is included for context. Which of
763these a given {{diff-line}} corresponds to is indicated by its
764{{diff-line-origin}}, one of {{#\+}}, {{#\-}} or {{#\space}}.
765
766==== Status
767
768<procedure>(file-status repository path) => symbol</procedure>
769
770Returns the status of the file specified by {{path}} in the given
771{{repository}}.
772
773This status will be one of the following symbols, or a list of them if
774the file is in multiple statuses:
775
776    current
777    index/new
778    index/modified
779    index/deleted
780    worktree/new
781    worktree/modified
782    worktree/deleted
783    ignored
784
785<procedure>(file-statuses-fold kons knil repository) => object</procedure>
786
787Folds over each path and corresponding file status in the given
788{{repository}}'s working directory.
789
790Note that {{kons}} should be a function of three arguments; the pathname
791of the current file (a string, relative to the repository's working
792directory), the current status symbol, and the current state of the
793fold.
794
795<procedure>(file-statuses repository) => list</procedure>
796
797Returns an alist all file statuses in the given {{repository}}, whose
798keys are the pathnames of the file  in the repository and whose keys are
799the status symbols of the files.
800
801<procedure>(file-ignored? repository path) => boolean</procedure>
802
803Returns a boolean indicating whether the given {{path}} in {{repository}} is
804ignored by Git or not.
805
806==== Note
807
808<record>note</record>
809<procedure>(note? obj) => boolean</procedure>
810
811A {{note}} is a type of reference, stored under the {{refs/notes}}
812namespace. It's used to associate some data (accessible via
813{{note-message}}) with an object.
814
815<procedure>(note-message note) => string</procedure>
816<procedure>(note-id note) => oid</procedure>
817
818{{note-message}} and {{note-id}} return the string content and {{oid}}
819of the given {{note}}, respectively.
820
821<procedure>(note repository object [reference]) => note</procedure>
822
823Returns the {{note}} associated with the given {{object}} in the
824{{repository}}. {{reference}} may be a string specifying an alternative
825notes reference namespace, which defaults to {{"refs/notes/commits"}}.
826An error is signaled if no such {{note}} exists.
827
828<procedure>(delete-note repository #!key target author [committer] [reference]) => void</procedure>
829
830Deletes all notes for the given object {{target}} by the given
831{{author}} in the {{repository}}. {{author}} and {{committer}} should be a
832{{signature}}s, while {{reference}} may specify an alternative notes
833reference namespace, which defaults to {{"refs/notes/commits"}}.
834
835On success, the note is removed from disk immediately. An error is
836signaled if no such {{note}} exists.
837
838<procedure>(create-note repository #!key message target reference author [committer] [force]) => note</procedure>
839
840Creates & returns a new {{note}} in the given {{repository}} with the
841specified {{message}} and {{target}} object. {{author}} and
842{{committer}} should be {{signature}}s, while {{reference}} may specify
843an alternative notes reference namespace, which defaults to
844{{"refs/notes/commits"}}. If {{force}} is given and not {{#f}}, an
845existing note for the same {{target}} and {{author}}/{{committer}} will
846be overwritten; otherwise, an error will be signaled if such a {{note}}
847already exists.
848
849On success, the on-disk repository is updated immediately.
850
851<procedure>(notes-fold kons knil repository [reference]) => object</procedure>
852
853Folds over the given {{repository}}'s notes in unspecified order.
854
855{{reference}} may specify an alternative notes reference namespace,
856which defaults to {{"refs/notes/commits"}}.
857
858<procedure>(notes repository [reference]) => list</procedure>
859
860Returns a list of all notes in the given {{repository}}.
861
862{{reference}} may specify an alternative notes reference namespace,
863which defaults to {{"refs/notes/commits"}}.
864
865==== Index
866
867<record>index</record>
868<procedure>(index? obj) => boolean</procedure>
869
870An {{index}} represents the on-disk state of Git's working tree. Changes made
871to a given {{index}} exist only in memory until written to disk using
872{{index-write}}.
873
874<procedure>(index-open repository-or-path) => index</procedure>
875
876It {{repository-or-path}} is a {{repository}}, {{index-open}} returns
877the repository's index. If it's a string, {{index-open}} creates and
878returns the index at the given path, signaling an error if such an index
879doesn't exist. It is not possible to open the index of a bare
880repository, and doing so will result in an exception.
881
882<procedure>(index-entrycount index) => int</procedure>
883
884Returns the total number of index entries entries of the given
885{{index}}, respectively. This is essentially a count of all files
886tracked by Git in a given repository.
887
888<procedure>(index-read index) => void</procedure>
889
890Updates the given {{index}} to reflect the current state of the on-disk
891repository.
892
893<procedure>(index-write index) => void</procedure>
894
895Writes the state of the given {{index}} from memory onto disk, modifying
896the repository on success.
897
898<procedure>(index-clear index) => void</procedure>
899
900Removes all enries from a given {{index}}.
901
902<procedure>(index-add index path [stage]) => void</procedure>
903
904Adds a given {{path}}, which must refer to a file relative to the index's
905repository, to the {{index}}. If an integer {{stage}} is given, it will be used
906as the staging number for the changes.
907
908<procedure>(index-remove index ref) => void</procedure>
909
910Removes an entry from the given {{index}}. {{ref}} may be a file path string or
911an zero-based integer index. If no entry is removed, {{#f}} is returned.
912
913<procedure>(index-find index path) => int</procedure>
914
915Returns the zero-based integer index of the file specified by {{path}} in the
916given {{index}}, signaling an error if it doesn't exist.
917
918<procedure>(index-ref index key [type]) => index-entry</procedure>
919
920Returns the {{index-entry}} from the {{index}} for the given {{key}}, which may
921be an zero-based integer index or a pathname string, or {{#f}} if no such entry
922exists. If a type symbol is given, either {{merged}} (the default behavior) or
923{{unmerged}}, the search will be limited to such entries.
924
925==== Index Entry
926
927<record>index-entry</record>
928<procedure>(index-entry? obj) => boolean</procedure>
929
930An {{index-entry}} represents a tracked file in Git's working directory,
931belonging to an {{index}}.
932
933<procedure>(index-entry-id index-entry) => oid</procedure>
934
935Returns the {{oid}} referring to the given {{index-entry}}.
936
937<procedure>(index-entry-path index-entry) => string</procedure>
938
939Returns the file path of the given {{index-entry}} relative to the owning
940repository's working directory.
941
942<procedure>(index-entry-ctime index-entry) => int</procedure>
943<procedure>(index-entry-mtime index-entry) => int</procedure>
944<procedure>(index-entry-dev index-entry) => int</procedure>
945<procedure>(index-entry-ino index-entry) => int</procedure>
946<procedure>(index-entry-size index-entry) => int</procedure>
947<procedure>(index-entry-stage index-entry) => int</procedure>
948<procedure>(index-entry-uid index-entry) => int</procedure>
949<procedure>(index-entry-gid index-entry) => int</procedure>
950<procedure>(index-entry-mode index-entry) => int</procedure>
951<procedure>(index-entry-flags index-entry) => int</procedure>
952<procedure>(index-entry-extended index-entry) => int</procedure>
953
954These methods return the file attributes for the given {{index-entry}} as it
955exists in its in-memory {{index}}.
956
957==== ODB
958
959<record>odb</record>
960<procedure>(odb? obj) => boolean</procedure>
961
962An {{odb}} offers a direct interface to Git's internal object database.
963
964<procedure>(odb-open repository-or-path) => odb</procedure>
965
966It {{repository-or-path}} is a {{repository}}, returns the repository's
967object database. If it is a string, creates and returns the object
968database at the given path, signaling an error if no such database
969exists.
970
971<procedure>(odb-has-object? odb ref) => boolean</procedure>
972
973Determines if the given {{odb}} contains the given object {{ref}}, which should
974be a SHA1 string, {{oid}} or Git object of type {{commit}}, {{blob}}, {{tree}}
975or {{tag}}.
976
977<procedure>(odb-read odb ref) => odb-object</procedure>
978
979Reads the given object {{ref}} from the database, signaling an error if it
980doesn't exist. {{ref}} should be a SHA1 string, {{oid}} or Git object of type
981{{commit}}, {{blob}}, {{tree}} or {{tag}}.
982
983<procedure>(odb-write odb data [type]) => oid</procedure>
984
985Writes a given data {{blob}} to the {{odb}}, returning an {{oid}} referring to
986the newly-created object. The type of the stored data can be specified by an
987optional {{type}} symbol, which defaults to {{blob}}.
988
989<procedure>(odb-hash odb data [type]) => oid</procedure>
990
991Returns an {{oid}} reference for the given data {{blob}} as though it had been
992stored to the given {{odb}} but without writing it to disk. The type of the
993hashed data can be specified by an optional {{type}} symbol, which defaults to
994{{blob}}.
995
996==== ODB Object
997
998<record>odb-object</record>
999<procedure>(odb-object? obj) => boolean</procedure>
1000
1001An {{odb-object}} is a reference to a blob of data in a Git object database.
1002
1003<procedure>(odb-object-id odb-object) => oid</procedure>
1004
1005Returns the {{oid}} for the given {{odb-object}}.
1006
1007<procedure>(odb-object-size odb-object) => int</procedure>
1008
1009Returns the size of the {{odb-object}}'s data in bytes.
1010
1011<procedure>(odb-object-type odb-object) => symbol</procedure>
1012
1013Returns the object type symbol of the given {{odb-object}}.
1014
1015<procedure>(odb-object-data odb-object) => blob</procedure>
1016
1017Returns a blob consisting of the {{odb-object}}'s data.
1018
1019==== Signature
1020
1021<record>signature</record>
1022<procedure>(signature? obj) => boolean</procedure>
1023
1024A signature is a record of the name, email, time and UTC offset of a given Git
1025object.
1026
1027<procedure>(make-signature name email [time [offset]]) => signature</procedure>
1028
1029Returns a new {{signature}} for the given name and email strings. If a
1030timestamp {{time}} and integer {{offset}} are given, they will be used as the
1031signature time; otherwise, the current time will be used.
1032
1033Unlike the {{create-*}} functions, no representation of this signature is
1034created in the repository; it exists only in memory until associated with a
1035{{commit}} or {{tag}}.
1036
1037<procedure>(signature-name signature) => string</procedure>
1038<procedure>(signature-email signature) => string</procedure>
1039
1040{{signature-name}} and {{signature-email}} return strings for the
1041given {{signature}}'s respective fields.
1042
1043<procedure>(signature-time signature) => int</procedure>
1044<procedure>(signature-time-offset signature) => int</procedure>
1045
1046{{signature-time}} and {{signature-time-offset}} return the timestamp of the
1047given {{signature}} and its UTC offset in minutes, respectively.
1048
1049==== Checkout
1050
1051<procedure>(checkout repository [object]) => void</procedure>
1052
1053{{checkout}} updates files in the working directory and index of the
1054given {{repository}} to match the state of {{object}}.
1055
1056If {{object}} is an {{index}}, the {{repository}}'s working directory
1057will be updated to match the its state.
1058
1059If {{object}} is a {{commit}}, {{tag}} or {{tree}}, the {{repository}}'s
1060working directory and index will both be updated to reflect its state.
1061
1062If {{object}} is omitted or {{#f}}, the {{repository}}'s working
1063directory and index will both be updated to match the state of the
1064repository's {{HEAD}}.
1065
1066Note that {{checkout}} will silently delete untracked files and
1067overwrite changes to tracked files in the repository's working
1068directory.
1069
1070==== Clone
1071
1072<procedure>(clone url path) => void</procedure>
1073
1074Clones the remote Git repository specified by {{url}} into the local
1075pathname {{path}}.
1076
1077On success, the branch indicated by the {{HEAD}} reference of the remote
1078repository is checked out as a normal (i.e. non-bare) Git working
1079directory.
1080
1081An error is signaled if the clone fails for any reason.
1082
1083==== Config
1084
1085<record>config</record>
1086<procedure>(config? obj) => boolean</procedure>
1087
1088A {{config}} represents a Git configuration file, associated with either a
1089repository, the current user, or the system-wide Git installation.
1090
1091<procedure>(config-path [type]) => string</procedure>
1092
1093Returns the path to a Git configuration file, if one exists. {{type}}
1094may be a symbol specifying the type of path to search, either {{user}},
1095{{system}} or {{xdg}}, to request the path to the configuration for
1096the current user, the system-wide Git installation, or the configuration
1097file path specified by the XDG standard (".config/git/config"),
1098respectively. {{type}} defaults to {{user}}. An error is signalled if
1099no configuration file is found at the requested location.
1100
1101<procedure>(config-open [source]) => config</procedure>
1102
1103Reads the Git configuration file indicated by {{source}}, which may be a
1104{{repository}}, path, or symbol as expected by {{config-path}}. An
1105error is signalled if no configuration file is found at the requested location.
1106
1107<procedure>(config-get config name [type]) => object</procedure>
1108
1109Returns the value of the property {{name}} in the given {{config}}
1110object. The value is returned as a string, unless an alternative return
1111type is specified by the given symbol {{type}}, which should be
1112{{string}}, {{symbol}}, {{number}} or {{boolean}}. An error is
1113signaled if the requested property doesn't exist, or if it cannot be
1114converted to the specified return type.
1115
1116<procedure>(config-set! config name value) => object</procedure>
1117
1118Sets the value of the property {{name}} in the given {{config}} object to the
1119given {{value}}.
1120
1121On success, the new value is written immediately to disk.
1122
1123<procedure>(config-unset! config name) => void</procedure>
1124
1125Deletes the property {{name}} from the given {{config}} object.
1126
1127On success, the change is written immediately to disk.
1128
1129=== History
1130
1131* 0.0.25 - libgit2 0.20.0 expanded diff API
1132* 0.0.24 - libgit2 0.20.0
1133* 0.0.23 - libgit2 0.19.0 object owner tracking
1134* 0.0.22 - libgit2 0.19.0 note, clone & revparse bindings
1135* 0.0.21 - libgit2 0.19.0 fix for repository-ref on 32-bit platforms
1136* 0.0.20 - libgit2 0.19.0
1137* 0.0.19 - libgit2 0.18.0 reference & branch API updates
1138* 0.0.18 - libgit2 0.18.0
1139
1140=== Author
1141
1142Evan Hanson
1143
1144=== License
1145
1146Copyright (c) 2013-2014, Evan Hanson, 3-Clause BSD License
Note: See TracBrowser for help on using the repository browser.