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