rugged 1.3.1 → 1.9.0

data/vendor/libgit2/include/git2/odb.h

@@ -15,29 +15,91 @@
 
 /**
  * @file git2/odb.h
- * @brief Git object database routines
+ * @brief An object database manages the storage of git objects
  * @defgroup git_odb Git object database routines
  * @ingroup Git
  * @{
  */
 GIT_BEGIN_DECL
 
+/** Flags controlling the behavior of ODB lookup operations */
+typedef enum {
+	/**
+	 * Don't call `git_odb_refresh` if the lookup fails. Useful when doing
+	 * a batch of lookup operations for objects that may legitimately not
+	 * exist. When using this flag, you may wish to manually call
+	 * `git_odb_refresh` before processing a batch of objects.
+	 */
+	GIT_ODB_LOOKUP_NO_REFRESH = (1 << 0)
+} git_odb_lookup_flags_t;
+
 /**
  * Function type for callbacks from git_odb_foreach.
+ *
+ * @param id an id of an object in the object database
+ * @param payload the payload from the initial call to git_odb_foreach
+ * @return 0 on success, or an error code
  */
 typedef int GIT_CALLBACK(git_odb_foreach_cb)(const git_oid *id, void *payload);
 
+/** Options for configuring a loose object backend. */
+typedef struct {
+	unsigned int version; /**< version for the struct */
+
+	/**
+	 * Type of object IDs to use for this object database, or
+	 * 0 for default (currently SHA1).
+	 */
+	git_oid_t oid_type;
+} git_odb_options;
+
+/** The current version of the diff options structure */
+#define GIT_ODB_OPTIONS_VERSION 1
+
+/**
+ * Stack initializer for odb options.  Alternatively use
+ * `git_odb_options_init` programmatic initialization.
+ */
+#define GIT_ODB_OPTIONS_INIT { GIT_ODB_OPTIONS_VERSION }
+
+#ifdef GIT_EXPERIMENTAL_SHA256
+
+/**
+ * Create a new object database with no backends.
+ *
+ * @param[out] odb location to store the database pointer, if opened.
+ * @param opts the options for this object database or NULL for defaults
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_new(git_odb **odb, const git_odb_options *opts);
+
+/**
+ * Create a new object database and automatically add loose and packed
+ * backends.
+ *
+ * @param[out] odb_out location to store the database pointer, if opened.
+ *			Set to NULL if the open failed.
+ * @param objects_dir path of the backends' "objects" directory.
+ * @param opts the options for this object database or NULL for defaults
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_open(
+	git_odb **odb_out,
+	const char *objects_dir,
+	const git_odb_options *opts);
+
+#else
+
 /**
  * Create a new object database with no backends.
  *
  * Before the ODB can be used for read/writing, a custom database
  * backend must be manually added using `git_odb_add_backend()`
  *
- * @param out location to store the database pointer, if opened.
- *			Set to NULL if the open failed.
+ * @param[out] odb location to store the database pointer, if opened.
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_odb_new(git_odb **out);
+GIT_EXTERN(int) git_odb_new(git_odb **odb);
 
 /**
  * Create a new object database and automatically add
@@ -50,12 +112,13 @@ GIT_EXTERN(int) git_odb_new(git_odb **out);
  *		assuming `objects_dir` as the Objects folder which
  *		contains a 'pack/' folder with the corresponding data
  *
- * @param out location to store the database pointer, if opened.
+ * @param[out] odb_out location to store the database pointer, if opened.
  *			Set to NULL if the open failed.
  * @param objects_dir path of the backends' "objects" directory.
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir);
+GIT_EXTERN(int) git_odb_open(git_odb **odb_out, const char *objects_dir);
+#endif
 
 /**
  * Add an on-disk alternate to an existing Object DB.
@@ -91,13 +154,13 @@ GIT_EXTERN(void) git_odb_free(git_odb *db);
  * internally cached, so it should be closed
  * by the user once it's no longer in use.
  *
- * @param out pointer where to store the read object
+ * @param[out] obj pointer where to store the read object
  * @param db database to search for the object in.
  * @param id identity of the object to read.
  * @return 0 if the object was read, GIT_ENOTFOUND if the object is
  *         not in the database.
  */
-GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id);
+GIT_EXTERN(int) git_odb_read(git_odb_object **obj, git_odb *db, const git_oid *id);
 
 /**
  * Read an object from the database, given a prefix
@@ -106,7 +169,7 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i
  * This method queries all available ODB backends
  * trying to match the 'len' first hexadecimal
  * characters of the 'short_id'.
- * The remaining (GIT_OID_HEXSZ-len)*4 bits of
+ * The remaining (GIT_OID_SHA1_HEXSIZE-len)*4 bits of
  * 'short_id' must be 0s.
  * 'len' must be at least GIT_OID_MINPREFIXLEN,
  * and the prefix must be long enough to identify
@@ -117,7 +180,7 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i
  * internally cached, so it should be closed
  * by the user once it's no longer in use.
  *
- * @param out pointer where to store the read object
+ * @param[out] obj pointer where to store the read object
  * @param db database to search for the object in.
  * @param short_id a prefix of the id of the object to read.
  * @param len the length of the prefix
@@ -125,7 +188,7 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i
  *         database. GIT_EAMBIGUOUS if the prefix is ambiguous
  *         (several objects match the prefix)
  */
-GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git_oid *short_id, size_t len);
+GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **obj, git_odb *db, const git_oid *short_id, size_t len);
 
 /**
  * Read the header of an object from the database, without
@@ -137,8 +200,8 @@ GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git
  * of an object, so the whole object will be read and then the
  * header will be returned.
  *
- * @param len_out pointer where to store the length
- * @param type_out pointer where to store the type
+ * @param[out] len_out pointer where to store the length
+ * @param[out] type_out pointer where to store the type
  * @param db database to search for the object in.
  * @param id identity of the object to read.
  * @return 0 if the object was read, GIT_ENOTFOUND if the object is not
@@ -155,6 +218,17 @@ GIT_EXTERN(int) git_odb_read_header(size_t *len_out, git_object_t *type_out, git
  */
 GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id);
 
+/**
+ * Determine if the given object can be found in the object database, with
+ * extended options.
+ *
+ * @param db database to be searched for the given object.
+ * @param id the object to search for.
+ * @param flags flags affecting the lookup (see `git_odb_lookup_flags_t`)
+ * @return 1 if the object was found, 0 otherwise
+ */
+GIT_EXTERN(int) git_odb_exists_ext(git_odb *db, const git_oid *id, unsigned int flags);
+
 /**
  * Determine if an object can be found in the object database by an
  * abbreviated object ID.
@@ -192,12 +266,13 @@ typedef struct git_odb_expand_id {
 
 /**
  * Determine if one or more objects can be found in the object database
- * by their abbreviated object ID and type.  The given array will be
- * updated in place:  for each abbreviated ID that is unique in the
- * database, and of the given type (if specified), the full object ID,
- * object ID length (`GIT_OID_HEXSZ`) and type will be written back to
- * the array.  For IDs that are not found (or are ambiguous), the
- * array entry will be zeroed.
+ * by their abbreviated object ID and type.
+ *
+ * The given array will be updated in place: for each abbreviated ID that is
+ * unique in the database, and of the given type (if specified),
+ * the full object ID, object ID length (`GIT_OID_SHA1_HEXSIZE`) and type will be
+ * written back to the array. For IDs that are not found (or are ambiguous),
+ * the array entry will be zeroed.
  *
  * Note that since this function operates on multiple objects, the
  * underlying database will not be asked to be reloaded if an object is
@@ -231,7 +306,7 @@ GIT_EXTERN(int) git_odb_expand_ids(
  * @param db database to refresh
  * @return 0 on success, error code otherwise
  */
