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

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

wiki/git: Document patch API, other minor fixes

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