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

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

git: create-repository, fix incorrect treebuilder docs

File size: 25.3 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 a filename string.
375
376<procedure>(tree->list tree [repository]) => list</procedure>
377
378Returns a list of {{tree-entry}} objects for the given {{tree}}. If a
379{{repository}} is given, this function will recurse into it, returning a nested
380list of entries spanning the full directory tree.
381
382<procedure>(create-tree repository index) => tree</procedure>
383
384Creates and returns a {{tree}} object from the state of the given {{index}}.
385
386==== Tree Entry
387
388<record>tree-entry</record>
389<procedure>(tree-entry? obj) => boolean</procedure>
390
391A {{tree-entry}} represents a single node in a {{tree}} object.
392
393<procedure>(tree-entry-id tree-entry) => oid</procedure>
394
395Returns the {{oid}} of the given {{tree-entry}}.
396
397<procedure>(tree-entry-name tree-entry) => string</procedure>
398
399Returns the name of the given {{tree-entry}}.
400
401<procedure>(tree-entry-attributes tree-entry) => int</procedure>
402
403Returns the Unix file attributes of the given {{tree-entry}}.
404
405<procedure>(tree-entry-type tree-entry) => symbol</procedure>
406
407Returns the object type symbol, either {{tree}} or {{blob}}, of the given
408{{tree-entry}}.
409
410<procedure>(tree-entry->object repository tree-entry) => object</procedure>
411
412Returns an object of type {{tree}} or {{blob*}} from the given {{tree-entry}}
413and {{repository}}, which must be the owner of the {{tree-entry}}.
414
415==== Tree Builder
416
417<record>tree-builder</record>
418<procedure>(tree-builder? obj) => boolean</procedure>
419
420A tree builder provides a way to construct {{tree}} objects in memory and write
421them to a repository, without using an index as an intermediary.
422
423<procedure>(make-tree-builder [tree]) => tree-builder</procedure>
424
425Creates a new {{tree-builder}}. If a {{tree}} is given, it is used as the
426constructed tree's initial state. Otherwise, it must be populated manually
427using {{tree-builder-insert}}.
428
429<procedure>(tree-builder-insert tree-builder object name attributes) => tree-entry</procedure>
430
431Inserts {{object}} into the {{tree-builder}}'s tree under the given filename
432{{name}}. The inserted object must be a {{tree}} or {{blob*}}, and will have
433the given {{attributes}} (an integer file mode).
434
435<procedure>(tree-builder-ref tree-builder path) => tree-entry</procedure>
436
437Returns the {{tree-entry}} from the given {{tree-builder}} at {{path}}, which
438should be a filename string. If the requested file doesn't exist, {{#f}} is
439returned.
440
441<procedure>(tree-builder-remove tree-builder path) => void</procedure>
442
443Removes the object at the given {{path}} from the {{tree-builder}}'s tree.
444
445<procedure>(tree-builder-write repo tree-builder) => tree</procedure>
446
447Writes the {{tree-builder}}'s tree to the given {{repository}}, modifying the
448on-disk repository on success. The resulting {{tree}} is returned.
449
450==== Status
451
452<procedure>(file-status repository path) => symbol</procedure>
453
454Returns the status of the file specified by {{path}} in the given
455{{repository}}.
456
457This status will be one of the following symbols:
458
459    current
460    index/new
461    index/modified
462    index/deleted
463    worktree/new
464    worktree/modified
465    worktree/deleted
466    ignored
467
468Currently, if a file is of two statuses (for example, partially-staged, so it
469is both {{index/modified}} and {{worktree/modified}}) this function will return
470the empty list.
471
472==== Index
473
474<record>index</record>
475<procedure>(index? obj) => boolean</procedure>
476
477An {{index}} represents the on-disk state of Git's working tree. Changes made
478to a given {{index}} exist only in memory until written to disk using
479{{index-write}}.
480
481<procedure>(index-open repo-or-path) => index</procedure>
482
483It {{repo-or-path}} is a {{repository}}, returns the repository's index.  If it
484is a string, creates and returns the index at the given path, signaling an
485error if such an index doesn't exist. It is not possible to open the index of a
486bare repository, and doing so will result in an exception.
487
488<procedure>(index-entrycount index) => int</procedure>
489<procedure>(index-entrycount-unmerged index) => int</procedure>
490
491Returns the total number of index entries and unmerged index entries of the
492given {{index}}, respectively. This is essentially a count of all files tracked
493by Git in a given repository.
494
495<procedure>(index-read index) => void</procedure>
496
497Updates the given {{index}} to reflect the current state of the on-disk
498repository.
499
500<procedure>(index-write index) => void</procedure>
501
502Writes the state of the given {{index}} from memory onto disk, modifying the
503repository on success.
504
505<procedure>(index-clear index) => void</procedure>
506
507Removes all enries from a given {{index}}.
508
509<procedure>(index-add index path [stage]) => void</procedure>
510
511Adds a given {{path}}, which must refer to a file relative to the index's
512repository, to the {{index}}. If an integer {{stage}} is given, it will be used
513as the staging number for the changes.
514
515<procedure>(index-remove index ref) => void</procedure>
516
517Removes an entry from the given {{index}}. {{ref}} may be a file path string or
518an zero-based integer index. If no entry is removed, {{#f}} is returned.
519
520<procedure>(index-find index path) => int</procedure>
521
522Returns the zero-based integer index of the file specified by {{path}} in the
523given {{index}}, signaling an error if it doesn't exist.
524
525<procedure>(index-ref index key [type]) => index-entry</procedure>
526
527Returns the {{index-entry}} from the {{index}} for the given {{key}}, which may
528be an zero-based integer index or a pathname string, or {{#f}} if no such entry
529exists. If a type symbol is given, either {{merged}} (the default behavior) or
530{{unmerged}}, the search will be limited to such entries.
531
532<procedure>(index->list index [type]) => list</procedure>
533
534Returns a list of all {{index-entry}} objects in the given {{index}}. If a type
535symbol is given, either {{merged}} (the default behavior) or {{unmerged}}, the
536returned list will be limited to such entries.
537
538==== Index Entry
539
540<record>index-entry</record>
541<procedure>(index-entry? obj) => boolean</procedure>
542
543An {{index-entry}} represents a tracked file in Git's working directory,
544belonging to an {{index}}.
545
546<procedure>(index-entry-id index-entry) => oid</procedure>
547
548Returns the {{oid}} referring to the given {{index-entry}}.
549
550<procedure>(index-entry-path index-entry) => string</procedure>
551
552Returns the file path of the given {{index-entry}} relative to the owning
553repository's working directory.
554
555<procedure>(index-entry-ctime index-entry) => int</procedure>
556<procedure>(index-entry-mtime index-entry) => int</procedure>
557<procedure>(index-entry-dev index-entry) => int</procedure>
558<procedure>(index-entry-ino index-entry) => int</procedure>
559<procedure>(index-entry-size index-entry) => int</procedure>
560<procedure>(index-entry-stage index-entry) => int</procedure>
561<procedure>(index-entry-uid index-entry) => int</procedure>
562<procedure>(index-entry-gid index-entry) => int</procedure>
563<procedure>(index-entry-mode index-entry) => int</procedure>
564<procedure>(index-entry-flags index-entry) => int</procedure>
565<procedure>(index-entry-extended index-entry) => int</procedure>
566
567These methods return the file attributes for the given {{index-entry}} as it
568exists in its in-memory {{index}}.
569
570==== ODB
571
572<record>odb</record>
573<procedure>(odb? obj) => boolean</procedure>
574
575An {{odb}} offers a direct interface to Git's internal object database.
576
577<procedure>(odb-open repo-or-path) => odb</procedure>
578
579It {{repo-or-path}} is a {{repository}}, returns the repository's object
580database. If it is a string, creates and returns the object database at the
581given path, signaling an error if no such database exists.
582
583<procedure>(odb-has-object? odb ref) => boolean</procedure>
584
585Determines if the given {{odb}} contains the given object {{ref}}, which should
586be a SHA1 string, {{oid}} or Git object of type {{commit}}, {{blob*}}, {{tree}}
587or {{tag}}.
588
589<procedure>(odb-read odb ref) => odb-object</procedure>
590
591Reads the given object {{ref}} from the database, signaling an error if it
592doesn't exist. {{ref}} should be a SHA1 string, {{oid}} or Git object of type
593{{commit}}, {{blob*}}, {{tree}} or {{tag}}.
594
595<procedure>(odb-write odb data [type]) => oid</procedure>
596
597Writes a given data {{blob}} to the {{odb}}, returning an {{oid}} referring to
598the newly-created object. The type of the stored data can be specified by an
599optional {{type}} symbol, which defaults to {{blob}}.
600
601<procedure>(odb-hash odb data [type]) => oid</procedure>
602
603Returns an {{oid}} reference for the given data {{blob}} as though it had been
604stored to the given {{odb}} but without writing it to disk. The type of the
605hashed data can be specified by an optional {{type}} symbol, which defaults to
606{{blob}}.
607
608==== ODB Object
609
610<record>odb-object</record>
611<procedure>(odb-object? obj) => boolean</procedure>
612
613An {{odb-object}} is a reference to a blob of data in a Git object database.
614
615<procedure>(odb-object-id odb-object) => oid</procedure>
616
617Returns the {{oid}} for the given {{odb-object}}.
618
619<procedure>(odb-object-size odb-object) => int</procedure>
620
621Returns the size of the {{odb-object}}'s data in bytes.
622
623<procedure>(odb-object-type odb-object) => symbol</procedure>
624
625Returns the object type symbol of the given {{odb-object}}.
626
627<procedure>(odb-object-data odb-object) => blob</procedure>
628
629Returns a blob consisting of the {{odb-object}}'s data.
630
631==== Signature
632
633<record>signature</record>
634<procedure>(signature? obj) => boolean</procedure>
635
636A signature is a record of the name, email, time and UTC offset of a given Git
637object.
638
639<procedure>(make-signature name email [time [offset]]) => signature</procedure>
640
641Returns a new {{signature}} for the given name and email strings. If a
642timestamp {{time}} and integer {{offset}} are given, they will be used as the
643signature time; otherwise, the current time will be used.
644
645Unlike the {{create-*}} functions, no representation of this signature is
646created in the repository; it exists only in memory until associated with a
647{{commit}} or {{tag}}.
648
649<procedure>(signature-name signature) => string</procedure>
650<procedure>(signature-email signature) => string</procedure>
651
652{{signature-name}} and {{signature-email}} return strings for the
653given {{signature}}'s respective fields.
654
655<procedure>(signature-time signature) => int</procedure>
656<procedure>(signature-time-offset signature) => int</procedure>
657
658{{signature-time}} and {{signature-time-offset}} return the timestamp of the
659given {{signature}} and its UTC offset in minutes, respectively.
660
661==== Config
662
663<record>config</record>
664<procedure>(config? obj) => boolean</procedure>
665
666A {{config}} represents a Git configuration file, associated with either a
667repository, the current user, or the system-wide Git installation.
668
669<procedure>(config-path [type]) => string</procedure>
670
671Returns the path to a Git configuration file. {{type}} may be a symbol, either
672{{user}} or {{system}}, to request the path to the configuration for either the
673current user or the system-wide Git installation, respectively. {{type}}
674defaults to {{user}}. An error is signalled if no configuration file is found
675at the requested location.
676
677<procedure>(config-open [source]) => config</procedure>
678
679Reads the Git configuration file indicated by {{source}}, which may be a
680{{repository}}, path, or symbol as expected by {{config-path}}. An
681error is signalled if no configuration file is found at the requested location.
682
683<procedure>(config-get config name [type]) => object</procedure>
684
685Returns the value of the property {{name}} in the given {{config}} object. The
686value is returned as a string, unless an alternative return type is specified
687by the given symbol {{type}}, which should be {{string}}, {{symbol}}, or
688{{number}}. An error is signaled if the requested property doesn't exist, or if
689it cannot be converted to the specified return type.
690
691<procedure>(config-set config name value) => object</procedure>
692
693Sets the value of the property {{name}} in the given {{config}} object to the
694given {{value}}.
695
696On success, the new value is written immediately to disk.
697
698<procedure>(config-unset config name) => void</procedure>
699
700Deletes the property {{name}} from the given {{config}} object.
701
702On success, the change is written immediately to disk.
703
704=== Author
705
706Evan Hanson
707
708=== License
709
710Copyright (c) 2011, Evan Hanson, 3-Clause BSD License
Note: See TracBrowser for help on using the repository browser.