-GIT_EXTERN(int) git_odb_refresh(struct git_odb *db);
+GIT_EXTERN(int) git_odb_refresh(git_odb *db);
 
 /**
  * List all objects available in the database
@@ -246,7 +321,10 @@ GIT_EXTERN(int) git_odb_refresh(struct git_odb *db);
  * @param payload data to pass to the callback
  * @return 0 on success, non-zero callback return value, or error code
  */
-GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payload);
+GIT_EXTERN(int) git_odb_foreach(
+	git_odb *db,
+	git_odb_foreach_cb cb,
+	void *payload);
 
 /**
  * Write an object directly into the ODB
@@ -261,7 +339,7 @@ GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payloa
  *
  * @param out pointer to store the OID result of the write
  * @param odb object database where to store the object
- * @param data buffer with the data to store
+ * @param data @type `const unsigned char *` buffer with the data to store
  * @param len size of the buffer
  * @param type type of the data to store
  * @return 0 or an error code
@@ -323,6 +401,11 @@ GIT_EXTERN(int) git_odb_stream_finalize_write(git_oid *out, git_odb_stream *stre
  * Read from an odb stream
  *
  * Most backends don't implement streaming reads
+ *
+ * @param stream the stream
+ * @param buffer a user-allocated buffer to store the data in.
+ * @param len the buffer's length
+ * @return the number of bytes read if succeeded, error code otherwise
  */
 GIT_EXTERN(int) git_odb_stream_read(git_odb_stream *stream, char *buffer, size_t len);
 
