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

Last change on this file since 25714 was 25714, checked in by evhan, 9 years ago

wiki/git create-repository docs

File size: 25.4 KB
Line 
1[[tags: egg]]
2
3== git
4
5[[toc:]]
6
7=== Description
8
9Bindings to the [[http://libgit2.github.com|libgit2]] library.
10
11This library has been written and tested against Chicken 4.6 & 4.7 and libgit2
120.15.0. If you encounter problems, check your versions.
13
14The source for this egg is available at [[http://github.com/evhan/chicken-git]].
15
16=== Documentation
17
18{{git}} provides an interface for reading & manipulating git repositories.
19The library is split into two modules, {{git}} and {{git-lolevel}}:
20
21* {{git-lolevel}} is essentially just the libgit2 API, thinly wrapped. Most of
22  the function signatures remain the same, with a few exceptions:
23
24** Structures & pointers that would go on the stack are allocated
25automatically.
26
27** Return values are checked where appropriate, signaling an exception of type
28{{git}} when negative.
29
30** Pointer arrays are converted to rest arguments.
31
32* {{git}} is a higher-level interface around {{git-lolevel}}, providing
33  record types for each libgit2 structure.
34
35The following documentation applies to the {{git}} module.
36
37=== Usage
38
39  (use git) ; or...
40  (use git-lolevel)
41
42It's not recommended to mix the two without prefixing one or the other's
43imports, as the two libraries share many identifiers.
44
45=== API
46
47==== Repository
48
49<record>repository</record>
50<procedure>(repository? obj) => boolean</procedure>
51
52A {{repository}} corresponds to an on-disk Git repository.
53
54<procedure>(create-repository [path] [bare]) => repository</procedure>
55
56Creates & returns a new repository at the given {{path}}, or the value of
57{{current-directory}} if no path is given. If {{bare}} is given and not {{#f}},
58the repository will be created without a working directory. An error is
59signaled if the path is invalid or the repository cannot be created.
60
61<procedure>(repository-open [path]) => repository</procedure>
62
63Opens the Git repository indicated by {{path}}, or the value of
64{{current-directory}} if no {{path}} is given. {{path}} may point to a bare
65repository, a working directory containing a ".git" directory, or a ".git"
66directory directly.
67
68<procedure>(repository-path repository [type]) => string</procedure>
69
70Returns the absolute path to the given {{repository}}. A {{type}} symbol may be
71given in order to retrieve alternate paths for the repository, and should be
72one of {{path}} (the default), {{index}}, {{odb}} or {{workdir}}.
73
74<procedure>(repository-ref repository ref) => object</procedure>
75
76Looks up a Git object in the given {{repository}}. {{ref}} may be a SHA1 string,
77{{oid}}, {{reference}}, {{blob*}}, {{commit}}, {{tag}} or {{tree}}. The returned
78object will be of type {{blob*}}, {{commit}}, {{tag}} or {{tree}}, or {{#f}} if
79no object matching the given {{ref}} is found.
80
81<procedure>(repository-empty? repository) => boolean</procedure>
82<procedure>(repository-bare? repositoy) => boolean</procedure>
83
84Returns a boolean indicating whether the given {{repository}} is empty
85(contains no commits) or bare (an exposed git directory without a working
86directory).
87
88<procedure>(pack-references repository) => void</procedure>
89
90Writes all loose references in the given {{repository}} into its "pack-refs"
91file and removes them from the on-disk repository. Calling this function will
92invalidate any existing {{reference}} objects belonging to the repository.
93
94==== OID
95
96<record>oid</record>
97<procedure>(oid? obj) => boolean</procedure>
98
99An {{oid}} is a unique reference to a Git object, corresponding to a
10040-character SHA1 object name.
101
102<procedure>(string->oid string) => oid</procedure>
103
104Creates an {{oid}} from the given string, which should be a 40-character SHA1
105hash. An error is signaled if the string is not a valid hash.
106
107<procedure>(oid->string oid [length]) => string</procedure>
108
109Returns the string representation of the given {{oid}}. The optional integer
110{{length}} specifies the length of the returned string, up to 40 characters.
111
112<procedure>(oid->path oid) => string</procedure>
113
114Returns the string representation of the given {{oid}} in the form "xx/...",
115where "xx" is the first two characters of the SHA1 and "..." is the remainder.
116
117==== Reference
118
119<record>reference</record>
120<procedure>(reference? obj) => boolean</procedure>
121
122A {{reference}} is a direct or indirect pointer to a Git commit object. A
123repository's {{"HEAD"}} is a common example: it is a symbolic reference,
124referring to the immediate reference {{"refs/heads/master"}}, which in turn
125points at a {{commit}}.
126
127<procedure>(reference repository ref) => reference</procedure>
128
129Returns the {{reference}} specified by the given string {{ref}} from the
130{{repository}}. {{ref}} must be a string referring to a valid reference, such
131as {{"HEAD"}}, {{"ref/heads/master"}}, or {{"refs/tags/v0.1.0"}}. An error is
132signalled if the reference doesn't exists.
133
134<procedure>(references repository) => list</procedure>
135
136Returns a list of all references in the given {{repository}}.
137
138<procedure>(reference-id reference) => oid</procedure>
139
140Returns the {{oid}} of the object referred to by the given {{reference}}.
141
142<procedure>(reference-owner reference) => repository</procedure>
143
144Returns the {{repository}} to which the given {{reference}} belongs.
145
146<procedure>(reference-resolve reference) => reference</procedure>
147
148Dereferences the given (possibly symbolic) {{reference}}, returning a new
149non-symbolic {{reference}} pointing directly to a {{commit}}.
150
151<procedure>(reference-target reference) => string</procedure>
152
153Returns the name of the reference referred to by the given symbolic
154{{reference}}. It is an error if the given {{reference}} is not symbolic.
155
156<procedure>(reference-rename reference name) => void</procedure>
157<procedure>(reference-target-set reference target) => void</procedure>
158
159{{reference-rename}} changes the name of the given {{reference}} to the string
160{{name}}.
161
162{{reference-target-set}} updates a {{reference}} to refer to the given
163{{target}}. If {{reference}} is an immediate reference (referring to an object
164ID), {{target}} must be an {{oid}}, {{commit}}, or SHA1 string. If
165{{reference}} is symbolic, {{target}} must be a {{reference}} or reference
166name. It is an error to assign a symbolic reference an OID target and
167vice-versa.
168
169On success, the on-disk repository is updated immediately.
170
171<procedure>(create-reference repository #!key name target [symbolic] [force]) => reference</procedure>
172
173Creates & returns a new reference in the given {{repository}} for the specified
174{{name}} and {{target}}. If {{symbolic}} is given and not {{#f}}, the created
175reference will be so, and {{target}} must be a reference name or {{reference}}.
176Otherwise, {{target}} must be a SHA1 string, {{oid}}, {{commit}} or
177{{reference}} to a {{commit}}. If a reference of the given {{name}} exists and
178{{force}} is not given or {{#f}}, an error is signalled. Otherwise, creation
179is forced and the old reference will be overwritten.
180
181On success, the on-disk repository is updated immediately.
182
183==== Generic
184
185<procedure>(object-id object) => oid</procedure>
186
187Returns the {{oid}} referring to the given object, which must be a {{commit}},
188{{tree}}, {{tag}} or {{blob*}}.
189
190<procedure>(object-sha object [length]) => string</procedure>
191
192Returns the SHA1 identifier corresponding to the given object, which may be a
193{{commit}}, {{tree}}, {{tag}} {{blob*}}, {{reference}}, {{oid}} or {{string}}.
194
195<procedure>(object-type object) => symbol</procedure>
196
197Returns a symbol specifying the type of the given object, which must be one of
198{{commit}}, {{tree}}, {{tag}} or {{blob*}}. {{#f}} is returned if the type
199cannot be determined.
200
201==== Blob*
202
203<record>blob*</record>
204<procedure>(blob*? obj) => boolean</procedure>
205
206A {{blob*}} corresponds to Git's Blob object type, renamed in order to avoid
207name clashes with Chicken's built-in {{blob}} type. It represents a file.
208
209<procedure>(blob* repository ref) => blob*</procedure>
210
211Returns the {{blob*}} specified by the given {{ref}} from the repository.
212{{ref}} may be a SHA1 string, {{oid}}, or {{blob*}}. An error is signaled if
213no such {{blob*}} exists.
214
215<procedure>(blob*-content blob*) => blob</procedure>
216
217Returns a {{blob}} (of the Chicken built-in type) with the contents of the given
218{{blob*}} (of the Git object type).
219
220<procedure>(blob*-size blob*) => int</procedure>
221
222Returns the size in bytes of the given {{blob*}}.
223
224==== Commit
225
226<record>commit</record>
227<procedure>(commit? obj) => boolean</procedure>
228
229A {{commit}} corresponds to Git's commit object type.
230
231<procedure>(commit repository ref) => commit</procedure>
232
233Returns the {{commit}} specified by the given {{ref}} from the repository.
234{{ref}} may be a SHA1 string, {{oid}}, {{reference}} or {{commit}}. An error
235is signaled if no such {{commit}} exists.
236
237<procedure>(commits repository #!key [initial] [hide] [sort]) => list</procedure>
238
239Returns a list of all {{commit}}s in the given {{repository}}. If a {{commit}}
240or SHA1 {{initial}} is given,
241
242<procedure>(commit-id commit) => oid</procedure>
243
244Returns the {{oid}} for the given {{commit}}.
245
246<procedure>(commit-time commit) => int</procedure>
247<procedure>(commit-time-offset commit) => int</procedure>
248
249{{commit-time}} and {{commit-time-offset}} return the timestamp of the given
250{{commit}} and its UTC offset in minutes, respectively.
251
252<procedure>(commit-message commit) => string</procedure>
253
254Returns the full commit message of the given {{commit}}.
255
256<procedure>(commit-tree commit) => tree</procedure>
257
258Returns the {{tree}} associated with the given {{commit}}.
259
260<procedure>(commit-author commit) => signature</procedure>
261<procedure>(commit-committer commit) => signature</procedure>
262
263{{commit-author}} and {{commit-committer}} return the given {{commit}}'s
264respective {{signature}}s.
265
266<procedure>(commit-parentcount commit) => int</procedure>
267<procedure>(commit-parent commit [n]) => commit</procedure>
268
269{{commit-parentcount}} returns the number of parents for a given {{commit}}.
270
271{{commit-parent}} returns the {{n}}th parent of the given {{commit}}, or the
272first if no {{n}} is given.
273
274<procedure>(create-commit repository #!key message tree [parents] author [committer] [reference]) => commit</procedure>
275
276Creates & returns a new commit in the given {{repository}}. The string
277{{message}} will be used as the commit's message and {{tree}} will be the file
278tree of the commit. {{parents}} should be be a (possibly empty) list of commits
279to be used as this commit's parents. {{author}} and {{committer}} should be
280signatures; if {{committer}} is not given, {{author}} will be used for both.
281{{reference}}, if given and not {{#f}}, should be the {{reference}} that will
282be updated to point to the newly-created commit.
283
284Note that if no {{reference}} is given, the commit will be created in Git's
285database but will not be reflected in any of the repository's branches. To
286update the the working branch with the new commit, for example, use "HEAD".
287
288On success, the on-disk repository is updated immediately.
289
290==== Tag
291
292<record>tag</record>
293<procedure>(tag? obj) => boolean</procedure>
294
295A {{tag}} corresponds to Git's Tag object type, which is a way to mark a
296specific object as special in some way.
297
298<procedure>(tag repository ref) => tag</procedure>
299
300Creates & returns the {{tag}} specified by the given {{ref}} from the
301repository. {{ref}} may be a SHA1 string, {{oid}}, or {{tag}}. An error is
302signaled if no such {{tag}} exists.
303
304<procedure>(tags repository) => list</procedure>
305
306Returns a list of all tags in the given {{repository}}.
307
308<procedure>(tag-id tag) => oid</procedure>
309
310Returns the {{oid}} for the given {{tag}}.
311
312<procedure>(tag-type tag) => symbol</procedure>
313
314Returns the object type symbol of the target of the given {{tag}}, which will
315be one of {{commit}}, {{tree}}, {{blob}}, or {{tag}}.
316
317<procedure>(tag-name tag) => string</procedure>
318<procedure>(tag-message tag) => string</procedure>
319
320Return the name or message of the given {{tag}}.
321
322<procedure>(tag-tagger tag) => signature</procedure>
323
324Returns the {{signature}} of the {{tag}}'s creator.
325
326<procedure>(tag-target tag) => object</procedure>
327
328Returns the object referred to by {{tag}}, which will be of type {{commit}},
329{{tree}}, {{blob}} or {{tag}}.
330
331<procedure>(tag-delete tag) => void</procedure>
332
333Destroys the given {{tag}}.
334
335On success, the on-disk repository is updated immediately.
336
337<procedure>(create-tag repository #!key target name message tagger [force]) => tag</procedure>
338
339Creates & returns a new tag in the given {{repository}} for the specified
340{{name}}, {{message}} and {{target}}. {{name}} and {{message}} must be strings,
341{{tagger}} must be a {{signature}},and {{target}} must be a {{commit}},
342{{tree}} or {{blob*}}. If a tag of the given {{name}} exists and {{force}} is
343not given or {{#f}}, an error is signalled.  Otherwise, creation is forced and
344the old tag will be overwritten.
345
346On success, the on-disk repository is updated immediately.
347
348==== Tree
349
350<record>tree</record>
351<procedure>(tree? obj) => boolean</procedure>
352
353A {{tree}} corresponds to Git's Tree object type, which represents a directory
354tree.
355
356<procedure>(tree repository ref) => tree</procedure>
357
358Returns the {{tree}} specified by the given {{ref}} from the repository. {{ref}}
359may be a SHA1 string, {{oid}}, or {{tree}}. An error is signaled if no such
360{{tree}} exists.
361
362<procedure>(tree-id tree) => oid</procedure>
363
364Returns the {{oid}} for the given {{tree}}.
365
366<procedure>(tree-entrycount tree) => int</procedure>
367
368Returns the number of entries in the given {{tree}}. This count does not
369include entries of contained directories.
370
371<procedure>(tree-ref tree key) => tree-entry</procedure>
372
373Returns a {{tree-entry}} object for the given {{key}}, or {{#f}} if no such
374object is found. {{key}} may be a zero-based integer index or the full string
375pathname of an entry name.
376
377<procedure>(tree->list tree [repository]) => list</procedure>
378
379Returns a list of {{tree-entry}} objects for the given {{tree}}. If a
380{{repository}} is given, this function will recurse into it, returning a nested
381list of entries spanning the full directory tree.
382
383<procedure>(create-tree repository index) => tree</procedure>
384
385Creates and returns a {{tree}} object from the state of the given {{index}}.
386
387==== Tree Entry
388
389<record>tree-entry</record>
390<procedure>(tree-entry? obj) => boolean</procedure>
391
392A {{tree-entry}} represents a single node in a {{tree}} object.
393
394<procedure>(tree-entry-id tree-entry) => oid</procedure>
395
396Returns the {{oid}} of the given {{tree-entry}}.
397
398<procedure>(tree-entry-name tree-entry) => string</procedure>
399
400Returns the name of the given {{tree-entry}}.
401
402<procedure>(tree-entry-attributes tree-entry) => int</procedure>
403
404Returns the Unix file attributes of the given {{tree-entry}}.
405
406<procedure>(tree-entry-type tree-entry) => symbol</procedure>
407
408Returns the object type symbol, either {{tree}} or {{blob}}, of the given
409{{tree-entry}}.
410
411<procedure>(tree-entry->object repository tree-entry) => object</procedure>
412
413Returns an object of type {{tree}} or {{blob*}} from the given {{tree-entry}}
414and {{repository}}, which must be the owner of the {{tree-entry}}.
415
416==== Tree Builder
417
418<record>tree-builder</record>
419<procedure>(tree-builder? obj) => boolean</procedure>
420
421A tree builder provides a way to construct {{tree}} objects in memory and write
422them to a repository, without using an index as an intermediary.
423
424<procedure>(make-tree-builder [tree]) => tree-builder</procedure>
425
426Creates a new {{tree-builder}}. If a {{tree}} is given, it is used as the
427constructed tree's initial state. Otherwise, it must be populated manually
428using {{tree-builder-insert}}.
429
430<procedure>(tree-builder-insert tree-builder object path attributes) => tree-entry</procedure>
431
432Inserts {{object}} into the {{tree-builder}}'s tree at the given {{path}},
433which should be a pathname to a file relative to the repository's root. The
434inserted object must be a {{tree}} or {{blob*}}, and will have the given
435{{attributes}} (an integer file mode).
436
437<procedure>(tree-builder-ref tree-builder path) => tree-entry</procedure>
438
439Returns the {{tree-entry}} from the given {{tree-builder}} at {{path}}, which
440should be a pathname to a file relative to the repository's root. If the
441requested file doesn't exist, {{#f}} is returned.
442
443<procedure>(tree-builder-remove tree-builder path) => void</procedure>
444
445Removes the object at the given {{path}} from the {{tree-builder}}'s tree.
446
447<procedure>(tree-builder-write repo tree-builder) => tree</procedure>
448
449Writes the {{tree-builder}}'s tree to the given {{repository}}, modifying the
450on-disk repository on success. The resulting {{tree}} is returned.
451
452==== Status
453
454<procedure>(file-status repository path) => symbol</procedure>
455
456Returns the status of the file specified by {{path}} in the given
457{{repository}}.
458
459This status will be one of the following symbols:
460
461    current
462    index/new
463    index/modified
464    index/deleted
465    worktree/new
466    worktree/modified
467    worktree/deleted
468    ignored
469
470Currently, if a file is of two statuses (for example, partially-staged, so it
471is both {{index/modified}} and {{worktree/modified}}) this function will return
472the empty list.
473
474==== Index
475
476<record>index</record>
477<procedure>(index? obj) => boolean</procedure>
478
479An {{index}} represents the on-disk state of Git's working tree. Changes made
480to a given {{index}} exist only in memory until written to disk using
481{{index-write}}.
482
483<procedure>(index-open repo-or-path) => index</procedure>
484
485It {{repo-or-path}} is a {{repository}}, returns the repository's index.  If it
486is a string, creates and returns the index at the given path, signaling an
487error if such an index doesn't exist. It is not possible to open the index of a
488bare repository, and doing so will result in an exception.
489
490<procedure>(index-entrycount index) => int</procedure>
491<procedure>(index-entrycount-unmerged index) => int</procedure>
492
493Returns the total number of index entries and unmerged index entries of the
494given {{index}}, respectively. This is essentially a count of all files tracked
495by Git in a given repository.
496
497<procedure>(index-read index) => void</procedure>
498
499Updates the given {{index}} to reflect the current state of the on-disk
500repository.
501
502<procedure>(index-write index) => void</procedure>
503
504Writes the state of the given {{index}} from memory onto disk, modifying the
505repository on success.
506
507<procedure>(index-clear index) => void</procedure>
508
509Removes all enries from a given {{index}}.
510
511<procedure>(index-add index path [stage]) => void</procedure>
512
513Adds a given {{path}}, which must refer to a file relative to the index's
514repository, to the {{index}}. If an integer {{stage}} is given, it will be used
515as the staging number for the changes.
516
517<procedure>(index-remove index ref) => void</procedure>
518
519Removes an entry from the given {{index}}. {{ref}} may be a file path string or
520an zero-based integer index. If no entry is removed, {{#f}} is returned.
521
522<procedure>(index-find index path) => int</procedure>
523
524Returns the zero-based integer index of the file specified by {{path}} in the
525given {{index}}, signaling an error if it doesn't exist.
526
527<procedure>(index-ref index key [type]) => index-entry</procedure>
528
529Returns the {{index-entry}} from the {{index}} for the given {{key}}, which may
530be an zero-based integer index or a pathname string, or {{#f}} if no such entry
531exists. If a type symbol is given, either {{merged}} (the default behavior) or
532{{unmerged}}, the search will be limited to such entries.
533
534<procedure>(index->list index [type]) => list</procedure>
535
536Returns a list of all {{index-entry}} objects in the given {{index}}. If a type
537symbol is given, either {{merged}} (the default behavior) or {{unmerged}}, the
538returned list will be limited to such entries.
539
540==== Index Entry
541
542<record>index-entry</record>
543<procedure>(index-entry? obj) => boolean</procedure>
544
545An {{index-entry}} represents a tracked file in Git's working directory,
546belonging to an {{index}}.
547
548<procedure>(index-entry-id index-entry) => oid</procedure>
549
550Returns the {{oid}} referring to the given {{index-entry}}.
551
552<procedure>(index-entry-path index-entry) => string</procedure>
553
554Returns the file path of the given {{index-entry}} relative to the owning
555repository's working directory.
556
557<procedure>(index-entry-ctime index-entry) => int</procedure>
558<procedure>(index-entry-mtime index-entry) => int</procedure>
559<procedure>(index-entry-dev index-entry) => int</procedure>
560<procedure>(index-entry-ino index-entry) => int</procedure>
561<procedure>(index-entry-size index-entry) => int</procedure>
562<procedure>(index-entry-stage index-entry) => int</procedure>
563<procedure>(index-entry-uid index-entry) => int</procedure>
564<procedure>(index-entry-gid index-entry) => int</procedure>
565<procedure>(index-entry-mode index-entry) => int</procedure>
566<procedure>(index-entry-flags index-entry) => int</procedure>
567<procedure>(index-entry-extended index-entry) => int</procedure>
568
569These methods return the file attributes for the given {{index-entry}} as it
570exists in its in-memory {{index}}.
571
572==== ODB
573
574<record>odb</record>
575<procedure>(odb? obj) => boolean</procedure>
576
577An {{odb}} offers a direct interface to Git's internal object database.
578
579<procedure>(odb-open repo-or-path) => odb</procedure>
580
581It {{repo-or-path}} is a {{repository}}, returns the repository's object
582database. If it is a string, creates and returns the object database at the
583given path, signaling an error if no such database exists.
584
585<procedure>(odb-has-object? odb ref) => boolean</procedure>
586
587Determines if the given {{odb}} contains the given object {{ref}}, which should
588be a SHA1 string, {{oid}} or Git object of type {{commit}}, {{blob*}}, {{tree}}
589or {{tag}}.
590
591<procedure>(odb-read odb ref) => odb-object</procedure>
592
593Reads the given object {{ref}} from the database, signaling an error if it
594doesn't exist. {{ref}} should be a SHA1 string, {{oid}} or Git object of type
595{{commit}}, {{blob*}}, {{tree}} or {{tag}}.
596
597<procedure>(odb-write odb data [type]) => oid</procedure>
598
599Writes a given data {{blob}} to the {{odb}}, returning an {{oid}} referring to
600the newly-created object. The type of the stored data can be specified by an
601optional {{type}} symbol, which defaults to {{blob}}.
602
603<procedure>(odb-hash odb data [type]) => oid</procedure>
604
605Returns an {{oid}} reference for the given data {{blob}} as though it had been
606stored to the given {{odb}} but without writing it to disk. The type of the
607hashed data can be specified by an optional {{type}} symbol, which defaults to
608{{blob}}.
609
610==== ODB Object
611
612<record>odb-object</record>
613<procedure>(odb-object? obj) => boolean</procedure>
614
615An {{odb-object}} is a reference to a blob of data in a Git object database.
616
617<procedure>(odb-object-id odb-object) => oid</procedure>
618
619Returns the {{oid}} for the given {{odb-object}}.
620
621<procedure>(odb-object-size odb-object) => int</procedure>
622
623Returns the size of the {{odb-object}}'s data in bytes.
624
625<procedure>(odb-object-type odb-object) => symbol</procedure>
626
627Returns the object type symbol of the given {{odb-object}}.
628
629<procedure>(odb-object-data odb-object) => blob</procedure>
630
631Returns a blob consisting of the {{odb-object}}'s data.
632
633==== Signature
634
635<record>signature</record>
636<procedure>(signature? obj) => boolean</procedure>
637
638A signature is a record of the name, email, time and UTC offset of a given Git
639object.
640
641<procedure>(make-signature name email [time [offset]]) => signature</procedure>
642
643Returns a new {{signature}} for the given name and email strings. If a
644timestamp {{time}} and integer {{offset}} are given, they will be used as the
645signature time; otherwise, the current time will be used.
646
647Unlike the {{create-*}} functions, no representation of this signature is
648created in the repository; it exists only in memory until associated with a
649{{commit}} or {{tag}}.
650
651<procedure>(signature-name signature) => string</procedure>
652<procedure>(signature-email signature) => string</procedure>
653
654{{signature-name}} and {{signature-email}} return strings for the
655given {{signature}}'s respective fields.
656
657<procedure>(signature-time signature) => int</procedure>
658<procedure>(signature-time-offset signature) => int</procedure>
659
660{{signature-time}} and {{signature-time-offset}} return the timestamp of the
661given {{signature}} and its UTC offset in minutes, respectively.
662
663==== Config
664
665<record>config</record>
666<procedure>(config? obj) => boolean</procedure>
667
668A {{config}} represents a Git configuration file, associated with either a
669repository, the current user, or the system-wide Git installation.
670
671<procedure>(config-path [type]) => string</procedure>
672
673Returns the path to a Git configuration file. {{type}} may be a symbol, either
674{{user}} or {{system}}, to request the path to the configuration for either the
675current user or the system-wide Git installation, respectively. {{type}}
676defaults to {{user}}. An error is signalled if no configuration file is found
677at the requested location.
678
679<procedure>(config-open [source]) => config</procedure>
680
681Reads the Git configuration file indicated by {{source}}, which may be a
682{{repository}}, path, or symbol as expected by {{config-path}}. An
683error is signalled if no configuration file is found at the requested location.
684
685<procedure>(config-get config name [type]) => object</procedure>
686
687Returns the value of the property {{name}} in the given {{config}} object. The
688value is returned as a string, unless an alternative return type is specified
689by the given symbol {{type}}, which should be {{string}}, {{symbol}}, or
690{{number}}. An error is signaled if the requested property doesn't exist, or if
691it cannot be converted to the specified return type.
692
693<procedure>(config-set config name value) => object</procedure>
694
695Sets the value of the property {{name}} in the given {{config}} object to the
696given {{value}}.
697
698On success, the new value is written immediately to disk.
699
700<procedure>(config-unset config name) => void</procedure>
701
702Deletes the property {{name}} from the given {{config}} object.
703
704On success, the change is written immediately to disk.
705
706=== Author
707
708Evan Hanson
709
710=== License
711
712Copyright (c) 2011, Evan Hanson, 3-Clause BSD License
Note: See TracBrowser for help on using the repository browser.