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

Last change on this file since 36801 was 36801, checked in by evhan, 9 months ago

wiki/eggref: update docs/formatting/urls and eggref/5/{r7rs,fancypants,chicken-belt}

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