]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
f5918330 | 3 | * |
bb742ede VM |
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. | |
f5918330 | 6 | */ |
3315782c VM |
7 | #ifndef INCLUDE_git_repository_h__ |
8 | #define INCLUDE_git_repository_h__ | |
9 | ||
10 | #include "common.h" | |
d12299fe VM |
11 | #include "types.h" |
12 | #include "oid.h" | |
7a3bd1e7 | 13 | #include "buffer.h" |
3315782c VM |
14 | |
15 | /** | |
f5918330 | 16 | * @file git2/repository.h |
d12299fe VM |
17 | * @brief Git repository management routines |
18 | * @defgroup git_repository Git repository management routines | |
3315782c VM |
19 | * @ingroup Git |
20 | * @{ | |
21 | */ | |
22 | GIT_BEGIN_DECL | |
23 | ||
24 | /** | |
6fd195d7 | 25 | * Open a git repository. |
3315782c | 26 | * |
9462c471 VM |
27 | * The 'path' argument must point to either a git repository |
28 | * folder, or an existing work dir. | |
3315782c | 29 | * |
9462c471 VM |
30 | * The method will automatically detect if 'path' is a normal |
31 | * or bare repository or fail is 'path' is neither. | |
6fd195d7 | 32 | * |
c9fc4a6f | 33 | * @param out pointer to the repo which will be opened |
6fd195d7 | 34 | * @param path the path to the repository |
e172cf08 | 35 | * @return 0 or an error code |
3315782c | 36 | */ |
c9fc4a6f | 37 | GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path); |
8c8d726e PS |
38 | /** |
39 | * Open working tree as a repository | |
40 | * | |
41 | * Open the working directory of the working tree as a normal | |
42 | * repository that can then be worked on. | |
43 | * | |
44 | * @param out Output pointer containing opened repository | |
45 | * @param wt Working tree to open | |
46 | * @return 0 or an error code | |
47 | */ | |
48 | GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_worktree *wt); | |
3315782c | 49 | |
6782245e CMN |
50 | /** |
51 | * Create a "fake" repository to wrap an object database | |
52 | * | |
53 | * Create a repository object to wrap an object database to be used | |
54 | * with the API when all you have is an object database. This doesn't | |
55 | * have any paths associated with it, so use with care. | |
56 | * | |
c9fc4a6f | 57 | * @param out pointer to the repo |
6782245e CMN |
58 | * @param odb the object database to wrap |
59 | * @return 0 or an error code | |
60 | */ | |
c9fc4a6f | 61 | GIT_EXTERN(int) git_repository_wrap_odb(git_repository **out, git_odb *odb); |
6782245e | 62 | |
fd0574e5 | 63 | /** |
9462c471 VM |
64 | * Look for a git repository and copy its path in the given buffer. |
65 | * The lookup start from base_path and walk across parent directories | |
66 | * if nothing has been found. The lookup ends when the first repository | |
67 | * is found, or when reaching a directory referenced in ceiling_dirs | |
68 | * or when the filesystem changes (in case across_fs is true). | |
fd0574e5 | 69 | * |
9462c471 VM |
70 | * The method will automatically detect if the repository is bare |
71 | * (if there is a repository). | |
fd0574e5 | 72 | * |
7a3bd1e7 CMN |
73 | * @param out A pointer to a user-allocated git_buf which will contain |
74 | * the found path. | |
fd0574e5 RG |
75 | * |
76 | * @param start_path The base path where the lookup starts. | |
77 | * | |
9462c471 VM |
78 | * @param across_fs If true, then the lookup will not stop when a |
79 | * filesystem device change is detected while exploring parent directories. | |
fd0574e5 | 80 | * |
9462c471 VM |
81 | * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR separated list of |
82 | * absolute symbolic link free paths. The lookup will stop when any | |
83 | * of this paths is reached. Note that the lookup always performs on | |
84 | * start_path no matter start_path appears in ceiling_dirs ceiling_dirs | |
85 | * might be NULL (which is equivalent to an empty string) | |
fd0574e5 | 86 | * |
e172cf08 | 87 | * @return 0 or an error code |
fd0574e5 | 88 | */ |
9462c471 | 89 | GIT_EXTERN(int) git_repository_discover( |
7a3bd1e7 | 90 | git_buf *out, |
9462c471 VM |
91 | const char *start_path, |
92 | int across_fs, | |
93 | const char *ceiling_dirs); | |
6fd195d7 | 94 | |
662880ca RB |
95 | /** |
96 | * Option flags for `git_repository_open_ext`. | |
662880ca | 97 | */ |
c9fc4a6f | 98 | typedef enum { |
ac3d33df JK |
99 | /** |
100 | * Only open the repository if it can be immediately found in the | |
101 | * start_path. Do not walk up from the start_path looking at parent | |
102 | * directories. | |
103 | */ | |
7784bcbb | 104 | GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0), |
ac3d33df JK |
105 | |
106 | /** | |
107 | * Unless this flag is set, open will not continue searching across | |
108 | * filesystem boundaries (i.e. when `st_dev` changes from the `stat` | |
109 | * system call). For example, searching in a user's home directory at | |
110 | * "/home/user/source/" will not return "/.git/" as the found repo if | |
111 | * "/" is a different filesystem than "/home". | |
112 | */ | |
7784bcbb | 113 | GIT_REPOSITORY_OPEN_CROSS_FS = (1 << 1), |
ac3d33df JK |
114 | |
115 | /** | |
116 | * Open repository as a bare repo regardless of core.bare config, and | |
117 | * defer loading config file for faster setup. | |
118 | * Unlike `git_repository_open_bare`, this can follow gitlinks. | |
119 | */ | |
3fe046cf | 120 | GIT_REPOSITORY_OPEN_BARE = (1 << 2), |
ac3d33df JK |
121 | |
122 | /** | |
123 | * Do not check for a repository by appending /.git to the start_path; | |
124 | * only open the repository if start_path itself points to the git | |
125 | * directory. | |
126 | */ | |
39c6fca3 | 127 | GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3), |
ac3d33df JK |
128 | |
129 | /** | |
130 | * Find and open a git repository, respecting the environment variables | |
131 | * used by the git command-line tools. | |
132 | * If set, `git_repository_open_ext` will ignore the other flags and | |
133 | * the `ceiling_dirs` argument, and will allow a NULL `path` to use | |
134 | * `GIT_DIR` or search from the current directory. | |
135 | * The search for a repository will respect $GIT_CEILING_DIRECTORIES and | |
136 | * $GIT_DISCOVERY_ACROSS_FILESYSTEM. The opened repository will | |
137 | * respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and | |
138 | * $GIT_ALTERNATE_OBJECT_DIRECTORIES. | |
139 | * In the future, this flag will also cause `git_repository_open_ext` | |
140 | * to respect $GIT_WORK_TREE and $GIT_COMMON_DIR; currently, | |
141 | * `git_repository_open_ext` with this flag will error out if either | |
142 | * $GIT_WORK_TREE or $GIT_COMMON_DIR is set. | |
143 | */ | |
0dd98b69 | 144 | GIT_REPOSITORY_OPEN_FROM_ENV = (1 << 4), |
f4a62c30 | 145 | } git_repository_open_flag_t; |
7784bcbb RB |
146 | |
147 | /** | |
148 | * Find and open a repository with extended controls. | |
662880ca | 149 | * |
c9fc4a6f | 150 | * @param out Pointer to the repo which will be opened. This can |
662880ca RB |
151 | * actually be NULL if you only want to use the error code to |
152 | * see if a repo at this path could be opened. | |
c9fc4a6f | 153 | * @param path Path to open as git repository. If the flags |
662880ca | 154 | * permit "searching", then this can be a path to a subdirectory |
0dd98b69 JT |
155 | * inside the working directory of the repository. May be NULL if |
156 | * flags is GIT_REPOSITORY_OPEN_FROM_ENV. | |
662880ca RB |
157 | * @param flags A combination of the GIT_REPOSITORY_OPEN flags above. |
158 | * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR delimited list of path | |
159 | * prefixes at which the search for a containing repository should | |
160 | * terminate. | |
161 | * @return 0 on success, GIT_ENOTFOUND if no repository could be found, | |
162 | * or -1 if there was a repository but open failed for some reason | |
163 | * (such as repo corruption or system errors). | |
7784bcbb RB |
164 | */ |
165 | GIT_EXTERN(int) git_repository_open_ext( | |
c9fc4a6f BS |
166 | git_repository **out, |
167 | const char *path, | |
168 | unsigned int flags, | |
7784bcbb RB |
169 | const char *ceiling_dirs); |
170 | ||
a442ed68 VM |
171 | /** |
172 | * Open a bare repository on the serverside. | |
173 | * | |
174 | * This is a fast open for bare repositories that will come in handy | |
175 | * if you're e.g. hosting git repositories and need to access them | |
176 | * efficiently | |
177 | * | |
178 | * @param out Pointer to the repo which will be opened. | |
179 | * @param bare_path Direct path to the bare repository | |
180 | * @return 0 on success, or an error code | |
181 | */ | |
437d3666 | 182 | GIT_EXTERN(int) git_repository_open_bare(git_repository **out, const char *bare_path); |
a442ed68 | 183 | |
3315782c VM |
184 | /** |
185 | * Free a previously allocated repository | |
6b2a1941 | 186 | * |
f0d08b7c VM |
187 | * Note that after a repository is free'd, all the objects it has spawned |
188 | * will still exist until they are manually closed by the user | |
45e79e37 | 189 | * with `git_object_free`, but accessing any of the attributes of |
f0d08b7c VM |
190 | * an object without a backing repository will result in undefined |
191 | * behavior | |
192 | * | |
3315782c VM |
193 | * @param repo repository handle to close. If NULL nothing occurs. |
194 | */ | |
195 | GIT_EXTERN(void) git_repository_free(git_repository *repo); | |
196 | ||
e1f8cad0 | 197 | /** |
40c44d2f | 198 | * Creates a new Git repository in the given folder. |
e1f8cad0 | 199 | * |
40c44d2f VM |
200 | * TODO: |
201 | * - Reinit the repository | |
e1f8cad0 | 202 | * |
c9fc4a6f | 203 | * @param out pointer to the repo which will be created or reinitialized |
e1f8cad0 | 204 | * @param path the path to the repository |
662880ca RB |
205 | * @param is_bare if true, a Git repository without a working directory is |
206 | * created at the pointed path. If false, provided path will be | |
207 | * considered as the working directory into which the .git directory | |
208 | * will be created. | |
40c44d2f | 209 | * |
e172cf08 | 210 | * @return 0 or an error code |
e1f8cad0 | 211 | */ |
662880ca | 212 | GIT_EXTERN(int) git_repository_init( |
c9fc4a6f | 213 | git_repository **out, |
662880ca RB |
214 | const char *path, |
215 | unsigned is_bare); | |
216 | ||
217 | /** | |
218 | * Option flags for `git_repository_init_ext`. | |
219 | * | |
220 | * These flags configure extra behaviors to `git_repository_init_ext`. | |
221 | * In every case, the default behavior is the zero value (i.e. flag is | |
222 | * not set). Just OR the flag values together for the `flags` parameter | |
223 | * when initializing a new repo. Details of individual values are: | |
224 | * | |
225 | * * BARE - Create a bare repository with no working directory. | |
0b170f4d | 226 | * * NO_REINIT - Return an GIT_EEXISTS error if the repo_path appears to |
662880ca RB |
227 | * already be an git repository. |
228 | * * NO_DOTGIT_DIR - Normally a "/.git/" will be appended to the repo | |
229 | * path for non-bare repos (if it is not already there), but | |
230 | * passing this flag prevents that behavior. | |
231 | * * MKDIR - Make the repo_path (and workdir_path) as needed. Init is | |
232 | * always willing to create the ".git" directory even without this | |
233 | * flag. This flag tells init to create the trailing component of | |
234 | * the repo and workdir paths as needed. | |
235 | * * MKPATH - Recursively make all components of the repo and workdir | |
236 | * paths as necessary. | |
237 | * * EXTERNAL_TEMPLATE - libgit2 normally uses internal templates to | |
238 | * initialize a new repo. This flags enables external templates, | |
239 | * looking the "template_path" from the options if set, or the | |
240 | * `init.templatedir` global config if not, or falling back on | |
241 | * "/usr/share/git-core/templates" if it exists. | |
bc737620 JM |
242 | * * GIT_REPOSITORY_INIT_RELATIVE_GITLINK - If an alternate workdir is |
243 | * specified, use relative paths for the gitdir and core.worktree. | |
662880ca | 244 | */ |
f4a62c30 | 245 | typedef enum { |
662880ca RB |
246 | GIT_REPOSITORY_INIT_BARE = (1u << 0), |
247 | GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1), | |
248 | GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2), | |
249 | GIT_REPOSITORY_INIT_MKDIR = (1u << 3), | |
250 | GIT_REPOSITORY_INIT_MKPATH = (1u << 4), | |
251 | GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5), | |
bc737620 | 252 | GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6), |
f4a62c30 | 253 | } git_repository_init_flag_t; |
ca1b6e54 RB |
254 | |
255 | /** | |
256 | * Mode options for `git_repository_init_ext`. | |
257 | * | |
258 | * Set the mode field of the `git_repository_init_options` structure | |
259 | * either to the custom mode that you would like, or to one of the | |
260 | * following modes: | |
261 | * | |
262 | * * SHARED_UMASK - Use permissions configured by umask - the default. | |
263 | * * SHARED_GROUP - Use "--shared=group" behavior, chmod'ing the new repo | |
264 | * to be group writable and "g+sx" for sticky group assignment. | |
265 | * * SHARED_ALL - Use "--shared=all" behavior, adding world readability. | |
266 | * * Anything else - Set to custom value. | |
267 | */ | |
f4a62c30 | 268 | typedef enum { |
ca1b6e54 RB |
269 | GIT_REPOSITORY_INIT_SHARED_UMASK = 0, |
270 | GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775, | |
271 | GIT_REPOSITORY_INIT_SHARED_ALL = 0002777, | |
f4a62c30 | 272 | } git_repository_init_mode_t; |
662880ca RB |
273 | |
274 | /** | |
275 | * Extended options structure for `git_repository_init_ext`. | |
276 | * | |
277 | * This contains extra options for `git_repository_init_ext` that enable | |
278 | * additional initialization features. The fields are: | |
279 | * | |
280 | * * flags - Combination of GIT_REPOSITORY_INIT flags above. | |
ca1b6e54 RB |
281 | * * mode - Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... |
282 | * constants above, or to a custom value that you would like. | |
662880ca | 283 | * * workdir_path - The path to the working dir or NULL for default (i.e. |
ca1b6e54 RB |
284 | * repo_path parent on non-bare repos). IF THIS IS RELATIVE PATH, |
285 | * IT WILL BE EVALUATED RELATIVE TO THE REPO_PATH. If this is not | |
286 | * the "natural" working directory, a .git gitlink file will be | |
287 | * created here linking to the repo_path. | |
662880ca RB |
288 | * * description - If set, this will be used to initialize the "description" |
289 | * file in the repository, instead of using the template content. | |
290 | * * template_path - When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set, | |
291 | * this contains the path to use for the template directory. If | |
292 | * this is NULL, the config or default directory options will be | |
293 | * used instead. | |
294 | * * initial_head - The name of the head to point HEAD at. If NULL, then | |
295 | * this will be treated as "master" and the HEAD ref will be set | |
296 | * to "refs/heads/master". If this begins with "refs/" it will be | |
297 | * used verbatim; otherwise "refs/heads/" will be prefixed. | |
298 | * * origin_url - If this is non-NULL, then after the rest of the | |
299 | * repository initialization is completed, an "origin" remote | |
300 | * will be added pointing to this URL. | |
301 | */ | |
ca94e031 | 302 | typedef struct { |
bde336ea | 303 | unsigned int version; |
662880ca RB |
304 | uint32_t flags; |
305 | uint32_t mode; | |
306 | const char *workdir_path; | |
307 | const char *description; | |
308 | const char *template_path; | |
309 | const char *initial_head; | |
310 | const char *origin_url; | |
311 | } git_repository_init_options; | |
312 | ||
bde336ea | 313 | #define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1 |
fac43c54 | 314 | #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION} |
bde336ea | 315 | |
b9f81997 | 316 | /** |
ac3d33df JK |
317 | * Initialize git_repository_init_options structure |
318 | * | |
319 | * Initializes a `git_repository_init_options` with default values. Equivalent to | |
320 | * creating an instance with `GIT_REPOSITORY_INIT_OPTIONS_INIT`. | |
b9f81997 | 321 | * |
ac3d33df JK |
322 | * @param opts The `git_repository_init_options` struct to initialize. |
323 | * @param version The struct version; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`. | |
b9f81997 MB |
324 | * @return Zero on success; -1 on failure. |
325 | */ | |
0c9c969a | 326 | GIT_EXTERN(int) git_repository_init_options_init( |
702efc89 RB |
327 | git_repository_init_options *opts, |
328 | unsigned int version); | |
b9f81997 | 329 | |
662880ca RB |
330 | /** |
331 | * Create a new Git repository in the given folder with extended controls. | |
332 | * | |
333 | * This will initialize a new git repository (creating the repo_path | |
334 | * if requested by flags) and working directory as needed. It will | |
335 | * auto-detect the case sensitivity of the file system and if the | |
336 | * file system supports file mode bits correctly. | |
337 | * | |
c9fc4a6f | 338 | * @param out Pointer to the repo which will be created or reinitialized. |
662880ca RB |
339 | * @param repo_path The path to the repository. |
340 | * @param opts Pointer to git_repository_init_options struct. | |
341 | * @return 0 or an error code on failure. | |
342 | */ | |
343 | GIT_EXTERN(int) git_repository_init_ext( | |
c9fc4a6f | 344 | git_repository **out, |
662880ca RB |
345 | const char *repo_path, |
346 | git_repository_init_options *opts); | |
4b8e27c8 | 347 | |
3601c4bf | 348 | /** |
349 | * Retrieve and resolve the reference pointed at by HEAD. | |
350 | * | |
ca94e031 RB |
351 | * The returned `git_reference` will be owned by caller and |
352 | * `git_reference_free()` must be called when done with it to release the | |
353 | * allocated memory and prevent a leak. | |
354 | * | |
c9fc4a6f | 355 | * @param out pointer to the reference which will be retrieved |
3601c4bf | 356 | * @param repo a repository object |
357 | * | |
605da51a | 358 | * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing |
b1a3a70e | 359 | * branch, GIT_ENOTFOUND when HEAD is missing; an error code otherwise |
3601c4bf | 360 | */ |
c9fc4a6f | 361 | GIT_EXTERN(int) git_repository_head(git_reference **out, git_repository *repo); |
3601c4bf | 362 | |
04fb12ab PS |
363 | /** |
364 | * Retrieve the referenced HEAD for the worktree | |
365 | * | |
366 | * @param out pointer to the reference which will be retrieved | |
367 | * @param repo a repository object | |
368 | * @param name name of the worktree to retrieve HEAD for | |
369 | * @return 0 when successful, error-code otherwise | |
370 | */ | |
371 | GIT_EXTERN(int) git_repository_head_for_worktree(git_reference **out, git_repository *repo, | |
372 | const char *name); | |
373 | ||
35502d2e CMN |
374 | /** |
375 | * Check if a repository's HEAD is detached | |
376 | * | |
377 | * A repository's HEAD is detached when it points directly to a commit | |
378 | * instead of a branch. | |
379 | * | |
380 | * @param repo Repo to test | |
d73c94b2 | 381 | * @return 1 if HEAD is detached, 0 if it's not; error code if there |
35502d2e CMN |
382 | * was an error. |
383 | */ | |
408d733b | 384 | GIT_EXTERN(int) git_repository_head_detached(git_repository *repo); |
35502d2e | 385 | |
ac3d33df | 386 | /** |
04fb12ab PS |
387 | * Check if a worktree's HEAD is detached |
388 | * | |
389 | * A worktree's HEAD is detached when it points directly to a | |
390 | * commit instead of a branch. | |
391 | * | |
392 | * @param repo a repository object | |
393 | * @param name name of the worktree to retrieve HEAD for | |
394 | * @return 1 if HEAD is detached, 0 if its not; error code if | |
395 | * there was an error | |
396 | */ | |
397 | GIT_EXTERN(int) git_repository_head_detached_for_worktree(git_repository *repo, | |
398 | const char *name); | |
399 | ||
35502d2e | 400 | /** |
605da51a | 401 | * Check if the current branch is unborn |
35502d2e | 402 | * |
605da51a | 403 | * An unborn branch is one named from HEAD but which doesn't exist in |
35502d2e CMN |
404 | * the refs namespace, because it doesn't have any commit to point to. |
405 | * | |
406 | * @param repo Repo to test | |
605da51a | 407 | * @return 1 if the current branch is unborn, 0 if it's not; error |
d73c94b2 | 408 | * code if there was an error |
35502d2e | 409 | */ |
605da51a | 410 | GIT_EXTERN(int) git_repository_head_unborn(git_repository *repo); |
35502d2e | 411 | |
41233c40 VM |
412 | /** |
413 | * Check if a repository is empty | |
414 | * | |
9a294fd8 POL |
415 | * An empty repository has just been initialized and contains no references |
416 | * apart from HEAD, which must be pointing to the unborn master branch. | |
41233c40 VM |
417 | * |
418 | * @param repo Repo to test | |
419 | * @return 1 if the repository is empty, 0 if it isn't, error code | |
420 | * if the repository is corrupted | |
421 | */ | |
422 | GIT_EXTERN(int) git_repository_is_empty(git_repository *repo); | |
423 | ||
cb3269c9 PS |
424 | /** |
425 | * List of items which belong to the git repository layout | |
426 | */ | |
427 | typedef enum { | |
428 | GIT_REPOSITORY_ITEM_GITDIR, | |
429 | GIT_REPOSITORY_ITEM_WORKDIR, | |
430 | GIT_REPOSITORY_ITEM_COMMONDIR, | |
431 | GIT_REPOSITORY_ITEM_INDEX, | |
432 | GIT_REPOSITORY_ITEM_OBJECTS, | |
433 | GIT_REPOSITORY_ITEM_REFS, | |
434 | GIT_REPOSITORY_ITEM_PACKED_REFS, | |
435 | GIT_REPOSITORY_ITEM_REMOTES, | |
436 | GIT_REPOSITORY_ITEM_CONFIG, | |
437 | GIT_REPOSITORY_ITEM_INFO, | |
438 | GIT_REPOSITORY_ITEM_HOOKS, | |
439 | GIT_REPOSITORY_ITEM_LOGS, | |
440 | GIT_REPOSITORY_ITEM_MODULES, | |
0c9c969a UG |
441 | GIT_REPOSITORY_ITEM_WORKTREES, |
442 | GIT_REPOSITORY_ITEM__LAST | |
cb3269c9 PS |
443 | } git_repository_item_t; |
444 | ||
445 | /** | |
446 | * Get the location of a specific repository file or directory | |
447 | * | |
448 | * This function will retrieve the path of a specific repository | |
449 | * item. It will thereby honor things like the repository's | |
450 | * common directory, gitdir, etc. In case a file path cannot | |
451 | * exist for a given item (e.g. the working directory of a bare | |
9d49a43c | 452 | * repository), GIT_ENOTFOUND is returned. |
cb3269c9 PS |
453 | * |
454 | * @param out Buffer to store the path at | |
455 | * @param repo Repository to get path for | |
456 | * @param item The repository item for which to retrieve the path | |
9d49a43c | 457 | * @return 0, GIT_ENOTFOUND if the path cannot exist or an error code |
cb3269c9 | 458 | */ |
eae0bfdc | 459 | GIT_EXTERN(int) git_repository_item_path(git_buf *out, const git_repository *repo, git_repository_item_t item); |
cb3269c9 | 460 | |
6632c155 VM |
461 | /** |
462 | * Get the path of this repository | |
463 | * | |
464 | * This is the path of the `.git` folder for normal repositories, | |
465 | * or of the repository itself for bare repositories. | |
466 | * | |
467 | * @param repo A repository object | |
468 | * @return the path to the repository | |
469 | */ | |
eae0bfdc | 470 | GIT_EXTERN(const char *) git_repository_path(const git_repository *repo); |
6632c155 VM |
471 | |
472 | /** | |
473 | * Get the path of the working directory for this repository | |
474 | * | |
475 | * If the repository is bare, this function will always return | |
476 | * NULL. | |
477 | * | |
478 | * @param repo A repository object | |
479 | * @return the path to the working dir, if it exists | |
480 | */ | |
eae0bfdc | 481 | GIT_EXTERN(const char *) git_repository_workdir(const git_repository *repo); |
6632c155 | 482 | |
c09fd54e PS |
483 | /** |
484 | * Get the path of the shared common directory for this repository | |
485 | * | |
486 | * If the repository is bare is not a worktree, the git directory | |
487 | * path is returned. | |
488 | * | |
489 | * @param repo A repository object | |
490 | * @return the path to the common dir | |
491 | */ | |
eae0bfdc | 492 | GIT_EXTERN(const char *) git_repository_commondir(const git_repository *repo); |
c09fd54e | 493 | |
6632c155 VM |
494 | /** |
495 | * Set the path to the working directory for this repository | |
496 | * | |
497 | * The working directory doesn't need to be the same one | |
498 | * that contains the `.git` folder for this repository. | |
499 | * | |
500 | * If this repository is bare, setting its working directory | |
501 | * will turn it into a normal repository, capable of performing | |
502 | * all the common workdir operations (checkout, status, index | |
503 | * manipulation, etc). | |
504 | * | |
505 | * @param repo A repository object | |
506 | * @param workdir The path to a working directory | |
991a56c7 RB |
507 | * @param update_gitlink Create/update gitlink in workdir and set config |
508 | * "core.worktree" (if workdir is not the parent of the .git directory) | |
e172cf08 | 509 | * @return 0, or an error code |
6632c155 | 510 | */ |
991a56c7 RB |
511 | GIT_EXTERN(int) git_repository_set_workdir( |
512 | git_repository *repo, const char *workdir, int update_gitlink); | |
4a34b3a9 | 513 | |
fa9bcd81 | 514 | /** |
515 | * Check if a repository is bare | |
516 | * | |
517 | * @param repo Repo to test | |
28ba94ce | 518 | * @return 1 if the repository is bare, 0 otherwise. |
fa9bcd81 | 519 | */ |
eae0bfdc | 520 | GIT_EXTERN(int) git_repository_is_bare(const git_repository *repo); |
fa9bcd81 | 521 | |
79ab3ef6 PS |
522 | /** |
523 | * Check if a repository is a linked work tree | |
524 | * | |
525 | * @param repo Repo to test | |
526 | * @return 1 if the repository is a linked work tree, 0 otherwise. | |
527 | */ | |
eae0bfdc | 528 | GIT_EXTERN(int) git_repository_is_worktree(const git_repository *repo); |
79ab3ef6 | 529 | |
6632c155 VM |
530 | /** |
531 | * Get the configuration file for this repository. | |
532 | * | |
533 | * If a configuration file has not been set, the default | |
534 | * config set for the repository will be returned, including | |
535 | * global and system configurations (if they are available). | |
536 | * | |
537 | * The configuration file must be freed once it's no longer | |
538 | * being used by the user. | |
539 | * | |
ac99d86b | 540 | * @param out Pointer to store the loaded configuration |
6632c155 | 541 | * @param repo A repository object |
e172cf08 | 542 | * @return 0, or an error code |
6632c155 | 543 | */ |
9462c471 | 544 | GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo); |
6632c155 | 545 | |
ac99d86b CMN |
546 | /** |
547 | * Get a snapshot of the repository's configuration | |
548 | * | |
549 | * Convenience function to take a snapshot from the repository's | |
b1914c36 RB |
550 | * configuration. The contents of this snapshot will not change, |
551 | * even if the underlying config files are modified. | |
552 | * | |
553 | * The configuration file must be freed once it's no longer | |
554 | * being used by the user. | |
ac99d86b CMN |
555 | * |
556 | * @param out Pointer to store the loaded configuration | |
557 | * @param repo the repository | |
558 | * @return 0, or an error code | |
559 | */ | |
560 | GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository *repo); | |
561 | ||
6632c155 VM |
562 | /** |
563 | * Get the Object Database for this repository. | |
564 | * | |
565 | * If a custom ODB has not been set, the default | |
566 | * database for the repository will be returned (the one | |
567 | * located in `.git/objects`). | |
568 | * | |
569 | * The ODB must be freed once it's no longer being used by | |
570 | * the user. | |
571 | * | |
572 | * @param out Pointer to store the loaded ODB | |
573 | * @param repo A repository object | |
e172cf08 | 574 | * @return 0, or an error code |
6632c155 | 575 | */ |
9462c471 | 576 | GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo); |
6632c155 | 577 | |
d00d5464 ET |
578 | /** |
579 | * Get the Reference Database Backend for this repository. | |
580 | * | |
581 | * If a custom refsdb has not been set, the default database for | |
582 | * the repository will be returned (the one that manipulates loose | |
583 | * and packed references in the `.git` directory). | |
584 | * | |
585 | * The refdb must be freed once it's no longer being used by | |
586 | * the user. | |
587 | * | |
588 | * @param out Pointer to store the loaded refdb | |
589 | * @param repo A repository object | |
590 | * @return 0, or an error code | |
591 | */ | |
592 | GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo); | |
593 | ||
6632c155 VM |
594 | /** |
595 | * Get the Index file for this repository. | |
596 | * | |
597 | * If a custom index has not been set, the default | |
598 | * index for the repository will be returned (the one | |
599 | * located in `.git/index`). | |
600 | * | |
601 | * The index must be freed once it's no longer being used by | |
602 | * the user. | |
603 | * | |
604 | * @param out Pointer to store the loaded index | |
605 | * @param repo A repository object | |
e172cf08 | 606 | * @return 0, or an error code |
6632c155 | 607 | */ |
9462c471 | 608 | GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo); |
6632c155 | 609 | |
074841ec | 610 | /** |
cc548c7b | 611 | * Retrieve git's prepared message |
074841ec CMN |
612 | * |
613 | * Operations such as git revert/cherry-pick/merge with the -n option | |
614 | * stop just short of creating a commit with the changes and save | |
615 | * their prepared message in .git/MERGE_MSG so the next git-commit | |
616 | * execution can present it to the user for them to amend if they | |
617 | * wish. | |
618 | * | |
619 | * Use this function to get the contents of this file. Don't forget to | |
620 | * remove the file after you create the commit. | |
e9ca852e | 621 | * |
7a3bd1e7 | 622 | * @param out git_buf to write data into |
e9ca852e | 623 | * @param repo Repository to read prepared message from |
7a3bd1e7 | 624 | * @return 0, GIT_ENOTFOUND if no message exists or an error code |
074841ec | 625 | */ |
7a3bd1e7 | 626 | GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo); |
074841ec CMN |
627 | |
628 | /** | |
629 | * Remove git's prepared message. | |
630 | * | |
631 | * Remove the message that `git_repository_message` retrieves. | |
632 | */ | |
633 | GIT_EXTERN(int) git_repository_message_remove(git_repository *repo); | |
634 | ||
ad2bc32f | 635 | /** |
bab0b9f2 ET |
636 | * Remove all the metadata associated with an ongoing command like merge, |
637 | * revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc. | |
ad2bc32f ET |
638 | * |
639 | * @param repo A repository object | |
640 | * @return 0 on success, or error | |
641 | */ | |
bab0b9f2 | 642 | GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo); |
ad2bc32f | 643 | |
0c9c969a UG |
644 | /** |
645 | * Callback used to iterate over each FETCH_HEAD entry | |
646 | * | |
647 | * @see git_repository_fetchhead_foreach | |
648 | * | |
649 | * @param ref_name The reference name | |
650 | * @param remote_url The remote URL | |
651 | * @param oid The reference target OID | |
652 | * @param is_merge Was the reference the result of a merge | |
653 | * @param payload Payload passed to git_repository_fetchhead_foreach | |
654 | * @return non-zero to terminate the iteration | |
655 | */ | |
ac3d33df | 656 | typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb)(const char *ref_name, |
7fcec834 ET |
657 | const char *remote_url, |
658 | const git_oid *oid, | |
659 | unsigned int is_merge, | |
660 | void *payload); | |
661 | ||
662 | /** | |
373cf6a9 RB |
663 | * Invoke 'callback' for each entry in the given FETCH_HEAD file. |
664 | * | |
665 | * Return a non-zero value from the callback to stop the loop. | |
7fcec834 ET |
666 | * |
667 | * @param repo A repository object | |
668 | * @param callback Callback function | |
669 | * @param payload Pointer to callback data (optional) | |
373cf6a9 RB |
670 | * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if |
671 | * there is no FETCH_HEAD file, or other error code. | |
7fcec834 | 672 | */ |
373cf6a9 RB |
673 | GIT_EXTERN(int) git_repository_fetchhead_foreach( |
674 | git_repository *repo, | |
7fcec834 ET |
675 | git_repository_fetchhead_foreach_cb callback, |
676 | void *payload); | |
677 | ||
0c9c969a UG |
678 | /** |
679 | * Callback used to iterate over each MERGE_HEAD entry | |
680 | * | |
681 | * @see git_repository_mergehead_foreach | |
682 | * | |
683 | * @param oid The merge OID | |
684 | * @param payload Payload passed to git_repository_mergehead_foreach | |
685 | * @return non-zero to terminate the iteration | |
686 | */ | |
ac3d33df | 687 | typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb)(const git_oid *oid, |
42e50b5e ET |
688 | void *payload); |
689 | ||
690 | /** | |
373cf6a9 | 691 | * If a merge is in progress, invoke 'callback' for each commit ID in the |
42e50b5e ET |
692 | * MERGE_HEAD file. |
693 | * | |
373cf6a9 RB |
694 | * Return a non-zero value from the callback to stop the loop. |
695 | * | |
42e50b5e ET |
696 | * @param repo A repository object |
697 | * @param callback Callback function | |
e1967164 | 698 | * @param payload Pointer to callback data (optional) |
373cf6a9 RB |
699 | * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if |
700 | * there is no MERGE_HEAD file, or other error code. | |
42e50b5e | 701 | */ |
373cf6a9 RB |
702 | GIT_EXTERN(int) git_repository_mergehead_foreach( |
703 | git_repository *repo, | |
42e50b5e ET |
704 | git_repository_mergehead_foreach_cb callback, |
705 | void *payload); | |
706 | ||
47bfa0be RB |
707 | /** |
708 | * Calculate hash of file using repository filtering rules. | |
709 | * | |
710 | * If you simply want to calculate the hash of a file on disk with no filters, | |
711 | * you can just use the `git_odb_hashfile()` API. However, if you want to | |
712 | * hash a file in the repository and you want to apply filtering rules (e.g. | |
713 | * crlf filters) before generating the SHA, then use this function. | |
714 | * | |
5269008c RB |
715 | * Note: if the repository has `core.safecrlf` set to fail and the |
716 | * filtering triggers that failure, then this function will return an | |
717 | * error and not calculate the hash of the file. | |
718 | * | |
47bfa0be | 719 | * @param out Output value of calculated SHA |
a13fb55a | 720 | * @param repo Repository pointer |
47bfa0be RB |
721 | * @param path Path to file on disk whose contents should be hashed. If the |
722 | * repository is not NULL, this can be a relative path. | |
ac3d33df | 723 | * @param type The object type to hash as (e.g. GIT_OBJECT_BLOB) |
47bfa0be RB |
724 | * @param as_path The path to use to look up filtering rules. If this is |
725 | * NULL, then the `path` parameter will be used instead. If | |
726 | * this is passed as the empty string, then no filters will be | |
727 | * applied when calculating the hash. | |
5269008c | 728 | * @return 0 on success, or an error code |
47bfa0be RB |
729 | */ |
730 | GIT_EXTERN(int) git_repository_hashfile( | |
0cb16fe9 L |
731 | git_oid *out, |
732 | git_repository *repo, | |
733 | const char *path, | |
ac3d33df | 734 | git_object_t type, |
0cb16fe9 | 735 | const char *as_path); |
074841ec | 736 | |
44af67a8 | 737 | /** |
738 | * Make the repository HEAD point to the specified reference. | |
739 | * | |
740 | * If the provided reference points to a Tree or a Blob, the HEAD is | |
741 | * unaltered and -1 is returned. | |
742 | * | |
743 | * If the provided reference points to a branch, the HEAD will point | |
744 | * to that branch, staying attached, or become attached if it isn't yet. | |
745 | * If the branch doesn't exist yet, no error will be return. The HEAD | |
746 | * will then be attached to an unborn branch. | |
747 | * | |
748 | * Otherwise, the HEAD will be detached and will directly point to | |
749 | * the Commit. | |
750 | * | |
751 | * @param repo Repository pointer | |
752 | * @param refname Canonical name of the reference the HEAD should point at | |
753 | * @return 0 on success, or an error code | |
754 | */ | |
755 | GIT_EXTERN(int) git_repository_set_head( | |
756 | git_repository* repo, | |
4e498646 | 757 | const char* refname); |
44af67a8 | 758 | |
4ebe38bd | 759 | /** |
760 | * Make the repository HEAD directly point to the Commit. | |
761 | * | |
762 | * If the provided committish cannot be found in the repository, the HEAD | |
763 | * is unaltered and GIT_ENOTFOUND is returned. | |
764 | * | |
765 | * If the provided commitish cannot be peeled into a commit, the HEAD | |
766 | * is unaltered and -1 is returned. | |
767 | * | |
768 | * Otherwise, the HEAD will eventually be detached and will directly point to | |
769 | * the peeled Commit. | |
770 | * | |
771 | * @param repo Repository pointer | |
772 | * @param commitish Object id of the Commit the HEAD should point to | |
773 | * @return 0 on success, or an error code | |
774 | */ | |
775 | GIT_EXTERN(int) git_repository_set_head_detached( | |
776 | git_repository* repo, | |
4e498646 | 777 | const git_oid* commitish); |
4ebe38bd | 778 | |
62d38a1d CMN |
779 | /** |
780 | * Make the repository HEAD directly point to the Commit. | |
781 | * | |
782 | * This behaves like `git_repository_set_head_detached()` but takes an | |
783 | * annotated commit, which lets you specify which extended sha syntax | |
784 | * string was specified by a user, allowing for more exact reflog | |
785 | * messages. | |
786 | * | |
787 | * See the documentation for `git_repository_set_head_detached()`. | |
788 | * | |
789 | * @see git_repository_set_head_detached | |
790 | */ | |
791 | GIT_EXTERN(int) git_repository_set_head_detached_from_annotated( | |
792 | git_repository *repo, | |
793 | const git_annotated_commit *commitish); | |
794 | ||
3f4c3072 | 795 | /** |
796 | * Detach the HEAD. | |
797 | * | |
798 | * If the HEAD is already detached and points to a Commit, 0 is returned. | |
799 | * | |
800 | * If the HEAD is already detached and points to a Tag, the HEAD is | |
801 | * updated into making it point to the peeled Commit, and 0 is returned. | |
802 | * | |
0b170f4d | 803 | * If the HEAD is already detached and points to a non commitish, the HEAD is |
7eb222fc | 804 | * unaltered, and -1 is returned. |
3f4c3072 | 805 | * |
806 | * Otherwise, the HEAD will be detached and point to the peeled Commit. | |
807 | * | |
808 | * @param repo Repository pointer | |
605da51a | 809 | * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing |
875b16eb | 810 | * branch or an error code |
3f4c3072 | 811 | */ |
812 | GIT_EXTERN(int) git_repository_detach_head( | |
4e498646 | 813 | git_repository* repo); |
3f4c3072 | 814 | |
a295bd2d CMN |
815 | /** |
816 | * Repository state | |
817 | * | |
818 | * These values represent possible states for the repository to be in, | |
819 | * based on the current operation which is ongoing. | |
820 | */ | |
632d8b23 ET |
821 | typedef enum { |
822 | GIT_REPOSITORY_STATE_NONE, | |
823 | GIT_REPOSITORY_STATE_MERGE, | |
824 | GIT_REPOSITORY_STATE_REVERT, | |
2ea40fda | 825 | GIT_REPOSITORY_STATE_REVERT_SEQUENCE, |
0ba4dca5 | 826 | GIT_REPOSITORY_STATE_CHERRYPICK, |
2ea40fda | 827 | GIT_REPOSITORY_STATE_CHERRYPICK_SEQUENCE, |
31966d20 | 828 | GIT_REPOSITORY_STATE_BISECT, |
829 | GIT_REPOSITORY_STATE_REBASE, | |
830 | GIT_REPOSITORY_STATE_REBASE_INTERACTIVE, | |
831 | GIT_REPOSITORY_STATE_REBASE_MERGE, | |
832 | GIT_REPOSITORY_STATE_APPLY_MAILBOX, | |
833 | GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE, | |
632d8b23 ET |
834 | } git_repository_state_t; |
835 | ||
836 | /** | |
837 | * Determines the status of a git repository - ie, whether an operation | |
838 | * (merge, cherry-pick, etc) is in progress. | |
839 | * | |
840 | * @param repo Repository pointer | |
841 | * @return The state of the repository | |
842 | */ | |
843 | GIT_EXTERN(int) git_repository_state(git_repository *repo); | |
844 | ||
bade5194 VM |
845 | /** |
846 | * Sets the active namespace for this Git Repository | |
847 | * | |
848 | * This namespace affects all reference operations for the repo. | |
849 | * See `man gitnamespaces` | |
850 | * | |
851 | * @param repo The repo | |
852 | * @param nmspace The namespace. This should not include the refs | |
853 | * folder, e.g. to namespace all references under `refs/namespaces/foo/`, | |
854 | * use `foo` as the namespace. | |
855 | * @return 0 on success, -1 on error | |
856 | */ | |
857 | GIT_EXTERN(int) git_repository_set_namespace(git_repository *repo, const char *nmspace); | |
858 | ||
859 | /** | |
860 | * Get the currently active namespace for this repository | |
861 | * | |
862 | * @param repo The repo | |
863 | * @return the active namespace, or NULL if there isn't one | |
864 | */ | |
865 | GIT_EXTERN(const char *) git_repository_get_namespace(git_repository *repo); | |
866 | ||
93d8f77f BS |
867 | |
868 | /** | |
869 | * Determine if the repository was a shallow clone | |
870 | * | |
871 | * @param repo The repository | |
872 | * @return 1 if shallow, zero if not | |
873 | */ | |
874 | GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo); | |
875 | ||
659cf202 CMN |
876 | /** |
877 | * Retrieve the configured identity to use for reflogs | |
878 | * | |
879 | * The memory is owned by the repository and must not be freed by the | |
880 | * user. | |
881 | * | |
882 | * @param name where to store the pointer to the name | |
883 | * @param email where to store the pointer to the email | |
884 | * @param repo the repository | |
885 | */ | |
886 | GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo); | |
887 | ||
888 | /** | |
889 | * Set the identity to be used for writing reflogs | |
890 | * | |
891 | * If both are set, this name and email will be used to write to the | |
892 | * reflog. Pass NULL to unset. When unset, the identity will be taken | |
893 | * from the repository's configuration. | |
894 | * | |
895 | * @param repo the repository to configure | |
896 | * @param name the name to use for the reflog entries | |
41808d04 | 897 | * @param email the email to use for the reflog entries |
659cf202 CMN |
898 | */ |
899 | GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email); | |
900 | ||
3315782c VM |
901 | /** @} */ |
902 | GIT_END_DECL | |
903 | #endif |