2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_sys_git_refdb_backend_h__
8 #define INCLUDE_sys_git_refdb_backend_h__
10 #include "git2/common.h"
11 #include "git2/types.h"
15 * @file git2/refdb_backend.h
16 * @brief Git custom refs backend functions
17 * @defgroup git_refdb_backend Git custom refs backend API
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
28 * struct my_iterator {
29 * git_reference_iterator parent;
33 * and assing `iter->parent.backend` to your `git_refdb_backend`.
35 struct git_reference_iterator
{
36 git_refdb_backend
*backend
;
39 /** An instance for a custom backend */
40 struct git_refdb_backend
{
44 * Queries the refdb backend to determine if the given ref_name
45 * exists. A refdb implementation must provide this function.
49 git_refdb_backend
*backend
,
50 const char *ref_name
);
53 * Queries the refdb backend for a given reference. A refdb
54 * implementation must provide this function.
58 git_refdb_backend
*backend
,
59 const char *ref_name
);
62 * Enumerates each reference in the refdb. A refdb implementation must
63 * provide this function.
66 git_refdb_backend
*backend
,
67 unsigned int list_flags
,
68 git_reference_foreach_cb callback
,
72 * Enumerates each reference in the refdb that matches the given
73 * glob string. A refdb implementation may provide this function;
74 * if it is not provided, foreach will be used and the results filtered
78 git_refdb_backend
*backend
,
80 unsigned int list_flags
,
81 git_reference_foreach_cb callback
,
85 * Allocate an iterator object for the backend
88 git_reference_iterator
**iter
,
89 struct git_refdb_backend
*backend
);
92 * Return the current value and advance the iterator.
96 git_reference_iterator
*iter
);
101 void (*iterator_free
)(
102 git_reference_iterator
*iter
);
104 * Writes the given reference to the refdb. A refdb implementation
105 * must provide this function.
107 int (*write
)(git_refdb_backend
*backend
, const git_reference
*ref
);
110 * Deletes the given reference from the refdb. A refdb implementation
111 * must provide this function.
113 int (*delete)(git_refdb_backend
*backend
, const git_reference
*ref
);
116 * Suggests that the given refdb compress or optimize its references.
117 * This mechanism is implementation specific. (For on-disk reference
118 * databases, this may pack all loose references.) A refdb
119 * implementation may provide this function; if it is not provided,
120 * nothing will be done.
122 int (*compress
)(git_refdb_backend
*backend
);
125 * Frees any resources held by the refdb. A refdb implementation may
126 * provide this function; if it is not provided, nothing will be done.
128 void (*free
)(git_refdb_backend
*backend
);
131 #define GIT_ODB_BACKEND_VERSION 1
132 #define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION}
135 * Constructors for default filesystem-based refdb backend
137 * Under normal usage, this is called for you when the repository is
138 * opened / created, but you can use this to explicitly construct a
139 * filesystem refdb backend for a repository.
141 * @param backend_out Output pointer to the git_refdb_backend object
142 * @param repo Git repository to access
143 * @return 0 on success, <0 error code on failure
145 GIT_EXTERN(int) git_refdb_backend_fs(
146 git_refdb_backend
**backend_out
,
147 git_repository
*repo
);
150 * Sets the custom backend to an existing reference DB
152 * The `git_refdb` will take ownership of the `git_refdb_backend` so you
153 * should NOT free it after calling this function.
155 * @param refdb database to add the backend to
156 * @param backend pointer to a git_refdb_backend instance
157 * @return 0 on success; error code otherwise
159 GIT_EXTERN(int) git_refdb_set_backend(
161 git_refdb_backend
*backend
);