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

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

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

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