Ything-RepoMirrors/libgit2
2
0
Fork 0
mirror of https://github.com/libgit2/libgit2.git synced 2026-01-25 11:06:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

refdb_backend: improve callback documentation

Browse Source 
The callbacks are currently sparsely documented, making it really hard
to implement a new backend without taking a look at the existing
refdb_fs backend. Add documentation to make this task hopefully easier
to achieve.
This commit is contained in:
Patrick Steinhardt
2020-03-26 09:41:09 +01:00
parent dd43571136
commit 3bbbe95a9f
1 changed files with 109 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
include/git2/sys/refdb_backend.h
View File

@@ -64,6 +64,12 @@ struct git_refdb_backend {
* 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 GIT_CALLBACK(exists)(
int *exists,
@@ -74,6 +80,13 @@ struct git_refdb_backend {
* 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 GIT_CALLBACK(lookup)(
git_reference **out,
@@ -84,6 +97,16 @@ struct git_refdb_backend {
* 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 GIT_CALLBACK(iterator)(
git_reference_iterator **iter,
@@ -94,6 +117,27 @@ struct git_refdb_backend {
* 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 GIT_CALLBACK(write)(git_refdb_backend *backend,
const git_reference *ref, int force,
@@ -104,6 +148,18 @@ struct git_refdb_backend {
* 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,
@@ -116,6 +172,16 @@ struct git_refdb_backend {
* 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 GIT_CALLBACK(del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target);
@@ -127,13 +193,21 @@ struct git_refdb_backend {
*
* 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 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 GIT_CALLBACK(has_log)(git_refdb_backend *backend, const char *refname);
@@ -142,6 +216,8 @@ struct git_refdb_backend {
* will be appended to on writes.
*
* A refdb implementation must provide this function.
*
* @return `0` on success, a negative error code otherwise
*/
int GIT_CALLBACK(ensure_log)(git_refdb_backend *backend, const char *refname);
@@ -157,6 +233,8 @@ struct git_refdb_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 GIT_CALLBACK(reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name);
@@ -164,6 +242,11 @@ struct git_refdb_backend {
* 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 GIT_CALLBACK(reflog_write)(git_refdb_backend *backend, git_reflog *reflog);
@@ -171,6 +254,10 @@ struct git_refdb_backend {
* 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 GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name);
@@ -178,16 +265,22 @@ struct git_refdb_backend {
* 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 GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name);
/**
* Lock a reference.
*
* The opaque parameter will be passed to the unlock function.
*
* 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);
@@ -200,6 +293,20 @@ struct git_refdb_backend {
*
* 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);