@@ -383,6 +466,7 @@ GIT_EXTERN(int) git_odb_open_rstream(
  * Be aware that this is called inline with network and indexing operations,
  * so performance may be affected.
  * @param progress_payload payload for the progress callback
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_odb_write_pack(
 	git_odb_writepack **out,
@@ -400,23 +484,59 @@ GIT_EXTERN(int) git_odb_write_pack(
  * exist).
  *
  * @param db object database where the `multi-pack-index` file will be written.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_odb_write_multi_pack_index(
 	git_odb *db);
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+
 /**
- * Determine the object-ID (sha1 hash) of a data buffer
+ * Generate the object ID (in SHA1 or SHA256 format) for a given data buffer.
  *
- * The resulting SHA-1 OID will be the identifier for the data
- * buffer as if the data buffer it were to written to the ODB.
+ * @param[out] oid the resulting object ID.
+ * @param data data to hash
+ * @param len size of the data
+ * @param object_type of the data to hash
+ * @param oid_type the oid type to hash to
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_hash(
+	git_oid *oid,
+	const void *data,
+	size_t len,
+	git_object_t object_type,
+	git_oid_t oid_type);
+
+/**
+ * Determine the object ID of a file on disk.
+ *
+ * @param[out] oid oid structure the result is written into.
+ * @param path file to read and determine object id for
+ * @param object_type of the data to hash
+ * @param oid_type the oid type to hash to
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_hashfile(
+	git_oid *oid,
+	const char *path,
+	git_object_t object_type,
+	git_oid_t oid_type);
+#else
+
+/**
+ * Determine the object-ID (sha1 or sha256 hash) of a data buffer
+ *
+ * The resulting OID will be the identifier for the data buffer as if
+ * the data buffer it were to written to the ODB.
  *
- * @param out the resulting object-ID.
+ * @param[out] oid the resulting object-ID.
  * @param data data to hash
  * @param len size of the data
- * @param type of the data to hash
+ * @param object_type of the data to hash
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_object_t type);
+GIT_EXTERN(int) git_odb_hash(git_oid *oid, const void *data, size_t len, git_object_t object_type);
 
 /**
  * Read a file from disk and fill a git_oid with the object id
@@ -426,12 +546,14 @@ GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_obj
  * the `-w` flag, however, with the --no-filters flag.
  * If you need filters, see git_repository_hashfile.
  *
- * @param out oid structure the result is written into.
+ * @param[out] oid oid structure the result is written into.
  * @param path file to read and determine object id for
- * @param type the type of the object that will be hashed
+ * @param object_type of the data to hash
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_odb_hashfile(git_oid *out, const char *path, git_object_t type);
+GIT_EXTERN(int) git_odb_hashfile(git_oid *oid, const char *path, git_object_t object_type);
+
+#endif
 
 /**
  * Create a copy of an odb_object
@@ -476,7 +598,7 @@ GIT_EXTERN(const git_oid *) git_odb_object_id(git_odb_object *object);
  * This pointer is owned by the object and shall not be free'd.
  *
  * @param object the object
- * @return a pointer to the data
+ * @return @type `const unsigned char *` a pointer to the data
  */
 GIT_EXTERN(const void *) git_odb_object_data(git_odb_object *object);
 
@@ -556,7 +678,7 @@ GIT_EXTERN(int) git_odb_get_backend(git_odb_backend **out, git_odb *odb, size_t
 /**
  * Set the git commit-graph for the ODB.
  *
- * After a successfull call, the ownership of the cgraph parameter will be
+ * After a successful call, the ownership of the cgraph parameter will be
  * transferred to libgit2, and the caller should not free it.
  *
  * The commit-graph can also be unset by explicitly passing NULL as the cgraph
@@ -570,4 +692,5 @@ GIT_EXTERN(int) git_odb_set_commit_graph(git_odb *odb, git_commit_graph *cgraph)
 
 /** @} */
 GIT_END_DECL
+
 #endif

data/vendor/libgit2/include/git2/odb_backend.h

@@ -13,46 +13,135 @@
 
 /**
  * @file git2/backend.h
- * @brief Git custom backend functions
+ * @brief Object database backends manage the storage of git objects
  * @defgroup git_odb Git object database routines
  * @ingroup Git
  * @{
  */
 GIT_BEGIN_DECL
 
+/** Options for configuring a packfile object backend. */
+typedef struct {
+	unsigned int version; /**< version for the struct */
+
+	/**
+	 * Type of object IDs to use for this object database, or
+	 * 0 for default (currently SHA1).
+	 */
+	git_oid_t oid_type;
+} git_odb_backend_pack_options;
+
+/** The current version of the diff options structure */
+#define GIT_ODB_BACKEND_PACK_OPTIONS_VERSION 1
+
+/**
+ * Stack initializer for odb pack backend options.  Alternatively use
+ * `git_odb_backend_pack_options_init` programmatic initialization.
+ */
+#define GIT_ODB_BACKEND_PACK_OPTIONS_INIT \
+	{ GIT_ODB_BACKEND_PACK_OPTIONS_VERSION }
+
+typedef enum {
+	GIT_ODB_BACKEND_LOOSE_FSYNC = (1 << 0)
+} git_odb_backend_loose_flag_t;
+
+/** Options for configuring a loose object backend. */
+typedef struct {
+	unsigned int version; /**< version for the struct */
+
+	/** A combination of the `git_odb_backend_loose_flag_t` types. */
+	uint32_t flags;
+
+	/**
+	 * zlib compression level to use (0-9), where 1 is the fastest
+	 * at the expense of larger files, and 9 produces the best
+	 * compression at the expense of speed.  0 indicates that no
+	 * compression should be performed.  -1 is the default (currently
+	 * optimizing for speed).
+	 */
+	int compression_level;
+
+	/** Permissions to use creating a directory or 0 for defaults */
+	unsigned int dir_mode;
+
+	/** Permissions to use creating a file or 0 for defaults */
+	unsigned int file_mode;
+
+	/**
+	 * Type of object IDs to use for this object database, or
+	 * 0 for default (currently SHA1).
+	 */
+	git_oid_t oid_type;
+} git_odb_backend_loose_options;
+
+/** The current version of the diff options structure */
+#define GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION 1
+
+/**
+ * Stack initializer for odb loose backend options.  Alternatively use
+ * `git_odb_backend_loose_options_init` programmatic initialization.
+ */
+#define GIT_ODB_BACKEND_LOOSE_OPTIONS_INIT \
+	{ GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION, 0, -1 }
+
 /*
  * Constructors for in-box ODB backends.
  */
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+
 /**
- * Create a backend for the packfiles.
+ * Create a backend for a directory containing packfiles.
  *
- * @param out location to store the odb backend pointer
+ * @param[out] out location to store the odb backend pointer
  * @param objects_dir the Git repository's objects directory
+ * @param opts the options to use when creating the pack backend
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_backend_pack(
+	git_odb_backend **out,
+	const char *objects_dir,
+	const git_odb_backend_pack_options *opts);
+
+/**
+ * Create a backend for a single packfile.
  *
+ * @param[out] out location to store the odb backend pointer
+ * @param index_file path to the packfile's .idx file
+ * @param opts the options to use when creating the pack backend
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_odb_backend_pack(git_odb_backend **out, const char *objects_dir);
+GIT_EXTERN(int) git_odb_backend_one_pack(
+	git_odb_backend **out,
+	const char *index_file,
+	const git_odb_backend_pack_options *opts);
 
 /**
  * Create a backend for loose objects
  *
- * @param out location to store the odb backend pointer
+ * @param[out] out location to store the odb backend pointer
  * @param objects_dir the Git repository's objects directory
- * @param compression_level zlib compression level to use
- * @param do_fsync whether to do an fsync() after writing
- * @param dir_mode permissions to use creating a directory or 0 for defaults
- * @param file_mode permissions to use creating a file or 0 for defaults
+ * @param opts options for the loose object backend or NULL
  *
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_odb_backend_loose(
 	git_odb_backend **out,
 	const char *objects_dir,
-	int compression_level,
-	int do_fsync,
-	unsigned int dir_mode,
-	unsigned int file_mode);
+	git_odb_backend_loose_options *opts);
+
+#else
+
+/**
+ * Create a backend for a directory containing packfiles.
+ *
+ * @param[out] out location to store the odb backend pointer
+ * @param objects_dir the Git repository's objects directory
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_backend_pack(
+	git_odb_backend **out,
+	const char *objects_dir);
 
 /**
  * Create a backend out of a single packfile
@@ -60,18 +149,40 @@ GIT_EXTERN(int) git_odb_backend_loose(
  * This can be useful for inspecting the contents of a single
  * packfile.
  *
- * @param out location to store the odb backend pointer
+ * @param[out] out location to store the odb backend pointer
  * @param index_file path to the packfile's .idx file
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_backend_one_pack(
+	git_odb_backend **out,
+	const char *index_file);
+
+/**
+ * Create a backend for loose objects
  *
+ * @param[out] out location to store the odb backend pointer
+ * @param objects_dir the Git repository's objects directory
+ * @param compression_level zlib compression level (0-9), or -1 for the default
+ * @param do_fsync if non-zero, perform an fsync on write
+ * @param dir_mode permission to use when creating directories, or 0 for default
+ * @param file_mode permission to use when creating directories, or 0 for default
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_odb_backend_one_pack(git_odb_backend **out, const char *index_file);
+GIT_EXTERN(int) git_odb_backend_loose(
+	git_odb_backend **out,
+	const char *objects_dir,
+	int compression_level,
+	int do_fsync,
+	unsigned int dir_mode,
+	unsigned int file_mode);
+
+#endif
 
 /** Streaming mode */
 typedef enum {
 	GIT_STREAM_RDONLY = (1 << 1),
 	GIT_STREAM_WRONLY = (1 << 2),
-	GIT_STREAM_RW = (GIT_STREAM_RDONLY | GIT_STREAM_WRONLY),
+	GIT_STREAM_RW = (GIT_STREAM_RDONLY | GIT_STREAM_WRONLY)
 } git_odb_stream_t;
 
 /**
@@ -87,6 +198,10 @@ struct git_odb_stream {
 	unsigned int mode;
 	void *hash_ctx;
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+	git_oid_t oid_type;
+#endif
+
 	git_object_size_t declared_size;
 	git_object_size_t received_bytes;
 
@@ -130,6 +245,7 @@ struct git_odb_writepack {
 	void GIT_CALLBACK(free)(git_odb_writepack *writepack);
 };
 
+/** @} */
 GIT_END_DECL
 
 #endif