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

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

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

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