include/git2/odb.h

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