include/git2/sys/refdb_backend.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_sys_git_refdb_backend_h__
   8 #define INCLUDE_sys_git_refdb_backend_h__
   9
  10 #include "git2/common.h"
  11 #include "git2/types.h"
  12 #include "git2/oid.h"
  13
  14 /**
  15  * @file git2/refdb_backend.h
  16  * @brief Git custom refs backend functions
  17  * @defgroup git_refdb_backend Git custom refs backend API
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23
  24 /**
  25  * Every backend's iterator must have a pointer to itself as the first
  26  * element, so the API can talk to it. You'd define your iterator as
  27  *
  28  *     struct my_iterator {
  29  *             git_reference_iterator parent;
  30  *             ...
  31  *     }
  32  *
  33  * and assign `iter->parent.backend` to your `git_refdb_backend`.
  34  */
  35 struct git_reference_iterator {
  36         git_refdb *db;
  37
  38         /**
  39          * Return the current reference and advance the iterator.
  40          */
  41         int GIT_CALLBACK(next)(
  42                 git_reference **ref,
  43                 git_reference_iterator *iter);
  44
  45         /**
  46          * Return the name of the current reference and advance the iterator
  47          */
  48         int GIT_CALLBACK(next_name)(
  49                 const char **ref_name,
  50                 git_reference_iterator *iter);
  51
  52         /**
  53          * Free the iterator
  54          */
  55         void GIT_CALLBACK(free)(
  56                 git_reference_iterator *iter);
  57 };
  58
  59 /** An instance for a custom backend */
  60 struct git_refdb_backend {
  61         unsigned int version; /**< The backend API version */
  62
  63         /**
  64          * Queries the refdb backend for the existence of a reference.
  65          *
  66          * A refdb implementation must provide this function.
  67          */
  68         int GIT_CALLBACK(exists)(
  69                 int *exists,
  70                 git_refdb_backend *backend,
  71                 const char *ref_name);
  72
  73         /**
  74          * Queries the refdb backend for a given reference.
  75          *
  76          * A refdb implementation must provide this function.
  77          */
  78         int GIT_CALLBACK(lookup)(
  79                 git_reference **out,
  80                 git_refdb_backend *backend,
  81                 const char *ref_name);
  82
  83         /**
  84          * Allocate an iterator object for the backend.
  85          *
  86          * A refdb implementation must provide this function.
  87          */
  88         int GIT_CALLBACK(iterator)(
  89                 git_reference_iterator **iter,
  90                 struct git_refdb_backend *backend,
  91                 const char *glob);
  92
  93         /**
  94          * Writes the given reference to the refdb.
  95          *
  96          * A refdb implementation must provide this function.
  97          */
  98         int GIT_CALLBACK(write)(git_refdb_backend *backend,
  99                      const git_reference *ref, int force,
 100                      const git_signature *who, const char *message,
 101                      const git_oid *old, const char *old_target);
 102
 103         /**
 104          * Rename a reference in the refdb.
 105          *
 106          * A refdb implementation must provide this function.
 107          */
 108         int GIT_CALLBACK(rename)(
 109                 git_reference **out, git_refdb_backend *backend,
 110                 const char *old_name, const char *new_name, int force,
 111                 const git_signature *who, const char *message);
 112
 113         /**
 114          * Deletes the given reference from the refdb.
 115          *
 116          * If it exists, its reflog should be deleted as well.
 117          *
 118          * A refdb implementation must provide this function.
 119          */
 120         int GIT_CALLBACK(del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target);
 121
 122         /**
 123          * Suggests that the given refdb compress or optimize its references.
 124          *
 125          * This mechanism is implementation specific. For on-disk reference
 126          * databases, this may pack all loose references.
 127          *
 128          * A refdb implementation may provide this function; if it is not
 129          * provided, nothing will be done.
 130          */
 131         int GIT_CALLBACK(compress)(git_refdb_backend *backend);
 132
 133         /**
 134          * Query whether a particular reference has a log (may be empty)
 135          *
 136          * A refdb implementation must provide this function.
 137          */
 138         int GIT_CALLBACK(has_log)(git_refdb_backend *backend, const char *refname);
 139
 140         /**
 141          * Make sure a particular reference will have a reflog which
 142          * will be appended to on writes.
 143          *
 144          * A refdb implementation must provide this function.
 145          */
 146         int GIT_CALLBACK(ensure_log)(git_refdb_backend *backend, const char *refname);
 147
 148         /**
 149          * Frees any resources held by the refdb (including the `git_refdb_backend`
 150          * itself).
 151          *
 152          * A refdb backend implementation must provide this function.
 153          */
 154         void GIT_CALLBACK(free)(git_refdb_backend *backend);
 155
 156         /**
 157          * Read the reflog for the given reference name.
 158          *
 159          * A refdb implementation must provide this function.
 160          */
 161         int GIT_CALLBACK(reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name);
 162
 163         /**
 164          * Write a reflog to disk.
 165          *
 166          * A refdb implementation must provide this function.
 167          */
 168         int GIT_CALLBACK(reflog_write)(git_refdb_backend *backend, git_reflog *reflog);
 169
 170         /**
 171          * Rename a reflog.
 172          *
 173          * A refdb implementation must provide this function.
 174          */
 175         int GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name);
 176
 177         /**
 178          * Remove a reflog.
 179          *
 180          * A refdb implementation must provide this function.
 181          */
 182         int GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name);
 183
 184         /**
 185          * Lock a reference.
 186          *
 187          * The opaque parameter will be passed to the unlock function.
 188          *
 189          * A refdb implementation may provide this function; if it is not
 190          * provided, the transaction API will fail to work.
 191          */
 192         int GIT_CALLBACK(lock)(void **payload_out, git_refdb_backend *backend, const char *refname);
 193
 194         /**
 195          * Unlock a reference.
 196          *
 197          * Only one of target or symbolic_target will be set.
 198          * `success` will be true if the reference should be update, false if
 199          * the lock must be discarded.
 200          *
 201          * A refdb implementation must provide this function if a `lock`
 202          * implementation is provided.
 203          */
 204         int GIT_CALLBACK(unlock)(git_refdb_backend *backend, void *payload, int success, int update_reflog,
 205                       const git_reference *ref, const git_signature *sig, const char *message);
 206 };
 207
 208 #define GIT_REFDB_BACKEND_VERSION 1
 209 #define GIT_REFDB_BACKEND_INIT {GIT_REFDB_BACKEND_VERSION}
 210
 211 /**
 212  * Initializes a `git_refdb_backend` with default values. Equivalent to
 213  * creating an instance with GIT_REFDB_BACKEND_INIT.
 214  *
 215  * @param backend the `git_refdb_backend` struct to initialize
 216  * @param version Version of struct; pass `GIT_REFDB_BACKEND_VERSION`
 217  * @return Zero on success; -1 on failure.
 218  */
 219 GIT_EXTERN(int) git_refdb_init_backend(
 220         git_refdb_backend *backend,
 221         unsigned int version);
 222
 223 /**
 224  * Constructors for default filesystem-based refdb backend
 225  *
 226  * Under normal usage, this is called for you when the repository is
 227  * opened / created, but you can use this to explicitly construct a
 228  * filesystem refdb backend for a repository.
 229  *
 230  * @param backend_out Output pointer to the git_refdb_backend object
 231  * @param repo Git repository to access
 232  * @return 0 on success, <0 error code on failure
 233  */
 234 GIT_EXTERN(int) git_refdb_backend_fs(
 235         git_refdb_backend **backend_out,
 236         git_repository *repo);
 237
 238 /**
 239  * Sets the custom backend to an existing reference DB
 240  *
 241  * The `git_refdb` will take ownership of the `git_refdb_backend` so you
 242  * should NOT free it after calling this function.
 243  *
 244  * @param refdb database to add the backend to
 245  * @param backend pointer to a git_refdb_backend instance
 246  * @return 0 on success; error code otherwise
 247  */
 248 GIT_EXTERN(int) git_refdb_set_backend(
 249         git_refdb *refdb,
 250         git_refdb_backend *backend);
 251
 252 GIT_END_DECL
 253
 254 #endif