Changeset 31119 in project


Ignore:
Timestamp:
07/09/14 09:39:09 (6 years ago)
Author:
evhan
Message:

wiki/git: Document patch API, other minor fixes

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/git

    r30814 r31119  
    7171or the ".git" subdirectory.
    7272
    73 <procedure>(repository-working-directory repository) => string</procedure>
     73<procedure>(repository-working-directory repository) => (or string false)</procedure>
    7474
    7575Returns the absolute path to the given {{repository}}'s working directory,
    7676or {{#f}} if the repository is bare.
    7777
    78 <procedure>(repository-ref repository ref) => object</procedure>
     78<procedure>(repository-ref repository ref) => (or object false)</procedure>
    7979
    8080Looks up a Git object in the given {{repository}}. {{ref}} may be a SHA1 string,
     
    169169<procedure>(reference-remote? reference) => boolean</procedure>
    170170<procedure>(reference-branch? reference) => boolean</procedure>
     171<procedure>(reference-tag? reference) => boolean</procedure>
    171172
    172173These procedures return boolean values indicating whether the given
    173 reference is a remote- or branch-type reference, respectively.
    174 
    175 <procedure>(references-fold kons knil repository [type]) => object</procedure>
     174reference is a {{remote}}, {{branch}}, or {{tag}}-type reference,
     175respectively.
     176
     177<procedure>(references-fold kons knil repository [glob]) => object</procedure>
    176178
    177179Folds over the given {{repository}}'s references in unspecified order.
    178180
    179 An optional {{type}} symbol may be provided to limit the types of
    180 references returnd, and may be one of the symbols {{oid}},
    181 {{symbolic}}, or {{all}}. If no {{type}} is given, {{all}} is used.
    182 
    183 <procedure>(references repository [type]) => list</procedure>
     181An optional {{glob}} pattern string may be used to filter the references
     182returned. If given, it will be matched in "glob" style where a {{#\?}}
     183matches any letter, a {{#\*}} matches any sequence of letters, and
     184square brackets match a range of characters (such as "[0-9]" for
     185digits). If no {{glob}} is given, all references will be provided to
     186{{kons}}.
     187
     188<procedure>(references repository [type]) => (list-of reference)</procedure>
    184189
    185190Returns a list of all references in the given {{repository}}. A type
    186191symbol may be given to filter the references, as in {{references-fold}}.
    187 
    188 <procedure>(repository-head repository) => reference</procedure>
     192The order of the resulting list is unspecified.
     193
     194<procedure>(repository-head repository) => (or reference false)</procedure>
    189195
    190196Returns a reference to this repository's HEAD (resolved to an OID), of
     
    252258<procedure>(branches-fold kons knil repository [type]) => object</procedure>
    253259
    254 Folds over the given {{repository}}'s branches in unspecified order.
     260Folds over the given {{repository}}'s branches.
    255261
    256262A {{type}} symbol may be given, either {{local}}, {{remote}}, or
     
    258264{{all}} is used.
    259265
    260 <procedure>(branches repository [type]) => list</procedure>
     266<procedure>(branches repository [type]) => (list-of branch)</procedure>
    261267
    262268Returns a list {{reference}} objects for each branch in the given
    263269{{repository}}. A type symbol may be given to filter the branches, as in
    264 {{branches-fold}}.
     270{{branches-fold}}. The order of the resulting list is unspecified.
    265271
    266272<procedure>(branch-name reference) => string</procedure>
     
    300306{{commit}}, {{tree}}, {{tag}} {{blob}}, {{reference}}, {{oid}} or {{string}}.
    301307
    302 <procedure>(object-type object) => symbol</procedure>
     308<procedure>(object-type object) => (or symbol false)</procedure>
    303309
    304310Returns a symbol specifying the type of the given object, which must be
     
    372378<procedure>(commits-fold kons knil repository #!key [initial] [hide] [sort]) => object</procedure>
    373379
    374 Folds over the given {{repository}}'s commits. If an {{initial}} {{commit}} or
    375 SHA1 is given, only commits that are ancestors of that revision will be
    376 returned. If a list of revisions to {{hide}} is given, they and their ancestors
    377 will be ignored. If a {{sort}} is specified, commits will be collected in the
    378 given order; this sort order must be one of the symbols {{none}}, {{topo}},
    379 {{time}} or {{reverse}}.
    380 
    381 <procedure>(commits repository #!rest args) => list</procedure>
    382 
    383 Returns a list of the {{commit}}s in the given {{repository}}. {{args}} follows
    384 the {{#!key}} arguments specification for {{commits-fold}}.
     380Folds over the given {{repository}}'s commits. If an {{initial}}
     381{{commit}} or SHA1 is given, only commits that are ancestors of that
     382revision will be returned. If a list of revisions to {{hide}} is given,
     383they and their ancestors will be ignored. If a {{sort}} order is
     384specified, commits will be collected in the given order; this sort order
     385must be one of the symbols {{none}}, {{topo}}, {{time}} or {{reverse}},
     386or a list of such symbols.
     387
     388<procedure>(commits repository #!rest args) => (list-of commit)</procedure>
     389
     390Returns a list of the {{commit}}s in the given {{repository}}. {{args}}
     391follows the {{#!key}} arguments specification for {{commits-fold}}. The
     392order of the resulting list is opposite that of a call to
     393{{commits-fold}} with the same arguments.
    385394
    386395<procedure>(commit-id commit) => oid</procedure>
     
    413422
    414423<procedure>(commit-parentcount commit) => int</procedure>
    415 <procedure>(commit-parent commit [n]) => commit</procedure>
    416 <procedure>(commit-parents commit) => list</procedure>
    417 <procedure>(commit-ancestor commit [n]) => commit</procedure>
     424<procedure>(commit-parent commit [n]) => (or commit false)</procedure>
     425<procedure>(commit-parents commit) => (list-of commit)</procedure>
     426<procedure>(commit-ancestor commit [n]) => (or commit false)</procedure>
    418427
    419428{{commit-parentcount}} returns the number of parents of the given
     
    474483Folds over the given repository's {{tag}}s in unspecified order.
    475484
    476 <procedure>(tags repository) => list</procedure>
    477 
    478 Returns a list of all tags in the given {{repository}}.
     485<procedure>(tags repository) => (list-of tag)</procedure>
     486
     487Returns a list of all tags in the given {{repository}}. The order of
     488the resulting list is unspecified.
    479489
    480490<procedure>(tag-id tag) => oid</procedure>
     
    550560include entries of contained directories.
    551561
    552 <procedure>(tree-ref tree key) => tree-entry</procedure>
     562<procedure>(tree-ref tree key) => (or tree-entry false)</procedure>
    553563
    554564Returns a {{tree-entry}} object for the given {{key}} from the tree, or
     
    559569<procedure>(tree-fold kons knil tree) => object</procedure>
    560570
    561 Folds over each path and {{tree-entry}} objects in the given {{tree}}.
     571Folds over each path and accompanying {{tree-entry}} in the given
     572{{tree}} in unspecified order.
    562573
    563574Note that {{kons}} should be a function of three arguments; the path to
     
    566577fold.
    567578
    568 <procedure>(tree-entries tree) => list</procedure>
     579<procedure>(tree-entries tree) => (list-of (pair string tree-entry))</procedure>
    569580
    570581Returns an alist of all {{tree-entry}} objects in the given {{tree}},
    571 whose keys are the pathname strings indicating the {{tree-entry}}'s
    572 location in the repository and whose keys are the {{tree-entry}} objects
    573 themselves.
     582whose keys are pathname strings indicating each {{tree-entry}}'s
     583location in the tree and whose values are the {{tree-entry}} objects
     584themselves. The order of the resulting list is unspecified.
    574585
    575586<procedure>(create-tree repository [index]) => tree</procedure>
     
    638649the given {{attributes}} (an integer file mode).
    639650
    640 <procedure>(tree-builder-ref tree-builder path) => tree-entry</procedure>
     651<procedure>(tree-builder-ref tree-builder path) => (or tree-entry false)</procedure>
    641652
    642653Returns the {{tree-entry}} from the given {{tree-builder}} at {{path}}, which
     
    677688<procedure>(diff-fold kons knil diff) => object</procedure>
    678689
    679 Folds over the given {{diff}}'s {{diff-delta}}s in unspecified (but
    680 consistent) order.
    681 
    682 <procedure>(diffs repository [object1 [object2]]) => (list-of diff-delta)</procedure>
    683 
    684 Returns a list of {{diff-deltas}} for the {{diff}} between two objects
    685 in the given {{repository}}. This is equivalent to calling {{(diff
    686 repository object1 object2)}}, then immediately building a list from the
    687 resulting {{diff}} record with {{diff-fold}}.
     690Folds over the given {{diff}}'s {{diff-delta}}s in unspecified order.
     691
     692<procedure>(diff-deltas {{diff}}) => (list-of diff-delta)</procedure>
     693
     694Returns the list of {{diff-delta}}s for all changed files in the given
     695{{diff}}.
    688696
    689697<record>diff-delta</record>
     
    723731    untracked
    724732
    725 <procedure>(diff-old-file diff) => diff-file</procedure>
    726 <procedure>(diff-new-file diff) => diff-file</procedure>
     733<procedure>(diff-patch diff n) => patch</procedure>
     734
     735Returns a {{patch}} for the {{n}}th {{diff-delta}} in the given
     736{{diff}}.
     737
     738<procedure>(diff-patches diff) => patch</procedure>
     739
     740Returns a list of {{patch}}es for all {{diff-delta}}s in the given
     741{{diff}}.
     742
     743<procedure>(diff->string diff) => string</procedure>
     744
     745Returns a string representation of the given {{diff}} as a patch.
     746
     747This is equivalent to concatenating the string representations of each
     748{{patch}} given by {{diff-patches}}.
     749
     750<procedure>(diff-old-file diff) => (or diff-file false)</procedure>
     751<procedure>(diff-new-file diff) => (or diff-file false)</procedure>
    727752
    728753Returns the {{diff-file}} object for the old and new file of the given
     
    763788these a given {{diff-line}} corresponds to is indicated by its
    764789{{diff-line-origin}}, one of {{#\+}}, {{#\-}} or {{#\space}}.
     790
     791==== Patch
     792
     793<record>patch</record>
     794<procedure>(patch? obj) => boolean</procedure>
     795
     796A {{patch}} is a textual representation of a {{diff-delta}}.
     797
     798<procedure>(patch->string patch) => string</procedure>
     799
     800Returns the string representation of the given {{patch}}.
     801
     802<procedure>(patch-size patch) => integer</procedure>
     803
     804Returns the total number of bytes in the patch, including hunk and line
     805headers and context lines.
     806
     807<procedure>(patch-stats patch) => (vector-of integer integer integer)</procedure>
     808
     809Returns a three-element vector containing the number of lines of
     810context, number of lines added, and number of lines deleted in the
     811patch.
    765812
    766813==== Status
     
    785832<procedure>(file-statuses-fold kons knil repository) => object</procedure>
    786833
    787 Folds over each path and corresponding file status in the given
    788 {{repository}}'s working directory.
     834Folds over each path and the corresponding file's status in the given
     835{{repository}}'s working directory in unspecified order.
    789836
    790837Note that {{kons}} should be a function of three arguments; the pathname
     
    793840fold.
    794841
    795 <procedure>(file-statuses repository) => list</procedure>
    796 
    797 Returns an alist all file statuses in the given {{repository}}, whose
    798 keys are the pathnames of the file  in the repository and whose keys are
    799 the status symbols of the files.
     842<procedure>(file-statuses repository) => (list-of (pair string symbol))</procedure>
     843
     844Returns an alist of all file statuses in the given {{repository}}, whose
     845keys are pathnames to each file and whose values are the status symbols
     846of those files. The order of the resulting list is unspecified.
    800847
    801848<procedure>(file-ignored? repository path) => boolean</procedure>
     
    856903which defaults to {{"refs/notes/commits"}}.
    857904
    858 <procedure>(notes repository [reference]) => list</procedure>
    859 
    860 Returns a list of all notes in the given {{repository}}.
     905<procedure>(notes repository [reference]) => (list-of note)</procedure>
     906
     907Returns a list of all notes in the given {{repository}}. The order of
     908the resulting list is unspecified.
    861909
    862910{{reference}} may specify an alternative notes reference namespace,
     
    916964given {{index}}, signaling an error if it doesn't exist.
    917965
    918 <procedure>(index-ref index key [type]) => index-entry</procedure>
     966<procedure>(index-ref index key [type]) => (or index-entry false)</procedure>
    919967
    920968Returns the {{index-entry}} from the {{index}} for the given {{key}}, which may
     
    11291177=== History
    11301178
     1179* 0.0.26 - libgit2 0.20.0 types
    11311180* 0.0.25 - libgit2 0.20.0 expanded diff API
    11321181* 0.0.24 - libgit2 0.20.0
Note: See TracChangeset for help on using the changeset viewer.