/*
* Copyright (C) the libgit2 contributors. All rights reserved.
*
* This file is part of libgit2, distributed under the GNU GPL v2 with
* a Linking Exception. For full terms see the included COPYING file.
*/
#ifndef INCLUDE_sys_git_refdb_backend_h__
#define INCLUDE_sys_git_refdb_backend_h__
#include "git2/common.h"
#include "git2/types.h"
#include "git2/oid.h"
/**
* @file git2/refdb_backend.h
* @brief Git custom refs backend functions
* @defgroup git_refdb_backend Git custom refs backend API
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
* Every backend's iterator must have a pointer to itself as the first
* element, so the API can talk to it. You'd define your iterator as
*
* struct my_iterator {
* git_reference_iterator parent;
* ...
* }
*
* and assign `iter->parent.backend` to your `git_refdb_backend`.
*/
struct git_reference_iterator {
git_refdb *db;
/**
* Return the current reference and advance the iterator.
*/
int GIT_CALLBACK(next)(
git_reference **ref,
git_reference_iterator *iter);
/**
* Return the name of the current reference and advance the iterator
*/
int GIT_CALLBACK(next_name)(
const char **ref_name,
git_reference_iterator *iter);
/**
* Free the iterator
*/
void GIT_CALLBACK(free)(
git_reference_iterator *iter);
};
/** An instance for a custom backend */
struct git_refdb_backend {
unsigned int version; /**< The backend API version */
/**
* Queries the refdb backend for the existence of a reference.
*
* A refdb implementation must provide this function.
*/
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.
*/
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.
*/
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.
*/
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);
/**
* Rename a reference in the refdb.
*
* A refdb implementation must provide this function.
*/
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.
*
* If it exists, its reflog should be deleted as well.
*
* A refdb implementation must provide this function.
*/
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.
*/
int GIT_CALLBACK(compress)(git_refdb_backend *backend);
/**
* Query whether a particular reference has a log (may be empty)
*
* A refdb implementation must provide this function.
*/
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.
*/
int GIT_CALLBACK(ensure_log)(git_refdb_backend *backend, const char *refname);
/**
* Frees any resources held by the refdb (including the `git_refdb_backend`
* itself).
*
* A refdb backend implementation must provide this function.
*/
void GIT_CALLBACK(free)(git_refdb_backend *backend);
/**
* Read the reflog for the given reference name.
*
* A refdb implementation must provide this function.
*/
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.
*/
int GIT_CALLBACK(reflog_write)(git_refdb_backend *backend, git_reflog *reflog);
/**
* Rename a reflog.
*
* A refdb implementation must provide this function.
*/
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.
*/
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.
*/
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.
*/
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
*
* Under normal usage, this is called for you when the repository is
* opened / created, but you can use this to explicitly construct a
* filesystem refdb backend for a repository.
*
* @param backend_out Output pointer to the git_refdb_backend object
* @param repo Git repository to access
* @return 0 on success, <0 error code on failure
*/
GIT_EXTERN(int) git_refdb_backend_fs(
git_refdb_backend **backend_out,
git_repository *repo);
/**
* Sets the custom backend to an existing reference DB
*
* The `git_refdb` will take ownership of the `git_refdb_backend` so you
* should NOT free it after calling this function.
*
* @param refdb database to add the backend to
* @param backend pointer to a git_refdb_backend instance
* @return 0 on success; error code otherwise
*/
GIT_EXTERN(int) git_refdb_set_backend(
git_refdb *refdb,
git_refdb_backend *backend);
GIT_END_DECL
#endif
