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

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

Add C5 port of git egg and wiki page

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