1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 4 * This file is part of libgit2, distributed under the GNU GPL v2 with 5 * a Linking Exception. For full terms see the included COPYING file. 6 */ 7 module libgit2_d.odb; 8 9 10 private static import libgit2_d.indexer; 11 private static import libgit2_d.oid; 12 private static import libgit2_d.types; 13 14 /** 15 * @file git2/odb.h 16 * @brief Git object database routines 17 * @defgroup git_odb Git object database routines 18 * @ingroup Git 19 * @{ 20 */ 21 extern (C): 22 nothrow @nogc: 23 public: 24 25 /** 26 * Function type for callbacks from git_odb_foreach. 27 */ 28 alias git_odb_foreach_cb = int function(const (libgit2_d.oid.git_oid)* id, void* payload); 29 30 /** 31 * Create a new object database with no backends. 32 * 33 * Before the ODB can be used for read/writing, a custom database 34 * backend must be manually added using `git_odb_add_backend()` 35 * 36 * Params: 37 * out_ = location to store the database pointer, if opened. Set to null if the open failed. 38 * 39 * Returns: 0 or an error code 40 */ 41 //GIT_EXTERN 42 int git_odb_new(libgit2_d.types.git_odb** out_); 43 44 /** 45 * Create a new object database and automatically add 46 * the two default backends: 47 * 48 * - git_odb_backend_loose: read and write loose object files 49 * from disk, assuming `objects_dir` as the Objects folder 50 * 51 * - git_odb_backend_pack: read objects from packfiles, 52 * assuming `objects_dir` as the Objects folder which 53 * contains a 'pack/' folder with the corresponding data 54 * 55 * Params: 56 * out_ = location to store the database pointer, if opened. Set to null if the open failed. 57 * objects_dir = path of the backends' "objects" directory. 58 * 59 * Returns: 0 or an error code 60 */ 61 //GIT_EXTERN 62 int git_odb_open(libgit2_d.types.git_odb** out_, const (char)* objects_dir); 63 64 /** 65 * Add an on-disk alternate to an existing Object DB. 66 * 67 * Note that the added path must point to an `objects`, not 68 * to a full repository, to use it as an alternate store. 69 * 70 * Alternate backends are always checked for objects *after* 71 * all the main backends have been exhausted. 72 * 73 * Writing is disabled on alternate backends. 74 * 75 * Params: 76 * odb = database to add the backend to 77 * path = path to the objects folder for the alternate 78 * 79 * Returns: 0 on success; error code otherwise 80 */ 81 //GIT_EXTERN 82 int git_odb_add_disk_alternate(libgit2_d.types.git_odb* odb, const (char)* path); 83 84 /** 85 * Close an open object database. 86 * 87 * Params: 88 * db = database pointer to close. If null no action is taken. 89 */ 90 //GIT_EXTERN 91 void git_odb_free(libgit2_d.types.git_odb* db); 92 93 /** 94 * Read an object from the database. 95 * 96 * This method queries all available ODB backends 97 * trying to read the given OID. 98 * 99 * The returned object is reference counted and 100 * internally cached, so it should be closed 101 * by the user once it's no longer in use. 102 * 103 * Params: 104 * out_ = pointer where to store the read object 105 * db = database to search for the object in. 106 * id = identity of the object to read. 107 * 108 * @return 109 * - 0 if the object was read; 110 * - git_error_code.GIT_ENOTFOUND if the object is not in the database. 111 */ 112 //GIT_EXTERN 113 int git_odb_read(libgit2_d.types.git_odb_object** out_, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* id); 114 115 /** 116 * Read an object from the database, given a prefix 117 * of its identifier. 118 * 119 * This method queries all available ODB backends 120 * trying to match the 'len' first hexadecimal 121 * characters of the 'short_id'. 122 * The remaining (GIT_OID_HEXSZ-len)*4 bits of 123 * 'short_id' must be 0s. 124 * 'len' must be at least GIT_OID_MINPREFIXLEN, 125 * and the prefix must be long enough to identify 126 * a unique object in all the backends; the 127 * method will fail otherwise. 128 * 129 * The returned object is reference counted and 130 * internally cached, so it should be closed 131 * by the user once it's no longer in use. 132 * 133 * Params: 134 * out_ = pointer where to store the read object 135 * db = database to search for the object in. 136 * short_id = a prefix of the id of the object to read. 137 * len = the length of the prefix 138 * 139 * @return 140 * - 0 if the object was read; 141 * - git_error_code.GIT_ENOTFOUND if the object is not in the database. 142 * - git_error_code.GIT_EAMBIGUOUS if the prefix is ambiguous (several objects match the 143 * prefix) 144 */ 145 //GIT_EXTERN 146 int git_odb_read_prefix(libgit2_d.types.git_odb_object** out_, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* short_id, size_t len); 147 148 /** 149 * Read the header of an object from the database, without 150 * reading its full contents. 151 * 152 * The header includes the length and the type of an object. 153 * 154 * Note that most backends do not support reading only the header 155 * of an object, so the whole object will be read and then the 156 * header will be returned. 157 * 158 * Params: 159 * len_out = pointer where to store the length 160 * type_out = pointer where to store the type 161 * db = database to search for the object in. 162 * id = identity of the object to read. 163 * 164 * @return 165 * - 0 if the object was read; 166 * - git_error_code.GIT_ENOTFOUND if the object is not in the database. 167 */ 168 //GIT_EXTERN 169 int git_odb_read_header(size_t* len_out, libgit2_d.types.git_object_t* type_out, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* id); 170 171 /** 172 * Determine if the given object can be found in the object database. 173 * 174 * Params: 175 * db = database to be searched for the given object. 176 * id = the object to search for. 177 * 178 * @return 179 * - 1, if the object was found 180 * - 0, otherwise 181 */ 182 //GIT_EXTERN 183 int git_odb_exists(libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* id); 184 185 /** 186 * Determine if an object can be found in the object database by an 187 * abbreviated object ID. 188 * 189 * Params: 190 * out_ = The full OID of the found object if just one is found. 191 * db = The database to be searched for the given object. 192 * short_id = A prefix of the id of the object to read. 193 * len = The length of the prefix. 194 * 195 * Returns: 0 if found, git_error_code.GIT_ENOTFOUND if not found, git_error_code.GIT_EAMBIGUOUS if multiple matches were found, other value < 0 if there was a read error. 196 */ 197 //GIT_EXTERN 198 int git_odb_exists_prefix(libgit2_d.oid.git_oid* out_, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* short_id, size_t len); 199 200 /** 201 * The information about object IDs to query in `git_odb_expand_ids`, 202 * which will be populated upon return. 203 */ 204 struct git_odb_expand_id 205 { 206 /** 207 * The object ID to expand 208 */ 209 libgit2_d.oid.git_oid id; 210 211 /** 212 * The length of the object ID (in nibbles, or packets of 4 bits; the 213 * number of hex characters) 214 * */ 215 ushort length; 216 217 /** 218 * The (optional) type of the object to search for; leave as `0` or set 219 * to `git_object_t.GIT_OBJECT_ANY` to query for any object matching the ID. 220 */ 221 libgit2_d.types.git_object_t type = cast(libgit2_d.types.git_object_t)(0); 222 } 223 224 /** 225 * Determine if one or more objects can be found in the object database 226 * by their abbreviated object ID and type. The given array will be 227 * updated in place: for each abbreviated ID that is unique in the 228 * database, and of the given type (if specified), the full object ID, 229 * object ID length (`GIT_OID_HEXSZ`) and type will be written back to 230 * the array. For IDs that are not found (or are ambiguous), the 231 * array entry will be zeroed. 232 * 233 * Note that since this function operates on multiple objects, the 234 * underlying database will not be asked to be reloaded if an object is 235 * not found (which is unlike other object database operations.) 236 * 237 * Params: 238 * db = The database to be searched for the given objects. 239 * ids = An array of short object IDs to search for 240 * count = The length of the `ids` array 241 * 242 * Returns: 0 on success or an error code on failure 243 */ 244 //GIT_EXTERN 245 int git_odb_expand_ids(libgit2_d.types.git_odb* db, .git_odb_expand_id* ids, size_t count); 246 247 /** 248 * Refresh the object database to load newly added files. 249 * 250 * If the object databases have changed on disk while the library 251 * is running, this function will force a reload of the underlying 252 * indexes. 253 * 254 * Use this function when you're confident that an external 255 * application has tampered with the ODB. 256 * 257 * NOTE that it is not necessary to call this function at all. The 258 * library will automatically attempt to refresh the ODB 259 * when a lookup fails, to see if the looked up object exists 260 * on disk but hasn't been loaded yet. 261 * 262 * Params: 263 * db = database to refresh 264 * 265 * Returns: 0 on success, error code otherwise 266 */ 267 //GIT_EXTERN 268 int git_odb_refresh(libgit2_d.types.git_odb* db); 269 270 /** 271 * List all objects available in the database 272 * 273 * The callback will be called for each object available in the 274 * database. Note that the objects are likely to be returned in the index 275 * order, which would make accessing the objects in that order inefficient. 276 * Return a non-zero value from the callback to stop looping. 277 * 278 * Params: 279 * db = database to use 280 * cb = the callback to call for each object 281 * payload = data to pass to the callback 282 * 283 * Returns: 0 on success, non-zero callback return value, or error code 284 */ 285 //GIT_EXTERN 286 int git_odb_foreach(libgit2_d.types.git_odb* db, .git_odb_foreach_cb cb, void* payload); 287 288 /** 289 * Write an object directly into the ODB 290 * 291 * This method writes a full object straight into the ODB. 292 * For most cases, it is preferred to write objects through a write 293 * stream, which is both faster and less memory intensive, specially 294 * for big objects. 295 * 296 * This method is provided for compatibility with custom backends 297 * which are not able to support streaming writes 298 * 299 * Params: 300 * out_ = pointer to store the OID result of the write 301 * odb = object database where to store the object 302 * data = buffer with the data to store 303 * len = size of the buffer 304 * type = type of the data to store 305 * 306 * Returns: 0 or an error code 307 */ 308 //GIT_EXTERN 309 int git_odb_write(libgit2_d.oid.git_oid* out_, libgit2_d.types.git_odb* odb, const (void)* data, size_t len, libgit2_d.types.git_object_t type); 310 311 /** 312 * Open a stream to write an object into the ODB 313 * 314 * The type and final length of the object must be specified 315 * when opening the stream. 316 * 317 * The returned stream will be of type `git_odb_stream_t.GIT_STREAM_WRONLY`, and it 318 * won't be effective until `git_odb_stream_finalize_write` is called 319 * and returns without an error 320 * 321 * The stream must always be freed when done with `git_odb_stream_free` or 322 * will leak memory. 323 * 324 * @see git_odb_stream 325 * 326 * Params: 327 * out_ = pointer where to store the stream 328 * db = object database where the stream will write 329 * size = final size of the object that will be written 330 * type = type of the object that will be written 331 * 332 * Returns: 0 if the stream was created; error code otherwise 333 */ 334 //GIT_EXTERN 335 int git_odb_open_wstream(libgit2_d.types.git_odb_stream** out_, libgit2_d.types.git_odb* db, libgit2_d.types.git_object_size_t size, libgit2_d.types.git_object_t type); 336 337 /** 338 * Write to an odb stream 339 * 340 * This method will fail if the total number of received bytes exceeds the 341 * size declared with `git_odb_open_wstream()` 342 * 343 * Params: 344 * stream = the stream 345 * buffer = the data to write 346 * len = the buffer's length 347 * 348 * Returns: 0 if the write succeeded; error code otherwise 349 */ 350 //GIT_EXTERN 351 int git_odb_stream_write(libgit2_d.types.git_odb_stream* stream, const (char)* buffer, size_t len); 352 353 /** 354 * Finish writing to an odb stream 355 * 356 * The object will take its final name and will be available to the 357 * odb. 358 * 359 * This method will fail if the total number of received bytes 360 * differs from the size declared with `git_odb_open_wstream()` 361 * 362 * Params: 363 * out_ = pointer to store the resulting object's id 364 * stream = the stream 365 * 366 * Returns: 0 on success; an error code otherwise 367 */ 368 //GIT_EXTERN 369 int git_odb_stream_finalize_write(libgit2_d.oid.git_oid* out_, libgit2_d.types.git_odb_stream* stream); 370 371 /** 372 * Read from an odb stream 373 * 374 * Most backends don't implement streaming reads 375 */ 376 //GIT_EXTERN 377 int git_odb_stream_read(libgit2_d.types.git_odb_stream* stream, char* buffer, size_t len); 378 379 /** 380 * Free an odb stream 381 * 382 * Params: 383 * stream = the stream to free 384 */ 385 //GIT_EXTERN 386 void git_odb_stream_free(libgit2_d.types.git_odb_stream* stream); 387 388 /** 389 * Open a stream to read an object from the ODB 390 * 391 * Note that most backends do *not* support streaming reads 392 * because they store their objects as compressed/delta'ed blobs. 393 * 394 * It's recommended to use `git_odb_read` instead, which is 395 * assured to work on all backends. 396 * 397 * The returned stream will be of type `git_odb_stream_t.GIT_STREAM_RDONLY` and 398 * will have the following methods: 399 * 400 * - stream->read: read `n` bytes from the stream 401 * - stream->free: free the stream 402 * 403 * The stream must always be free'd or will leak memory. 404 * 405 * @see git_odb_stream 406 * 407 * Params: 408 * out_ = pointer where to store the stream 409 * len = pointer where to store the length of the object 410 * type = pointer where to store the type of the object 411 * db = object database where the stream will read from 412 * oid = oid of the object the stream will read from 413 * 414 * Returns: 0 if the stream was created; error code otherwise 415 */ 416 //GIT_EXTERN 417 int git_odb_open_rstream(libgit2_d.types.git_odb_stream** out_, size_t* len, libgit2_d.types.git_object_t* type, libgit2_d.types.git_odb* db, const (libgit2_d.oid.git_oid)* oid); 418 419 /** 420 * Open a stream for writing a pack file to the ODB. 421 * 422 * If the ODB layer understands pack files, then the given 423 * packfile will likely be streamed directly to disk (and a 424 * corresponding index created). If the ODB layer does not 425 * understand pack files, the objects will be stored in whatever 426 * format the ODB layer uses. 427 * 428 * @see git_odb_writepack 429 * 430 * Params: 431 * out_ = pointer to the writepack functions 432 * db = object database where the stream will read from 433 * progress_cb = function to call with progress information. Be aware that this is called inline with network and indexing operations, so performance may be affected. 434 * progress_payload = payload for the progress callback 435 */ 436 //GIT_EXTERN 437 int git_odb_write_pack(libgit2_d.types.git_odb_writepack** out_, libgit2_d.types.git_odb* db, libgit2_d.indexer.git_indexer_progress_cb progress_cb, void* progress_payload); 438 439 /** 440 * Determine the object-ID (sha1 hash) of a data buffer 441 * 442 * The resulting SHA-1 OID will be the identifier for the data 443 * buffer as if the data buffer it were to written to the ODB. 444 * 445 * Params: 446 * out_ = the resulting object-ID. 447 * data = data to hash 448 * len = size of the data 449 * type = of the data to hash 450 * 451 * Returns: 0 or an error code 452 */ 453 //GIT_EXTERN 454 int git_odb_hash(libgit2_d.oid.git_oid* out_, const (void)* data, size_t len, libgit2_d.types.git_object_t type); 455 456 /** 457 * Read a file from disk and fill a git_oid with the object id 458 * that the file would have if it were written to the Object 459 * Database as an object of the given type (w/o applying filters). 460 * Similar functionality to git.git's `git hash-object` without 461 * the `-w` flag, however, with the --no-filters flag. 462 * If you need filters, see git_repository_hashfile. 463 * 464 * Params: 465 * out_ = oid structure the result is written into. 466 * path = file to read and determine object id for 467 * type = the type of the object that will be hashed 468 * 469 * Returns: 0 or an error code 470 */ 471 //GIT_EXTERN 472 int git_odb_hashfile(libgit2_d.oid.git_oid* out_, const (char)* path, libgit2_d.types.git_object_t type); 473 474 /** 475 * Create a copy of an odb_object 476 * 477 * The returned copy must be manually freed with `git_odb_object_free`. 478 * Note that because of an implementation detail, the returned copy will be 479 * the same pointer as `source`: the object is internally refcounted, so the 480 * copy still needs to be freed twice. 481 * 482 * Params: 483 * dest = pointer where to store the copy 484 * source = object to copy 485 * 486 * Returns: 0 or an error code 487 */ 488 //GIT_EXTERN 489 int git_odb_object_dup(libgit2_d.types.git_odb_object** dest, libgit2_d.types.git_odb_object* source); 490 491 /** 492 * Close an ODB object 493 * 494 * This method must always be called once a `git_odb_object` is no 495 * longer needed, otherwise memory will leak. 496 * 497 * Params: 498 * object = object to close 499 */ 500 //GIT_EXTERN 501 void git_odb_object_free(libgit2_d.types.git_odb_object* object); 502 503 /** 504 * Return the OID of an ODB object 505 * 506 * This is the OID from which the object was read from 507 * 508 * Params: 509 * object = the object 510 * 511 * Returns: a pointer to the OID 512 */ 513 //GIT_EXTERN 514 const (libgit2_d.oid.git_oid)* git_odb_object_id(libgit2_d.types.git_odb_object* object); 515 516 /** 517 * Return the data of an ODB object 518 * 519 * This is the uncompressed, raw data as read from the ODB, 520 * without the leading header. 521 * 522 * This pointer is owned by the object and shall not be free'd. 523 * 524 * Params: 525 * object = the object 526 * 527 * Returns: a pointer to the data 528 */ 529 //GIT_EXTERN 530 const (void)* git_odb_object_data(libgit2_d.types.git_odb_object* object); 531 532 /** 533 * Return the size of an ODB object 534 * 535 * This is the real size of the `data` buffer, not the 536 * actual size of the object. 537 * 538 * Params: 539 * object = the object 540 * 541 * Returns: the size 542 */ 543 //GIT_EXTERN 544 size_t git_odb_object_size(libgit2_d.types.git_odb_object* object); 545 546 /** 547 * Return the type of an ODB object 548 * 549 * Params: 550 * object = the object 551 * 552 * Returns: the type 553 */ 554 //GIT_EXTERN 555 libgit2_d.types.git_object_t git_odb_object_type(libgit2_d.types.git_odb_object* object); 556 557 /** 558 * Add a custom backend to an existing Object DB 559 * 560 * The backends are checked in relative ordering, based on the 561 * value of the `priority` parameter. 562 * 563 * Read <sys/odb_backend.h> for more information. 564 * 565 * Params: 566 * odb = database to add the backend to 567 * backend = pointer to a git_odb_backend instance 568 * priority = Value for ordering the backends queue 569 * 570 * Returns: 0 on success; error code otherwise 571 */ 572 //GIT_EXTERN 573 int git_odb_add_backend(libgit2_d.types.git_odb* odb, libgit2_d.types.git_odb_backend* backend, int priority); 574 575 /** 576 * Add a custom backend to an existing Object DB; this 577 * backend will work as an alternate. 578 * 579 * Alternate backends are always checked for objects *after* 580 * all the main backends have been exhausted. 581 * 582 * The backends are checked in relative ordering, based on the 583 * value of the `priority` parameter. 584 * 585 * Writing is disabled on alternate backends. 586 * 587 * Read <sys/odb_backend.h> for more information. 588 * 589 * Params: 590 * odb = database to add the backend to 591 * backend = pointer to a git_odb_backend instance 592 * priority = Value for ordering the backends queue 593 * 594 * Returns: 0 on success; error code otherwise 595 */ 596 //GIT_EXTERN 597 int git_odb_add_alternate(libgit2_d.types.git_odb* odb, libgit2_d.types.git_odb_backend* backend, int priority); 598 599 /** 600 * Get the number of ODB backend objects 601 * 602 * Params: 603 * odb = object database 604 * 605 * Returns: number of backends in the ODB 606 */ 607 //GIT_EXTERN 608 size_t git_odb_num_backends(libgit2_d.types.git_odb* odb); 609 610 /** 611 * Lookup an ODB backend object by index 612 * 613 * Params: 614 * out_ = output pointer to ODB backend at pos 615 * odb = object database 616 * pos = index into object database backend list 617 * 618 * Returns: 0 on success; git_error_code.GIT_ENOTFOUND if pos is invalid; other errors < 0 619 */ 620 //GIT_EXTERN 621 int git_odb_get_backend(libgit2_d.types.git_odb_backend** out_, libgit2_d.types.git_odb* odb, size_t pos); 622 623 /** @} */