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