Changeset 29271 in project


Ignore:
Timestamp:
06/28/13 10:08:05 (8 years ago)
Author:
evhan
Message:

wiki: docs for git 0.0.18

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/git

    r27051 r29271  
    99Bindings to the [[http://libgit2.github.com|libgit2]] library.
    1010
    11 This library requires libgit2 0.16.0 and Chicken 4.7 or newer.
     11This library requires libgit2 0.18.0 and Chicken 4.7 or newer.
    1212
    1313The source for this egg is available at [[http://github.com/evhan/chicken-git]].
     
    6969directory directly.
    7070
    71 <procedure>(repository-path repository [type]) => string</procedure>
    72 
    73 Returns the absolute path to the given {{repository}}. A {{type}} symbol may be
    74 given in order to retrieve alternate paths for the repository, and should be
    75 one of {{path}} (the default), {{index}}, {{odb}} or {{workdir}}.
     71<procedure>(repository-path repository) => string</procedure>
     72
     73Returns the absolute path to the given {{repository}}'s Git directory,
     74either the topmost directory in the project (if the repository is bare)
     75or the ".git" subdirectory.
     76
     77<procedure>(repository-working-directory repository) => string</procedure>
     78
     79Returns the absolute path to the given {{repository}}'s working directory,
     80or {{#f}} if the repository is bare.
    7681
    7782<procedure>(repository-ref repository ref) => object</procedure>
     
    8994directory).
    9095
    91 <procedure>(pack-references repository) => void</procedure>
    92 
    93 Writes all loose references in the given {{repository}} into its "pack-refs"
    94 file and removes them from the on-disk repository. Calling this function will
    95 invalidate any existing {{reference}} objects belonging to the repository.
     96<procedure>(repository-head-orphan? repositoy) => boolean</procedure>
     97<procedure>(repository-head-detached? repositoy) => boolean</procedure>
     98
     99Returns a boolean indicating whether the given repository's HEAD (a
     100symbolic reference) is orphaned (unreferenced under the refs namespace)
     101or detached (refering to a commit rather than a branch).
    96102
    97103==== OID
     
    117123Returns the string representation of the given {{oid}} in the form "xx/...",
    118124where "xx" is the first two characters of the SHA1 and "..." is the remainder.
     125
     126<procedure>(oid=? oid1 oid2) => boolean</procedure>
     127
     128Indicates whether the two {{oid}}s are the equivalent.
    119129
    120130==== Reference
     
    139149Returns a list of all references in the given {{repository}}.
    140150
     151<procedure>(repository-head repository) => reference</procedure>
     152
     153Returns a reference to this repository's HEAD (resolved to an OID), of
     154{{#f}} if it doesn't exist.
     155
     156<procedure>(reference-name reference) => string</procedure>
    141157<procedure>(reference-id reference) => oid</procedure>
    142158
    143 Returns the {{oid}} of the object referred to by the given {{reference}}.
    144 
    145 <procedure>(reference-owner reference) => repository</procedure>
    146 
    147 Returns the {{repository}} to which the given {{reference}} belongs.
     159Returns the name of the given {{reference}} and the {{oid}} of the
     160object referred to by the given {{reference}}, respectively.
    148161
    149162<procedure>(reference-resolve reference) => reference</procedure>
    150163
    151164Dereferences the given (possibly symbolic) {{reference}}, returning a new
    152 non-symbolic {{reference}} pointing directly to a {{commit}}.
     165non-symbolic {{reference}} pointing refering directly to an {{oid}}.
    153166
    154167<procedure>(reference-target reference) => string</procedure>
    155168
    156 Returns the name of the reference referred to by the given symbolic
    157 {{reference}}. It is an error if the given {{reference}} is not symbolic.
    158 
    159 <procedure>(reference-rename reference name) => void</procedure>
    160 <procedure>(reference-target-set reference target) => void</procedure>
    161 
    162 {{reference-rename}} changes the name of the given {{reference}} to the string
    163 {{name}}.
    164 
    165 {{reference-target-set}} updates a {{reference}} to refer to the given
     169Returns the {{oid}} or {{reference}} to which the given {{reference}}
     170refers.
     171
     172<procedure>(reference-rename reference name [force]) => reference</procedure>
     173<procedure>(reference-target-set! reference target) => void</procedure>
     174
     175{{reference-rename}} changes the name of the given {{reference}} to the
     176string {{name}} and returns the newly-updated {{reference}}. If
     177{{force}} is given and nonfalse, any previously-existing {{reference}}
     178of the given {{name}} will be overwritten.
     179
     180{{reference-target-set!}} updates a {{reference}} to refer to the given
    166181{{target}}. If {{reference}} is an immediate reference (referring to an object
    167182ID), {{target}} must be an {{oid}}, {{commit}}, or SHA1 string. If
     
    184199On success, the on-disk repository is updated immediately.
    185200
     201<procedure>(reference-for-each procedure repository) => void</procedure>
     202
     203Invokes the given unary procedure on each reference in the repository.
     204
    186205==== Branch
    187206
     
    222241<procedure>(object-id object) => oid</procedure>
    223242
    224 Returns the {{oid}} referring to the given object, which must be a {{commit}},
     243Returns the {{oid}} of the given object, which must be a {{commit}},
    225244{{tree}}, {{tag}} or {{blob*}}.
    226245
     
    236255cannot be determined.
    237256
     257<procedure>(object=? object1 object2) => boolean</procedure>
     258
     259Indicates whether the two Git objects represent the same thing (judging
     260by their respective {{oid}}s). Each object of type {{commit}}, {{tree}},
     261{{tag}} or {{blob*}}.
     262
    238263==== Blob*
    239264
     
    252277<procedure>(blob*-content blob*) => blob</procedure>
    253278
    254 Returns a {{blob}} (of the Chicken built-in type) with the contents of the given
    255 {{blob*}} (of the Git object type).
     279Returns a blob (of the CHICKEN built-in type) of the contents of the
     280given {{blob*}} (of the Git object type).
    256281
    257282<procedure>(blob*-size blob*) => int</procedure>
    258283
    259284Returns the size in bytes of the given {{blob*}}.
     285
     286<procedure>(blob*-binary? blob*) => boolean</procedure>
     287
     288Indicates whether the given {{blob*}} is (likely to be) a binary chunk
     289or not.
     290
     291<procedure>(create-blob* repository source) => blob*</procedure>
     292
     293Creates a new {{blob*}} in the given {{repository}}.
     294
     295{{source}} is the data source for the {{blob*}}, and may be a blob (of
     296the CHICKEN built-in type) or a pathname string indicating a file on the
     297local disk or, if such a file isn't present, a file relative to the
     298repository's working directory.
     299
     300On success, the on-disk repository is updated immediately.
    260301
    261302==== Commit
     
    272313is signaled if no such {{commit}} exists.
    273314
    274 <procedure>(commits-fold kons knil repository #!key [initial] [hide] [sort]) => list</procedure>
     315<procedure>(commits-fold kons knil repository #!key [initial] [hide] [sort]) => object</procedure>
    275316
    276317Folds over the given {{repository}}'s commits. If an {{initial}} {{commit}} or
     
    297338
    298339<procedure>(commit-message commit) => string</procedure>
    299 
    300 Returns the full commit message of the given {{commit}}.
     340<procedure>(commit-message-encoding commit) => string</procedure>
     341
     342Returns the full commit message or message encoding for the given
     343{{commit}}.
    301344
    302345<procedure>(commit-tree commit) => tree</procedure>
     
    317360{{commit-parentcount}} returns the number of parents for a given {{commit}}.
    318361
    319 {{commit-parent}} returns the {{n}}th parent of the given {{commit}}, or the
    320 first if no {{n}} is given. If the {{commit}} has no parent, {{#f}} is
    321 returned.
    322 
    323 <procedure>(create-commit repository #!key message tree [parents] author [committer] [reference]) => commit</procedure>
     362{{commit-parent}} returns the {{n}}th parent of the given {{commit}}, or
     363the first parent if no {{n}} is given. If the {{commit}} has no parent,
     364{{#f}} is returned.
     365
     366<procedure>(create-commit repository #!key message author [committer] [tree] [parents] [reference]) => commit</procedure>
    324367
    325368Creates & returns a new commit in the given {{repository}}. The string
    326 {{message}} will be used as the commit's message and {{tree}} will be the file
    327 tree of the commit. {{parents}} should be be a (possibly empty) list of commits
    328 to be used as this commit's parents. {{author}} and {{committer}} should be
    329 signatures; if {{committer}} is not given, {{author}} will be used for both.
    330 {{reference}}, if given and not {{#f}}, should be the {{reference}} that will
     369{{message}} will be used as the commit's message and {{tree}} will be
     370the file tree of the commit. If no {{tree}} is given, the current state
     371of the repository's {{index}} is used. {{parents}} may be be a (possibly
     372empty) list of commits to be used as this commit's ancestors. {{author}}
     373and {{committer}} should be signatures; if {{committer}} is not given,
     374{{author}} will be used for both. {{reference}}, if given and not
     375{{#f}}, should be the {{reference}} or name of a {{reference}} that will
    331376be updated to point to the newly-created commit.
    332377
     
    356401signaled if no such {{tag}} exists.
    357402
     403<procedure>(tags-fold kons knil repository) => object</procedure>
     404
     405Folds over the given repository's {{tag}}s in unspecified order.
     406
    358407<procedure>(tags repository) => list</procedure>
    359408
     
    378427Returns the {{signature}} of the {{tag}}'s creator.
    379428
     429<procedure>(tag-peel tag) => object</procedure>
     430
     431Recursively dereferences the given {{tag}} until a non-tag object to
     432which it refers is found (and returned).
     433
    380434<procedure>(tag-target tag) => object</procedure>
    381435<procedure>(tag-peel tag) => object</procedure>
     
    384438{{commit}}, {{tree}}, {{blob}} or {{tag}}.
    385439
    386 {{tag-peel}} is similar to {{tag-target}}, except that it recursively
    387 dereferences the given {{tag}} until a non-tag object is found and returned.
     440Returns the object immediately referred to by {{tag}}, which will be of
     441type {{commit}}, {{tree}}, {{blob}} or {{tag}}.
    388442
    389443<procedure>(tag-delete tag) => void</procedure>
     
    430484
    431485Returns a {{tree-entry}} object for the given {{key}} from the tree, or
    432 {{#f}} if no such tree entry is found. {{key}} may be a zero-based integer
    433 index or a pathname string.
    434 
    435 <procedure>(tree->list tree [repository]) => list</procedure>
    436 
    437 Returns a list of {{tree-entry}} objects for the given {{tree}}. If a
    438 {{repository}} is given, this function will recurse into it, returning a nested
    439 list of entries spanning the full directory tree.
     486{{#f}} if no such tree entry is found. {{key}} may be a zero-based
     487integer index or a pathname string relative to the repository's working
     488directory.
     489
     490<procedure>(tree-fold kons knil tree) => object</procedure>
     491
     492Folds over each path and {{tree-entry}} objects in the given {{tree}}.
     493
     494Note that {{kons}} should be a function of three arguments; the path to
     495the current {{tree-entry}} (a string, relative to the repository's working
     496directory), the current {{tree-entry}}, and the current state of the
     497fold.
     498
     499<procedure>(tree-entries tree) => list</procedure>
     500
     501Returns an alist of all {{tree-entry}} objects in the given {{tree}},
     502whose keys are the pathname strings indicating the {{tree-entry}}'s
     503location in the repository and whose keys are the {{tree-entry}} objects
     504themselves.
    440505
    441506<procedure>(create-tree repository index) => tree</procedure>
    442507
    443 Creates and returns a {{tree}} object from the state of the given {{index}}.
    444 
    445 <procedure>(tree-walk tree fn [mode]) => void</procedure>
    446 
    447 Invokes the given function {{fn}} on each {{tree-entry}} in the given {{tree}}.
    448 A walk order may be specified by the symbol {{mode}}, which should be one of
    449 {{'pre}} or {{'post}}.
     508Creates and returns a new {{tree}} object from the state of the given
     509{{index}} in the given {{repository}}.
     510
     511On success, the new value is written immediately to disk.
    450512
    451513==== Tree Entry
     
    510572<procedure>(tree-builder-write repo tree-builder) => tree</procedure>
    511573
    512 Writes the {{tree-builder}}'s tree to the given {{repository}}, modifying the
    513 on-disk repository on success. The resulting {{tree}} is returned.
     574Writes the {{tree-builder}}'s current state to the given {{repository}},
     575modifying the on-disk repository on success. The resulting {{tree}} is
     576returned.
    514577
    515578==== Diff
     
    517580<record>diff</record>
    518581<procedure>(diff? obj) => boolean</procedure>
     582<procedure>(diff-path diff) => string</procedure>
     583<procedure>(diff-status diff) => symbol</procedure>
     584<procedure>(diff-similarity diff) => integer</procedure>
     585<procedure>(diff-old-file diff)</procedure>
     586<procedure>(diff-new-file diff)</procedure>
    519587<record>diff-file</record>
    520588<procedure>(diff-file? obj) => boolean</procedure>
    521 
    522 A {{diff}} is the difference in a single file between two Git {{tree}}s. Each
    523 diff has a status, similarity, and a pair of {{diff-file}}s for the old and new
    524 files, respectively.
    525 
    526 Each diff-file has an {{oid}}, {{path}}, and {{mode}} (Unix file attributes).
    527 
    528 <procedure>(diff repository [tree object]) => list</procedure>
    529 
    530 Compares a tree to another object in the given {{repository}}, or compares a
    531 repository's working directory to its index if no other arguments are given.
    532 Returns a list of {{diff}} objects is for every difference between them.
    533 
    534 {{object}} may be an {{index}}, {{tree}}, or one of the symbols {{'index}} or
    535 {{'workdir}} to specify a diff target indirectly.
     589<procedure>(diff-file-id diff-file) => oid</procedure>
     590<procedure>(diff-file-path diff-file) => string</procedure>
     591<procedure>(diff-file-size diff-file) => integer</procedure>
     592<procedure>(diff-file-mode diff-file) => integer</procedure>
     593
     594A {{diff}} is the difference in a single file between two Git {{tree}}s.
     595Each diff has a path, status, similarity, and a pair of {{diff-file}}s
     596for the old and new files, respectively (retrieved by {{diff-old-file}}
     597and {{diff-new-file}}).
     598
     599Each {{diff-file}} has an {{id}}, {{path}}, {{size}} and {{mode}} (Unix
     600file attributes).
    536601
    537602<procedure>(diff-status diff) => symbol</procedure>
    538603
    539604Returns a symbol representing the status of a {{diff}}, which will be
    540 one of the following symbols:
     605one of the following symbols, or a list of them if the {{diff}}'s file
     606is in multiple statuses:
    541607
    542608    modified
     
    562628returned for the diff's old or new file, respectively.
    563629
    564 <procedure>(diff-file-path diff-file) => string</procedure>
    565 
    566 Returns the path of the given {{diff-file}}, relative to the repository's root.
    567 In the case of a rename, the paths of the old and new {{diff-file}} for a given
    568 {{diff}} may be different.
    569 
    570 <procedure>(diff-file-id diff-file) => oid</procedure>
    571 
    572 Returns the {{oid}} of the given {{diff-file}}.
    573 
    574 <procedure>(diff-file-mode diff-file) => int</procedure>
    575 
    576 Returns the Unix file attributes of the given {{diff-file}}.
    577 
    578 <procedure>(diff-old-id diff) => oid</procedure>
    579 <procedure>(diff-new-id diff) => oid</procedure>
    580 <procedure>(diff-old-mode diff) => int</procedure>
    581 <procedure>(diff-new-mode diff) => int</procedure>
    582 <procedure>(diff-old-path diff) => string</procedure>
    583 <procedure>(diff-new-path diff) => string</procedure>
    584 
    585 Convenience procedures for accessing the fields of a {{diff}} objects's old &
    586 new {{diff-file}}s.
    587 
    588     (diff-old-id diff) => (diff-file-id (diff-old-file diff))
     630<procedure>(diff repository [object1 [object2]]) => list</procedure>
     631
     632Returns a list of {{diff}} objects.
     633
     634{{diff}}'s behavior is as follows, given the following arguments:
     635
     636* {{()}}: diff the repository's index to its working directory
     637* {{(index)}}: diff the given index to the repository's working directory
     638* {{(tree)}}: diff the given tree to the repository's working directory
     639* {{(tree tree)}}: diff the given trees
     640* {{(tree index)}}: diff the given tree to the given index
    589641
    590642==== Status
     
    595647{{repository}}.
    596648
    597 This status will be one of the following symbols:
     649This status will be one of the following symbols, or a list of them if
     650the file is in multiple statuses:
    598651
    599652    current
     
    606659    ignored
    607660
    608 Currently, if a file is of two statuses (for example, partially-staged, so it
    609 is both {{index/modified}} and {{worktree/modified}}) this function will return
    610 the empty list.
     661<procedure>(file-statuses-fold kons knil repository) => object</procedure>
     662
     663Folds over each path and corresponding file status in the given
     664{{repository}}'s working directory.
     665
     666Note that {{kons}} should be a function of three arguments; the pathname
     667of the current file (a string, relative to the repository's working
     668directory), the current status symbol, and the current state of the
     669fold.
     670
     671<procedure>(file-statuses repository) => list</procedure>
     672
     673Returns an alist all file statuses in the given {{repository}}, whose
     674keys are the pathnames of the file  in the repository and whose keys are
     675the status symbols of the files.
    611676
    612677<procedure>(file-ignored? repository path) => boolean</procedure>
     
    632697
    633698<procedure>(index-entrycount index) => int</procedure>
    634 <procedure>(index-entrycount-unmerged index) => int</procedure>
    635 
    636 Returns the total number of index entries and unmerged index entries of the
    637 given {{index}}, respectively. This is essentially a count of all files tracked
    638 by Git in a given repository.
     699
     700Returns the total number of index entries entries of the given
     701{{index}}, respectively. This is essentially a count of all files
     702tracked by Git in a given repository.
    639703
    640704<procedure>(index-read index) => void</procedure>
     
    645709<procedure>(index-write index) => void</procedure>
    646710
    647 Writes the state of the given {{index}} from memory onto disk, modifying the
    648 repository on success.
     711Writes the state of the given {{index}} from memory onto disk, modifying
     712the repository on success.
    649713
    650714<procedure>(index-clear index) => void</procedure>
     
    674738exists. If a type symbol is given, either {{merged}} (the default behavior) or
    675739{{unmerged}}, the search will be limited to such entries.
    676 
    677 <procedure>(index->list index [type]) => list</procedure>
    678 
    679 Returns a list of all {{index-entry}} objects in the given {{index}}. If a type
    680 symbol is given, either {{merged}} (the default behavior) or {{unmerged}}, the
    681 returned list will be limited to such entries.
    682740
    683741==== Index Entry
     
    849907=== History
    850908
     909* 0.0.18 - libgit2 0.18.0
     910* 0.0.17 - libgit2 0.17.0 small test fix
     911* 0.0.16 - libgit2 0.17.0 follow libgit2's diff & branch apis, improve C callback safety
    851912* 0.0.15 - libgit2 0.17.0 bindings & diff api changes
    852913* 0.0.14 - libgit2 0.17.0 compatibility
     
    859920=== License
    860921
    861 Copyright (c) 2012, Evan Hanson, 3-Clause BSD License
     922Copyright (c) 2013, Evan Hanson, 3-Clause BSD License
     923
     924
Note: See TracChangeset for help on using the changeset viewer.