Changeset 25496 in project
- Timestamp:
- 11/11/11 22:06:12 (9 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
wiki/eggref/4/git
r25336 r25496 10 10 11 11 Please note that the libgit library is currently a moving target, under heavy 12 development. This library has been written and tested against libgit2 0.15.0.13 If you encounter problems, check your versions.12 development. This library has been written and tested against Chicken 4.6 & 4.7 13 and libgit2 0.15.0. If you encounter problems, check your versions. 14 14 15 15 === Documentation … … 36 36 === Usage 37 37 38 (use git) 39 40 or 41 38 (use git) ; or... 42 39 (use git-lolevel) 43 40 … … 50 47 51 48 <record>repository</record> 52 <procedure>(repository-open [path]) => repository</procedure> 49 <procedure>(repository? obj) => boolean</procedure> 50 51 A {{repository}} corresponds to an on-disk Git repository. 52 53 <procedure>(repository-open [path]) => repository</procedure> 54 55 Opens the Git repository indicated by {{path}}, or the value of 56 {{current-directory}} if no {{path}} is given. {{path}} may point to a bare 57 repository, a working directory containing a ".git" directory, or a ".git" 58 directory directly. 59 53 60 <procedure>(repository-path repository [type]) => string</procedure> 54 <procedure>(repository-ref repository ref) => object</procedure> 55 <procedure>(repository-empty? repository) => boolean</procedure> 56 <procedure>(repository-bare? repositoy) => boolean</procedure> 57 <procedure>(pack-references repository) => void</procedure> 61 62 Returns the absolute path to the given {{repository}}. A {{type}} symbol may be 63 given in order to retrieve alternate paths for the repository, and should be 64 one of {{path}} (the default), {{index}}, {{odb}} or {{workdir}}. 65 66 <procedure>(repository-ref repository ref [type]) => object</procedure> 67 68 Looks up a Git object in the given {{repository}}. {{ref}} may be a SHA1 string, 69 {{oid}}, {{reference}}, {{blob*}}, {{commit}}, {{tag}} or {{tree}}. The returned 70 object will be of type {{blob*}}, {{commit}}, {{tag}} or {{tree}}, or {{#f}} if 71 no object matching the given {{ref}} is found. An optional {{type}} symbol may 72 be given in order to enforce an object type for which to search. 73 74 <procedure>(repository-empty? repository) => boolean</procedure> 75 <procedure>(repository-bare? repositoy) => boolean</procedure> 76 77 Returns a boolean indicating whether the given {{repository}} is empty 78 (contains no commits) or bare (an exposed git directory without a working 79 directory). 80 81 <procedure>(pack-references repository) => void</procedure> 82 83 Writes all loose references in the given {{repository}} into its "pack-refs" 84 file and removes them from the on-disk repository. Calling this function will 85 invalidate any existing {{reference}} objects belonging to the repository. 58 86 59 87 ==== OID 60 88 61 89 <record>oid</record> 62 <procedure>(string->oid string) => oid</procedure> 90 <procedure>(oid? obj) => boolean</procedure> 91 92 An {{oid}} is a unique reference to a Git object, corresponding to a 93 40-character SHA1 object name. 94 95 <procedure>(string->oid string) => oid</procedure> 96 97 Creates an {{oid}} from the given string, which should be a 40-character SHA1 98 hash. An error is signaled if the string is not a valid hash. 99 63 100 <procedure>(oid->string oid [length]) => string</procedure> 64 <procedure>(oid->path oid) => string</procedure> 101 102 Returns the string representation of the given {{oid}}. The optional integer 103 {{length}} specifies the length of the returned string, up to 40 characters. 104 105 <procedure>(oid->path oid) => string</procedure> 106 107 Returns the string representation of the given {{oid}} in the form "xx/...", 108 where "xx" is the first two characters of the SHA1 and "..." is the remainder. 65 109 66 110 ==== Reference 67 111 68 112 <record>reference</record> 69 <procedure>(reference repository ref) => reference</procedure> 70 <procedure>(references repository) => list</procedure> 71 <procedure>(reference-id reference) => oid</procedure> 72 <procedure>(reference-owner reference) => repository</procedure> 73 <procedure>(reference-resolve reference) => reference</procedure> 74 <procedure>(reference-id-set reference oid) => void</procedure> 75 <procedure>(reference-rename reference name) => void</procedure> 76 <procedure>(reference-target-set reference target) => void</procedure> 77 <procedure>(create-reference repository name target [symbolic?]) => reference</procedure> 113 <procedure>(reference? obj) => boolean</procedure> 114 115 A {{reference}} is an indirect pointer to a Git commit object. A repository's 116 {{"HEAD"}} is a common example. 117 118 <procedure>(reference repository ref) => reference</procedure> 119 120 Returns the {{reference}} specified by the given string {{ref}} from the 121 {{repository}}. {{ref}} must refer to a valid reference, such as 122 {{"HEAD"}}, {{"ref/heads/master"}}, or {{"refs/tags/v0.1.0"}}. An error is 123 signalled if the reference doesn't exists. 124 125 <procedure>(references repository) => list</procedure> 126 127 Returns a list of all references in the given {{repository}}. 128 129 <procedure>(reference-id reference) => oid</procedure> 130 131 Returns the {{oid}} of the object referred to by the given {{reference}}. 132 133 <procedure>(reference-owner reference) => repository</procedure> 134 135 Returns the {{repository}} to which the given {{reference}} belongs. 136 137 <procedure>(reference-resolve reference) => reference</procedure> 138 139 Dereferences the given (possibly symbolic) {{reference}}, returning a new 140 non-symbolic {{reference}} pointing directly to a {{commit}}. 141 142 <procedure>(reference-rename reference name) => void</procedure> 143 <procedure>(reference-target-set reference target) => void</procedure> 144 145 {{reference-rename}} changes the name of the given {{reference}} to the string 146 {{name}}. 147 148 {{reference-target-set}} updates a {{reference}} to refer to the given 149 {{target}}. If {{reference}} is an immediate reference (referring to an object 150 ID), {{target}} must be an {{oid}}, {{commit}}, or SHA1 string. If 151 {{reference}} is symbolic, {{target}} must be a {{reference}} or reference 152 name. It is an error to assign a symbolic reference an OID target and 153 vice-versa. 154 155 On success, the on-disk repository is updated immediately. 156 157 <procedure>(create-reference repository #!key name target [symbolic?] [force?]) => reference</procedure> 158 159 Creates & returns a new reference in the given {{repository}} for the specified 160 {{name}} and {{target}}. If {{symbolic?}} is given and not {{#f}}, the created 161 reference will be so, and {{target}} must be a reference name or {{reference}}. 162 Otherwise, {{target}} must be a SHA1 string, {{oid}}, {{commit}} or 163 {{reference}} to a {{commit}}. If a reference of the given {{name}} exists and 164 {{force?}} is not given or {{#f}}, an error is signalled. Otherwise, creation 165 is forced and the old reference will be overwritten. 166 167 On success, the on-disk repository is updated immediately. 78 168 79 169 ==== Generic 80 170 81 <procedure>(object-id object) => oid</procedure> 171 <procedure>(object-id object) => oid</procedure> 172 173 Returns the {{oid}} referring to the given object, which must be a {{commit}}, 174 {{tree}}, {{tag}} or {{blob*}}. 175 82 176 <procedure>(object-sha object [length]) => string</procedure> 83 <procedure>(object-type object) => symbol</procedure> 177 178 Returns the SHA1 identifier corresponding to the given object, which may be a 179 {{commit}}, {{tree}}, {{tag}} {{blob*}}, {{reference}}, {{oid}} or {{string}}. 180 181 <procedure>(object-type object) => symbol</procedure> 182 183 Returns a symbol specifying the type of the given object, which must be one of 184 {{commit}}, {{tree}}, {{tag}} or {{blob*}}. {{#f}} is returned if the type 185 cannot be determined. 84 186 85 187 ==== Blob* 86 188 87 189 <record>blob*</record> 190 <procedure>(blob*? obj) => boolean</procedure> 191 192 A {{blob*}} corresponds to Git's Blob object type, renamed in order to avoid 193 name clashes with Chicken's built-in {{blob}} type. It represents a file. 194 88 195 <procedure>(blob* repository ref) => blob*</procedure> 89 <procedure>(blob*-content blob) => blob</procedure> 90 <procedure>(blob*-size blob) => int</procedure> 196 197 Returns the {{blob*}} specified by the given {{ref}} from the repository. 198 {{ref}} may be a SHA1 string, {{oid}}, or {{blob*}}. An error is signaled if 199 no such {{blob*}} exists. 200 201 <procedure>(blob*-content blob*) => blob</procedure> 202 203 Returns a {{blob}} (of the Chicken built-in type) with the contents of the given 204 {{blob*}} (of the Git object type). 205 206 <procedure>(blob*-size blob*) => int</procedure> 207 208 Returns the size in bytes of the given {{blob*}}. 91 209 92 210 ==== Commit 93 211 94 212 <record>commit</record> 95 <procedure>(commit repository ref) => commit</procedure> 96 <procedure>(commits repository initial [hide] [sort]) => list</procedure> 97 <procedure>(commit-id commit) => oid</procedure> 98 <procedure>(commit-parentcount commit) => int</procedure> 99 <procedure>(commit-time commit) => int</procedure> 100 <procedure>(commit-time-offset commit) => int</procedure> 101 <procedure>(commit-message commit) => string</procedure> 102 <procedure>(commit-message-short commit) => string</procedure> 103 <procedure>(commit-tree commit) => tree</procedure> 104 <procedure>(commit-author commit) => signature</procedure> 105 <procedure>(commit-committer commit) => signature</procedure> 106 <procedure>(commit-parent commit [n]) => commit</procedure> 107 <procedure>(create-commit repository tree message [parents] author [committer] [reference]) => commit</procedure> 213 <procedure>(commit? obj) => boolean</procedure> 214 215 A {{commit}} corresponds to Git's commit object type. 216 217 <procedure>(commit repository ref) => commit</procedure> 218 219 Returns the {{commit}} specified by the given {{ref}} from the repository. 220 {{ref}} may be a SHA1 string, {{oid}}, {{reference}} or {{commit}}. An error 221 is signaled if no such {{commit}} exists. 222 223 <procedure>(commits repository #!key [initial] [hide] [sort]) => list</procedure> 224 225 Returns a list of all {{commit}}s in the given {{repository}}. If a {{commit}} 226 or SHA1 {{initial}} is given, 227 228 <procedure>(commit-id commit) => oid</procedure> 229 230 Returns the {{oid}} for the given {{commit}}. 231 232 <procedure>(commit-time commit) => int</procedure> 233 <procedure>(commit-time-offset commit) => int</procedure> 234 235 {{commit-time}} and {{commit-time-offset}} return the timestamp of the given 236 {{commit}} and its UTC offset in minutes, respectively. 237 238 <procedure>(commit-message commit) => string</procedure> 239 240 Returns the full commit message of the given {{commit}}. 241 242 <procedure>(commit-tree commit) => tree</procedure> 243 244 Returns the {{tree}} associated with the given {{commit}}. 245 246 <procedure>(commit-author commit) => signature</procedure> 247 <procedure>(commit-committer commit) => signature</procedure> 248 249 {{commit-author}} and {{commit-committer}} return the given {{commit}}'s 250 respective {{signature}}s. 251 252 <procedure>(commit-parentcount commit) => int</procedure> 253 <procedure>(commit-parent commit [n]) => commit</procedure> 254 255 {{commit-parentcount}} returns the number of parents for a given {{commit}}. 256 257 {{commit-parent}} returns the {{n}}th parent of the given {{commit}}, or the 258 first if no {{n}} is given. 259 260 <procedure>(create-commit repository #!key message tree [parents] author [committer] [reference]) => commit</procedure> 261 262 Creates & returns a new commit in the given {{repository}}. The string 263 {{message}} will be used as the commit's message and {{tree}} will be the file 264 tree of the commit. {{parents}} should be be a (possibly empty) list of commits 265 to be used as this commit's parents. {{author}} and {{committer}} should be 266 signatures; if {{committer}} is not given, {{author}} will be used for both. 267 {{reference}}, if given and not {{#f}}, should be the {{reference}} that will 268 be updated to point to the newly-created commit. 269 270 Note that if no {{reference}} is given, the commit will be created in Git's 271 database but will not be reflected in any of the repository's branches. To 272 update the the working branch with the new commit, for example, use "HEAD". 273 274 On success, the on-disk repository is updated immediately. 108 275 109 276 ==== Tag 110 277 111 278 <record>tag</record> 279 <procedure>(tag? obj) => boolean</procedure> 280 281 A {{tag}} corresponds to Git's Tag object type, which is a way to mark a 282 specific object as special in some way. 283 112 284 <procedure>(tag repository name) => tag</procedure> 113 <procedure>(tags repository) => list</procedure> 114 <procedure>(tag-id tag) => oid</procedure> 115 <procedure>(tag-type tag) => symbol</procedure> 116 <procedure>(tag-name tag) => string</procedure> 117 <procedure>(tag-message tag) => string</procedure> 118 <procedure>(tag-tagger tag) => signature</procedure> 119 <procedure>(tag-target tag) => object</procedure> 120 <procedure>(tag-delete tag) => tag</procedure> 121 <procedure>(create-tag repository target name message tagger) => tag</procedure> 285 286 Creates & returns the {{tag}} specified by the given {{ref}} from the 287 repository. {{ref}} may be a SHA1 string, {{oid}}, or {{tag}}. An error is 288 signaled if no such {{tag}} exists. 289 290 <procedure>(tags repository) => list</procedure> 291 292 Returns a list of all tags in the given {{repository}}. 293 294 <procedure>(tag-id tag) => oid</procedure> 295 296 Returns the {{oid}} for the given {{tag}}. 297 298 <procedure>(tag-type tag) => symbol</procedure> 299 300 Returns the object type symbol of the target of the given {{tag}}, which will 301 be one of {{commit}}, {{tree}}, {{blob}}, or {{tag}}. 302 303 <procedure>(tag-name tag) => string</procedure> 304 <procedure>(tag-message tag) => string</procedure> 305 306 Return the name or message strings of the given {{tag}}. 307 308 <procedure>(tag-tagger tag) => signature</procedure> 309 310 Returns the {{signature}} of the {{tag}}'s creator. 311 312 <procedure>(tag-target tag) => object</procedure> 313 314 Returns the object referred to by {{tag}}, which will be of type {{commit}}, 315 {{tree}}, {{blob}} or {{tag}}. 316 317 <procedure>(tag-delete tag) => void</procedure> 318 319 Destroys the given {{tag}}. 320 321 On success, the on-disk repository is updated immediately. 322 323 <procedure>(create-tag repository #!key target name message tagger [force?]) => tag</procedure> 324 325 Creates & returns a new tag in the given {{repository}} for the specified 326 {{name}}, {{message}} and {{target}}. {{name}} and {{message}} must be strings, 327 {{tagger}} must be a {{signature}},and {{target}} must be a {{commit}}, 328 {{tree}} or {{blob*}}. If a tag of the given {{name}} exists and {{force?}} is 329 not given or {{#f}}, an error is signalled. Otherwise, creation is forced and 330 the old tag will be overwritten. 331 332 On success, the on-disk repository is updated immediately. 122 333 123 334 ==== Tree 124 335 125 336 <record>tree</record> 126 <procedure>(tree repository ref) => tree</procedure> 127 <procedure>(tree-id tree) => oid</procedure> 128 <procedure>(tree-entrycount tree) => int</procedure> 129 <procedure>(tree-ref tree key) => tree-entry</procedure> 130 <procedure>(tree->list tree [repo]) => list</procedure> 337 <procedure>(tree? obj) => boolean</procedure> 338 339 A {{tree}} corresponds to Git's Tree object type, which represents a directory 340 tree. 341 342 <procedure>(tree repository ref) => tree</procedure> 343 344 Returns the {{tree}} specified by the given {{ref}} from the repository. {{ref}} 345 may be a SHA1 string, {{oid}}, or {{tree}}. An error is signaled if no such 346 {{tree}} exists. 347 348 <procedure>(tree-id tree) => oid</procedure> 349 350 Returns the {{oid}} for the given {{tree}}. 351 352 <procedure>(tree-entrycount tree) => int</procedure> 353 354 Returns the number of entries in the given {{tree}}. This count does not 355 include entries of contained directories. 356 357 <procedure>(tree-ref tree key) => tree-entry</procedure> 358 359 Returns a {{tree-entry}} object for the given {{key}}, or {{#f}} if no such 360 object is found. {{key}} may be a numerical index or the string of an entry 361 name. 362 363 <procedure>(tree->list tree [repository]) => list</procedure> 364 365 Returns a list of {{tree-entry}} objects for the given {{tree}}. If a 366 {{repository}} is given, this function will recurse into it, returning a nested 367 list of entries spanning the full directory tree. 368 131 369 <procedure>(create-tree repository index) => tree</procedure> 132 370 371 Creates and returns a {{tree}} object from the state of the given {{index}}. 372 133 373 ==== Tree Entry 134 374 135 375 <record>tree-entry</record> 136 <procedure>(tree-entry-id tree-entry) => oid</procedure> 137 <procedure>(tree-entry-name tree-entry) => string</procedure> 138 <procedure>(tree-entry-attributes tree-entry) => int</procedure> 139 <procedure>(tree-entry-type tree-entry) => symbol</procedure> 376 <procedure>(tree-entry? obj) => boolean</procedure> 377 378 A {{tree-entry}} represents a single node in a {{tree}} object. 379 380 <procedure>(tree-entry-id tree-entry) => oid</procedure> 381 382 Returns the {{oid}} of the given {{tree-entry}}. 383 384 <procedure>(tree-entry-name tree-entry) => string</procedure> 385 386 Returns the name of the given {{tree-entry}}. 387 388 <procedure>(tree-entry-attributes tree-entry) => int</procedure> 389 390 Returns the Unix file attributes of the given {{tree-entry}}. 391 392 <procedure>(tree-entry-type tree-entry) => symbol</procedure> 393 394 Returns the object type symbol, either {{tree}} or {{blob}}, of the given 395 {{tree-entry}}. 396 140 397 <procedure>(tree-entry->object repository tree-entry) => object</procedure> 141 398 399 Returns an object of type {{tree}} or {{blob*}} from the given {{tree-entry}} 400 and {{repository}}, which must be the owner of the {{tree-entry}}. 401 142 402 ==== Index 143 403 144 404 <record>index</record> 145 <procedure>(index-open repo-or-path) => index</procedure> 146 <procedure>(index-entrycount index) => int</procedure> 405 <procedure>(index? obj) => boolean</procedure> 406 <procedure>(index-open repo-or-path) => index</procedure> 407 <procedure>(index-entrycount index) => int</procedure> 147 408 <procedure>(index-entrycount-unmerged index) => int</procedure> 148 <procedure>(index-read index) 149 <procedure>(index-write index) 150 <procedure>(index-clear index) 151 <procedure>(index-add index path [stage]) 152 <procedure>(index-remove index ref) 153 <procedure>(index-find index) 154 <procedure>(index-ref index key) 155 <procedure>(index->list index [type]) 409 <procedure>(index-read index) => void</procedure> 410 <procedure>(index-write index) => void</procedure> 411 <procedure>(index-clear index) => void</procedure> 412 <procedure>(index-add index path [stage]) => void</procedure> 413 <procedure>(index-remove index ref) => void</procedure> 414 <procedure>(index-find index) => int</procedure> 415 <procedure>(index-ref index key) => index-entry</procedure> 416 <procedure>(index->list index [type]) => list</procedure> 156 417 157 418 ==== Index Entry 158 419 159 420 <record>index-entry</record> 160 <procedure>(index-entry-id index-entry) => oid</procedure> 161 <procedure>(index-entry-path index-entry) => string</procedure> 162 <procedure>(index-entry-ctime index-entry) => int</procedure> 163 <procedure>(index-entry-mtime index-entry) => int</procedure> 164 <procedure>(index-entry-dev index-entry) => int</procedure> 165 <procedure>(index-entry-ino index-entry) => int</procedure> 166 <procedure>(index-entry-size index-entry) => int</procedure> 167 <procedure>(index-entry-stage index-entry) => int</procedure> 168 <procedure>(index-entry-uid index-entry) => int</procedure> 169 <procedure>(index-entry-gid index-entry) => int</procedure> 170 <procedure>(index-entry-mode index-entry) => int</procedure> 171 <procedure>(index-entry-flags index-entry) => int</procedure> 172 <procedure>(index-entry-extended index-entry) => int</procedure> 421 <procedure>(index-entry? obj) => boolean</procedure> 422 <procedure>(index-entry-id index-entry) => oid</procedure> 423 <procedure>(index-entry-path index-entry) => string</procedure> 424 <procedure>(index-entry-ctime index-entry) => int</procedure> 425 <procedure>(index-entry-mtime index-entry) => int</procedure> 426 <procedure>(index-entry-dev index-entry) => int</procedure> 427 <procedure>(index-entry-ino index-entry) => int</procedure> 428 <procedure>(index-entry-size index-entry) => int</procedure> 429 <procedure>(index-entry-stage index-entry) => int</procedure> 430 <procedure>(index-entry-uid index-entry) => int</procedure> 431 <procedure>(index-entry-gid index-entry) => int</procedure> 432 <procedure>(index-entry-mode index-entry) => int</procedure> 433 <procedure>(index-entry-flags index-entry) => int</procedure> 434 <procedure>(index-entry-extended index-entry) => int</procedure> 173 435 <procedure>(index-entry->object repository index-entry) => object</procedure> 174 436 175 437 ==== ODB 176 438 177 <procedure>(odb-new) => odb</procedure> 178 <procedure>(odb-open repo-or-path) => odb</procedure> 179 <procedure>(odb-has-object? odb ref) => boolean</procedure> 180 <procedure>(odb-read odb ref) => odb-object</procedure> 439 <record>odb</record> 440 <procedure>(odb? obj) => boolean</procedure> 441 <procedure>(odb-new) => odb</procedure> 442 <procedure>(odb-open repo-or-path) => odb</procedure> 443 <procedure>(odb-has-object? odb ref) => boolean</procedure> 444 <procedure>(odb-read odb ref) => odb-object</procedure> 181 445 <procedure>(odb-write odb data [type]) => oid</procedure> 182 <procedure>(odb-hash odb data [type]) 446 <procedure>(odb-hash odb data [type]) => oid</procedure> 183 447 184 448 ==== ODB Object 185 449 186 450 <record>odb-object</record> 187 <procedure>(odb-object-id odb-object) => oid</procedure> 451 <procedure>(odb-object? obj) => boolean</procedure> 452 453 An {{odb-object}} is a reference to a blob of data in a Git object database. 454 455 <procedure>(odb-object-id odb-object) => oid</procedure> 456 457 Returns the {{oid}} for the given {{odb-object}}. 458 188 459 <procedure>(odb-object-size odb-object) => int</procedure> 460 461 Returns the size of the {{odb-object}}'s data in bytes. 462 189 463 <procedure>(odb-object-type odb-object) => symbol</procedure> 464 465 Returns the object type symbol of the given {{odb-object}}. 466 190 467 <procedure>(odb-object-data odb-object) => blob</procedure> 191 468 469 Returns a blob consisting of the {{odb-object}}'s data. 470 192 471 ==== Signature 193 472 194 473 <record>signature</record> 195 <procedure>(make-signature name email [time] [offset]) => signature</procedure> 196 <procedure>(signature-name signature) => string</procedure> 197 <procedure>(signature-email signature) => string</procedure> 198 <procedure>(signature-time signature) => int</procedure> 199 <procedure>(signature-time-offset signature) => int</procedure> 474 <procedure>(signature? obj) => boolean</procedure> 475 476 A signature is a record of the name, email, time and UTC offset of a given Git 477 object. 478 479 <procedure>(make-signature name email [time [offset]]) => signature</procedure> 480 481 Returns a new {{signature}} for the given name and email strings. If a 482 timestamp {{time}} and integer {{offset}} are given, they will be used as the 483 signature time; otherwise, the current time will be used. 484 485 Unlike the {{create-*}} functions, no representation of this signature is 486 created in the repository; it exists only in memory until associated with a 487 {{commit}} or {{tag}}. 488 489 <procedure>(signature-name signature) => string</procedure> 490 <procedure>(signature-email signature) => string</procedure> 491 492 {{signature-name}} and {{signature-email}} return strings for the 493 given {{signature}}'s respective fields. 494 495 <procedure>(signature-time signature) => int</procedure> 496 <procedure>(signature-time-offset signature) => int</procedure> 497 498 {{signature-time}} and {{signature-time-offset}} return the timestamp of the 499 given {{signature}} and its UTC offset in minutes, respectively. 200 500 201 501 === Author
Note: See TracChangeset
for help on using the changeset viewer.