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