/**
* Return the current reference and advance the iterator.
*/
- int (*next)(
+ int GIT_CALLBACK(next)(
git_reference **ref,
git_reference_iterator *iter);
/**
* Return the name of the current reference and advance the iterator
*/
- int (*next_name)(
+ int GIT_CALLBACK(next_name)(
const char **ref_name,
git_reference_iterator *iter);
/**
* Free the iterator
*/
- void (*free)(
+ void GIT_CALLBACK(free)(
git_reference_iterator *iter);
};
/** An instance for a custom backend */
struct git_refdb_backend {
- unsigned int version;
+ unsigned int version; /**< The backend API version */
/**
- * Queries the refdb backend to determine if the given ref_name
- * exists. A refdb implementation must provide this function.
+ * Queries the refdb backend for the existence of a reference.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @arg exists The implementation shall set this to `0` if a ref does
+ * not exist, otherwise to `1`.
+ * @arg ref_name The reference's name that should be checked for
+ * existence.
+ * @return `0` on success, a negative error value code.
*/
- int (*exists)(
+ int GIT_CALLBACK(exists)(
int *exists,
git_refdb_backend *backend,
const char *ref_name);
/**
- * Queries the refdb backend for a given reference. A refdb
- * implementation must provide this function.
+ * Queries the refdb backend for a given reference.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @arg out The implementation shall set this to the allocated
+ * reference, if it could be found, otherwise to `NULL`.
+ * @arg ref_name The reference's name that should be checked for
+ * existence.
+ * @return `0` on success, `GIT_ENOTFOUND` if the reference does
+ * exist, otherwise a negative error code.
*/
- int (*lookup)(
+ int GIT_CALLBACK(lookup)(
git_reference **out,
git_refdb_backend *backend,
const char *ref_name);
* Allocate an iterator object for the backend.
*
* A refdb implementation must provide this function.
+ *
+ * @arg out The implementation shall set this to the allocated
+ * reference iterator. A custom structure may be used with an
+ * embedded `git_reference_iterator` structure. Both `next`
+ * and `next_name` functions of `git_reference_iterator` need
+ * to be populated.
+ * @arg glob A pattern to filter references by. If given, the iterator
+ * shall only return references that match the glob when
+ * passed to `wildmatch`.
+ * @return `0` on success, otherwise a negative error code.
*/
- int (*iterator)(
+ int GIT_CALLBACK(iterator)(
git_reference_iterator **iter,
struct git_refdb_backend *backend,
const char *glob);
- /*
- * Writes the given reference to the refdb. A refdb implementation
- * must provide this function.
+ /**
+ * Writes the given reference to the refdb.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @arg ref The reference to persist. May either be a symbolic or
+ * direct reference.
+ * @arg force Whether to write the reference if a reference with the
+ * same name already exists.
+ * @arg who The person updating the reference. Shall be used to create
+ * a reflog entry.
+ * @arg message The message detailing what kind of reference update is
+ * performed. Shall be used to create a reflog entry.
+ * @arg old If not `NULL` and `force` is not set, then the
+ * implementation needs to ensure that the reference is currently at
+ * the given OID before writing the new value. If both `old`
+ * and `old_target` are `NULL`, then the reference should not
+ * exist at the point of writing.
+ * @arg old_target If not `NULL` and `force` is not set, then the
+ * implementation needs to ensure that the symbolic
+ * reference is currently at the given target before
+ * writing the new value. If both `old` and
+ * `old_target` are `NULL`, then the reference should
+ * not exist at the point of writing.
+ * @return `0` on success, otherwise a negative error code.
*/
- int (*write)(git_refdb_backend *backend,
+ int GIT_CALLBACK(write)(git_refdb_backend *backend,
const git_reference *ref, int force,
const git_signature *who, const char *message,
const git_oid *old, const char *old_target);
- int (*rename)(
+ /**
+ * Rename a reference in the refdb.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @arg out The implementation shall set this to the newly created
+ * reference or `NULL` on error.
+ * @arg old_name The current name of the reference that is to be renamed.
+ * @arg new_name The new name that the old reference shall be renamed to.
+ * @arg force Whether to write the reference if a reference with the
+ * target name already exists.
+ * @arg who The person updating the reference. Shall be used to create
+ * a reflog entry.
+ * @arg message The message detailing what kind of reference update is
+ * performed. Shall be used to create a reflog entry.
+ * @return `0` on success, otherwise a negative error code.
+ */
+ int GIT_CALLBACK(rename)(
git_reference **out, git_refdb_backend *backend,
const char *old_name, const char *new_name, int force,
const git_signature *who, const char *message);
/**
- * Deletes the given reference from the refdb. A refdb implementation
- * must provide this function.
+ * Deletes the given reference from the refdb.
+ *
+ * If it exists, its reflog should be deleted as well.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @arg ref_name The name of the reference name that shall be deleted.
+ * @arg old_id If not `NULL` and `force` is not set, then the
+ * implementation needs to ensure that the reference is currently at
+ * the given OID before writing the new value.
+ * @arg old_target If not `NULL` and `force` is not set, then the
+ * implementation needs to ensure that the symbolic
+ * reference is currently at the given target before
+ * writing the new value.
+ * @return `0` on success, otherwise a negative error code.
*/
- int (*del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target);
+ int GIT_CALLBACK(del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target);
/**
* Suggests that the given refdb compress or optimize its references.
- * This mechanism is implementation specific. (For on-disk reference
- * databases, this may pack all loose references.) A refdb
- * implementation may provide this function; if it is not provided,
- * nothing will be done.
+ *
+ * This mechanism is implementation specific. For on-disk reference
+ * databases, this may pack all loose references.
+ *
+ * A refdb implementation may provide this function; if it is not
+ * provided, nothing will be done.
+ *
+ * @return `0` on success a negative error code otherwise
*/
- int (*compress)(git_refdb_backend *backend);
+ int GIT_CALLBACK(compress)(git_refdb_backend *backend);
/**
* Query whether a particular reference has a log (may be empty)
+ *
+ * Shall return 1 if it has a reflog, 0 it it doesn't and negative in
+ * case an error occurred.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @return `0` on success, `1` if the reflog for the given reference
+ * exists, a negative error code otherwise
*/
- int (*has_log)(git_refdb_backend *backend, const char *refname);
+ int GIT_CALLBACK(has_log)(git_refdb_backend *backend, const char *refname);
/**
* Make sure a particular reference will have a reflog which
* will be appended to on writes.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @return `0` on success, a negative error code otherwise
*/
- int (*ensure_log)(git_refdb_backend *backend, const char *refname);
+ int GIT_CALLBACK(ensure_log)(git_refdb_backend *backend, const char *refname);
/**
- * Frees any resources held by the refdb. A refdb implementation may
- * provide this function; if it is not provided, nothing will be done.
+ * Frees any resources held by the refdb (including the `git_refdb_backend`
+ * itself).
+ *
+ * A refdb backend implementation must provide this function.
*/
- void (*free)(git_refdb_backend *backend);
+ void GIT_CALLBACK(free)(git_refdb_backend *backend);
/**
* Read the reflog for the given reference name.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @return `0` on success, a negative error code otherwise
*/
- int (*reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name);
+ int GIT_CALLBACK(reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name);
/**
* Write a reflog to disk.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @arg reflog The complete reference log for a given reference. Note
+ * that this may contain entries that have already been
+ * written to disk.
+ * @return `0` on success, a negative error code otherwise
*/
- int (*reflog_write)(git_refdb_backend *backend, git_reflog *reflog);
+ int GIT_CALLBACK(reflog_write)(git_refdb_backend *backend, git_reflog *reflog);
/**
- * Rename a reflog
+ * Rename a reflog.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @arg old_name The name of old reference whose reflog shall be renamed from.
+ * @arg new_name The name of new reference whose reflog shall be renamed to.
+ * @return `0` on success, a negative error code otherwise
*/
- int (*reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name);
+ int GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name);
/**
* Remove a reflog.
+ *
+ * A refdb implementation must provide this function.
+ *
+ * @arg name The name of the reference whose reflog shall be deleted.
+ * @return `0` on success, a negative error code otherwise
*/
- int (*reflog_delete)(git_refdb_backend *backend, const char *name);
+ int GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name);
+
+ /**
+ * Lock a reference.
+ *
+ * A refdb implementation may provide this function; if it is not
+ * provided, the transaction API will fail to work.
+ *
+ * @arg payload_out Opaque parameter that will be passed verbosely to
+ * `unlock`.
+ * @arg refname Reference that shall be locked.
+ * @return `0` on success, a negative error code otherwise
+ */
+ int GIT_CALLBACK(lock)(void **payload_out, git_refdb_backend *backend, const char *refname);
+
+ /**
+ * Unlock a reference.
+ *
+ * Only one of target or symbolic_target will be set.
+ * `success` will be true if the reference should be update, false if
+ * the lock must be discarded.
+ *
+ * A refdb implementation must provide this function if a `lock`
+ * implementation is provided.
+ *
+ * @arg payload The payload returned by `lock`.
+ * @arg success `1` if a reference should be updated, `2` if
+ * a reference should be deleted, `0` if the lock must be
+ * discarded.
+ * @arg update_reflog `1` in case the reflog should be updated, `0`
+ * otherwise.
+ * @arg ref The reference which should be unlocked.
+ * @arg who The person updating the reference. Shall be used to create
+ * a reflog entry in case `update_reflog` is set.
+ * @arg message The message detailing what kind of reference update is
+ * performed. Shall be used to create a reflog entry in
+ * case `update_reflog` is set.
+ * @return `0` on success, a negative error code otherwise
+ */
+ int GIT_CALLBACK(unlock)(git_refdb_backend *backend, void *payload, int success, int update_reflog,
+ const git_reference *ref, const git_signature *sig, const char *message);
};
#define GIT_REFDB_BACKEND_VERSION 1
#define GIT_REFDB_BACKEND_INIT {GIT_REFDB_BACKEND_VERSION}
+/**
+ * Initializes a `git_refdb_backend` with default values. Equivalent to
+ * creating an instance with GIT_REFDB_BACKEND_INIT.
+ *
+ * @param backend the `git_refdb_backend` struct to initialize
+ * @param version Version of struct; pass `GIT_REFDB_BACKEND_VERSION`
+ * @return Zero on success; -1 on failure.
+ */
+GIT_EXTERN(int) git_refdb_init_backend(
+ git_refdb_backend *backend,
+ unsigned int version);
+
/**
* Constructors for default filesystem-based refdb backend
*
projects / libgit2.git / blobdiff