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_git_repository_h__
8 #define INCLUDE_git_repository_h__
9 
10 #include "common.h"
11 #include "types.h"
12 #include "oid.h"
13 #include "buffer.h"
14 
15 /**
16  * @file git2/repository.h
17  * @brief Git repository management routines
18  * @defgroup git_repository Git repository management routines
19  * @ingroup Git
20  * @{
21  */
22 GIT_BEGIN_DECL
23 
24 /**
25  * Open a git repository.
26  *
27  * The 'path' argument must point to either a git repository
28  * folder, or an existing work dir.
29  *
30  * The method will automatically detect if 'path' is a normal
31  * or bare repository or fail is 'path' is neither.
32  *
33  * @param out pointer to the repo which will be opened
34  * @param path the path to the repository
35  * @return 0 or an error code
36  */
37 GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path);
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);
49 
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  *
57  * @param out pointer to the repo
58  * @param odb the object database to wrap
59  * @return 0 or an error code
60  */
61 GIT_EXTERN(int) git_repository_wrap_odb(git_repository **out, git_odb *odb);
62 
63 /**
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).
69  *
70  * The method will automatically detect if the repository is bare
71  * (if there is a repository).
72  *
73  * @param out A pointer to a user-allocated git_buf which will contain
74  * the found path.
75  *
76  * @param start_path The base path where the lookup starts.
77  *
78  * @param across_fs If true, then the lookup will not stop when a
79  * filesystem device change is detected while exploring parent directories.
80  *
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)
86  *
87  * @return 0 or an error code
88  */
89 GIT_EXTERN(int) git_repository_discover(
90 		git_buf *out,
91 		const char *start_path,
92 		int across_fs,
93 		const char *ceiling_dirs);
94 
95 /**
96  * Option flags for `git_repository_open_ext`.
97  */
98 typedef enum {
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 	 */
104 	GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0),
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 	 */
113 	GIT_REPOSITORY_OPEN_CROSS_FS  = (1 << 1),
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 	 */
120 	GIT_REPOSITORY_OPEN_BARE      = (1 << 2),
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 	 */
127 	GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3),
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 	 */
144 	GIT_REPOSITORY_OPEN_FROM_ENV  = (1 << 4),
145 } git_repository_open_flag_t;
146 
147 /**
148  * Find and open a repository with extended controls.
149  *
150  * @param out Pointer to the repo which will be opened.  This can
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.
153  * @param path Path to open as git repository.  If the flags
154  *        permit "searching", then this can be a path to a subdirectory
155  *        inside the working directory of the repository. May be NULL if
156  *        flags is GIT_REPOSITORY_OPEN_FROM_ENV.
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).
164  */
165 GIT_EXTERN(int) git_repository_open_ext(
166 	git_repository **out,
167 	const char *path,
168 	unsigned int flags,
169 	const char *ceiling_dirs);
170 
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  */
182 GIT_EXTERN(int) git_repository_open_bare(git_repository **out, const char *bare_path);
183 
184 /**
185  * Free a previously allocated repository
186  *
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
189  * with `git_object_free`, but accessing any of the attributes of
190  * an object without a backing repository will result in undefined
191  * behavior
192  *
193  * @param repo repository handle to close. If NULL nothing occurs.
194  */
195 GIT_EXTERN(void) git_repository_free(git_repository *repo);
196 
197 /**
198  * Creates a new Git repository in the given folder.
199  *
200  * TODO:
201  *	- Reinit the repository
202  *
203  * @param out pointer to the repo which will be created or reinitialized
204  * @param path the path to the repository
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.
209  *
210  * @return 0 or an error code
211  */
212 GIT_EXTERN(int) git_repository_init(
213 	git_repository **out,
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.
224  */
225 typedef enum {
226 	/**
227 	 * Create a bare repository with no working directory.
228 	 */
229 	GIT_REPOSITORY_INIT_BARE              = (1u << 0),
230 
231 	/**
232 	 * Return an GIT_EEXISTS error if the repo_path appears to already be
233 	 * an git repository.
234 	 */
235 	GIT_REPOSITORY_INIT_NO_REINIT         = (1u << 1),
236 
237 	/**
238 	 * Normally a "/.git/" will be appended to the repo path for
239 	 * non-bare repos (if it is not already there), but passing this flag
240 	 * prevents that behavior.
241 	 */
242 	GIT_REPOSITORY_INIT_NO_DOTGIT_DIR     = (1u << 2),
243 
244 	/**
245 	 * Make the repo_path (and workdir_path) as needed. Init is always willing
246 	 * to create the ".git" directory even without this flag. This flag tells
247 	 * init to create the trailing component of the repo and workdir paths
248 	 * as needed.
249 	 */
250 	GIT_REPOSITORY_INIT_MKDIR             = (1u << 3),
251 
252 	/**
253 	 * Recursively make all components of the repo and workdir paths as
254 	 * necessary.
255 	 */
256 	GIT_REPOSITORY_INIT_MKPATH            = (1u << 4),
257 
258 	/**
259 	 * libgit2 normally uses internal templates to initialize a new repo.
260 	 * This flags enables external templates, looking the "template_path" from
261 	 * the options if set, or the `init.templatedir` global config if not,
262 	 * or falling back on "/usr/share/git-core/templates" if it exists.
263 	 */
264 	GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5),
265 
266 	/**
267 	 * If an alternate workdir is specified, use relative paths for the gitdir
268 	 * and core.worktree.
269 	 */
270 	GIT_REPOSITORY_INIT_RELATIVE_GITLINK  = (1u << 6),
271 } git_repository_init_flag_t;
272 
273 /**
274  * Mode options for `git_repository_init_ext`.
275  *
276  * Set the mode field of the `git_repository_init_options` structure
277  * either to the custom mode that you would like, or to one of the
278  * defined modes.
279  */
280 typedef enum {
281 	/**
282 	 * Use permissions configured by umask - the default.
283 	 */
284 	GIT_REPOSITORY_INIT_SHARED_UMASK = 0,
285 
286 	/**
287 	 * Use "--shared=group" behavior, chmod'ing the new repo to be group
288 	 * writable and "g+sx" for sticky group assignment.
289 	 */
290 	GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775,
291 
292 	/**
293 	 * Use "--shared=all" behavior, adding world readability.
294 	 */
295 	GIT_REPOSITORY_INIT_SHARED_ALL   = 0002777,
296 } git_repository_init_mode_t;
297 
298 /**
299  * Extended options structure for `git_repository_init_ext`.
300  *
301  * This contains extra options for `git_repository_init_ext` that enable
302  * additional initialization features.
303  */
304 typedef struct {
305 	unsigned int version;
306 
307 	/**
308 	 * Combination of GIT_REPOSITORY_INIT flags above.
309 	 */
310 	uint32_t    flags;
311 
312 	/**
313 	 * Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... constants
314 	 * above, or to a custom value that you would like.
315 	 */
316 	uint32_t    mode;
317 
318 	/**
319 	 * The path to the working dir or NULL for default (i.e. repo_path parent
320 	 * on non-bare repos). IF THIS IS RELATIVE PATH, IT WILL BE EVALUATED
321 	 * RELATIVE TO THE REPO_PATH. If this is not the "natural" working
322 	 * directory, a .git gitlink file will be created here linking to the
323 	 * repo_path.
324 	 */
325 	const char *workdir_path;
326 
327 	/**
328 	 * If set, this will be used to initialize the "description" file in the
329 	 * repository, instead of using the template content.
330 	 */
331 	const char *description;
332 
333 	/**
334 	 * When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set, this contains
335 	 * the path to use for the template directory. If this is NULL, the config
336 	 * or default directory options will be used instead.
337 	 */
338 	const char *template_path;
339 
340 	/**
341 	 * The name of the head to point HEAD at. If NULL, then this will be
342 	 * treated as "master" and the HEAD ref will be set to "refs/heads/master".
343 	 * If this begins with "refs/" it will be used verbatim;
344 	 * otherwise "refs/heads/" will be prefixed.
345 	 */
346 	const char *initial_head;
347 
348 	/**
349 	 * If this is non-NULL, then after the rest of the repository
350 	 * initialization is completed, an "origin" remote will be added
351 	 * pointing to this URL.
352 	 */
353 	const char *origin_url;
354 } git_repository_init_options;
355 
356 #define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1
357 #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION}
358 
359 /**
360  * Initialize git_repository_init_options structure
361  *
362  * Initializes a `git_repository_init_options` with default values. Equivalent to
363  * creating an instance with `GIT_REPOSITORY_INIT_OPTIONS_INIT`.
364  *
365  * @param opts The `git_repository_init_options` struct to initialize.
366  * @param version The struct version; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`.
367  * @return Zero on success; -1 on failure.
368  */
369 GIT_EXTERN(int) git_repository_init_options_init(
370 	git_repository_init_options *opts,
371 	unsigned int version);
372 
373 /**
374  * Create a new Git repository in the given folder with extended controls.
375  *
376  * This will initialize a new git repository (creating the repo_path
377  * if requested by flags) and working directory as needed.  It will
378  * auto-detect the case sensitivity of the file system and if the
379  * file system supports file mode bits correctly.
380  *
381  * @param out Pointer to the repo which will be created or reinitialized.
382  * @param repo_path The path to the repository.
383  * @param opts Pointer to git_repository_init_options struct.
384  * @return 0 or an error code on failure.
385  */
386 GIT_EXTERN(int) git_repository_init_ext(
387 	git_repository **out,
388 	const char *repo_path,
389 	git_repository_init_options *opts);
390 
391 /**
392  * Retrieve and resolve the reference pointed at by HEAD.
393  *
394  * The returned `git_reference` will be owned by caller and
395  * `git_reference_free()` must be called when done with it to release the
396  * allocated memory and prevent a leak.
397  *
398  * @param out pointer to the reference which will be retrieved
399  * @param repo a repository object
400  *
401  * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
402  * branch, GIT_ENOTFOUND when HEAD is missing; an error code otherwise
403  */
404 GIT_EXTERN(int) git_repository_head(git_reference **out, git_repository *repo);
405 
406 /**
407  * Retrieve the referenced HEAD for the worktree
408  *
409  * @param out pointer to the reference which will be retrieved
410  * @param repo a repository object
411  * @param name name of the worktree to retrieve HEAD for
412  * @return 0 when successful, error-code otherwise
413  */
414 GIT_EXTERN(int) git_repository_head_for_worktree(git_reference **out, git_repository *repo,
415 	const char *name);
416 
417 /**
418  * Check if a repository's HEAD is detached
419  *
420  * A repository's HEAD is detached when it points directly to a commit
421  * instead of a branch.
422  *
423  * @param repo Repo to test
424  * @return 1 if HEAD is detached, 0 if it's not; error code if there
425  * was an error.
426  */
427 GIT_EXTERN(int) git_repository_head_detached(git_repository *repo);
428 
429 /**
430  * Check if a worktree's HEAD is detached
431  *
432  * A worktree's HEAD is detached when it points directly to a
433  * commit instead of a branch.
434  *
435  * @param repo a repository object
436  * @param name name of the worktree to retrieve HEAD for
437  * @return 1 if HEAD is detached, 0 if its not; error code if
438  *  there was an error
439  */
440 GIT_EXTERN(int) git_repository_head_detached_for_worktree(git_repository *repo,
441 	const char *name);
442 
443 /**
444  * Check if the current branch is unborn
445  *
446  * An unborn branch is one named from HEAD but which doesn't exist in
447  * the refs namespace, because it doesn't have any commit to point to.
448  *
449  * @param repo Repo to test
450  * @return 1 if the current branch is unborn, 0 if it's not; error
451  * code if there was an error
452  */
453 GIT_EXTERN(int) git_repository_head_unborn(git_repository *repo);
454 
455 /**
456  * Check if a repository is empty
457  *
458  * An empty repository has just been initialized and contains no references
459  * apart from HEAD, which must be pointing to the unborn master branch.
460  *
461  * @param repo Repo to test
462  * @return 1 if the repository is empty, 0 if it isn't, error code
463  * if the repository is corrupted
464  */
465 GIT_EXTERN(int) git_repository_is_empty(git_repository *repo);
466 
467 /**
468  * List of items which belong to the git repository layout
469  */
470 typedef enum {
471 	GIT_REPOSITORY_ITEM_GITDIR,
472 	GIT_REPOSITORY_ITEM_WORKDIR,
473 	GIT_REPOSITORY_ITEM_COMMONDIR,
474 	GIT_REPOSITORY_ITEM_INDEX,
475 	GIT_REPOSITORY_ITEM_OBJECTS,
476 	GIT_REPOSITORY_ITEM_REFS,
477 	GIT_REPOSITORY_ITEM_PACKED_REFS,
478 	GIT_REPOSITORY_ITEM_REMOTES,
479 	GIT_REPOSITORY_ITEM_CONFIG,
480 	GIT_REPOSITORY_ITEM_INFO,
481 	GIT_REPOSITORY_ITEM_HOOKS,
482 	GIT_REPOSITORY_ITEM_LOGS,
483 	GIT_REPOSITORY_ITEM_MODULES,
484 	GIT_REPOSITORY_ITEM_WORKTREES,
485 	GIT_REPOSITORY_ITEM__LAST
486 } git_repository_item_t;
487 
488 /**
489  * Get the location of a specific repository file or directory
490  *
491  * This function will retrieve the path of a specific repository
492  * item. It will thereby honor things like the repository's
493  * common directory, gitdir, etc. In case a file path cannot
494  * exist for a given item (e.g. the working directory of a bare
495  * repository), GIT_ENOTFOUND is returned.
496  *
497  * @param out Buffer to store the path at
498  * @param repo Repository to get path for
499  * @param item The repository item for which to retrieve the path
500  * @return 0, GIT_ENOTFOUND if the path cannot exist or an error code
501  */
502 GIT_EXTERN(int) git_repository_item_path(git_buf *out, const git_repository *repo, git_repository_item_t item);
503 
504 /**
505  * Get the path of this repository
506  *
507  * This is the path of the `.git` folder for normal repositories,
508  * or of the repository itself for bare repositories.
509  *
510  * @param repo A repository object
511  * @return the path to the repository
512  */
513 GIT_EXTERN(const char *) git_repository_path(const git_repository *repo);
514 
515 /**
516  * Get the path of the working directory for this repository
517  *
518  * If the repository is bare, this function will always return
519  * NULL.
520  *
521  * @param repo A repository object
522  * @return the path to the working dir, if it exists
523  */
524 GIT_EXTERN(const char *) git_repository_workdir(const git_repository *repo);
525 
526 /**
527  * Get the path of the shared common directory for this repository.
528  *
529  * If the repository is bare, it is the root directory for the repository.
530  * If the repository is a worktree, it is the parent repo's gitdir.
531  * Otherwise, it is the gitdir.
532  *
533  * @param repo A repository object
534  * @return the path to the common dir
535  */
536 GIT_EXTERN(const char *) git_repository_commondir(const git_repository *repo);
537 
538 /**
539  * Set the path to the working directory for this repository
540  *
541  * The working directory doesn't need to be the same one
542  * that contains the `.git` folder for this repository.
543  *
544  * If this repository is bare, setting its working directory
545  * will turn it into a normal repository, capable of performing
546  * all the common workdir operations (checkout, status, index
547  * manipulation, etc).
548  *
549  * @param repo A repository object
550  * @param workdir The path to a working directory
551  * @param update_gitlink Create/update gitlink in workdir and set config
552  *        "core.worktree" (if workdir is not the parent of the .git directory)
553  * @return 0, or an error code
554  */
555 GIT_EXTERN(int) git_repository_set_workdir(
556 	git_repository *repo, const char *workdir, int update_gitlink);
557 
558 /**
559  * Check if a repository is bare
560  *
561  * @param repo Repo to test
562  * @return 1 if the repository is bare, 0 otherwise.
563  */
564 GIT_EXTERN(int) git_repository_is_bare(const git_repository *repo);
565 
566 /**
567  * Check if a repository is a linked work tree
568  *
569  * @param repo Repo to test
570  * @return 1 if the repository is a linked work tree, 0 otherwise.
571  */
572 GIT_EXTERN(int) git_repository_is_worktree(const git_repository *repo);
573 
574 /**
575  * Get the configuration file for this repository.
576  *
577  * If a configuration file has not been set, the default
578  * config set for the repository will be returned, including
579  * global and system configurations (if they are available).
580  *
581  * The configuration file must be freed once it's no longer
582  * being used by the user.
583  *
584  * @param out Pointer to store the loaded configuration
585  * @param repo A repository object
586  * @return 0, or an error code
587  */
588 GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo);
589 
590 /**
591  * Get a snapshot of the repository's configuration
592  *
593  * Convenience function to take a snapshot from the repository's
594  * configuration.  The contents of this snapshot will not change,
595  * even if the underlying config files are modified.
596  *
597  * The configuration file must be freed once it's no longer
598  * being used by the user.
599  *
600  * @param out Pointer to store the loaded configuration
601  * @param repo the repository
602  * @return 0, or an error code
603  */
604 GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository *repo);
605 
606 /**
607  * Get the Object Database for this repository.
608  *
609  * If a custom ODB has not been set, the default
610  * database for the repository will be returned (the one
611  * located in `.git/objects`).
612  *
613  * The ODB must be freed once it's no longer being used by
614  * the user.
615  *
616  * @param out Pointer to store the loaded ODB
617  * @param repo A repository object
618  * @return 0, or an error code
619  */
620 GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo);
621 
622 /**
623  * Get the Reference Database Backend for this repository.
624  *
625  * If a custom refsdb has not been set, the default database for
626  * the repository will be returned (the one that manipulates loose
627  * and packed references in the `.git` directory).
628  *
629  * The refdb must be freed once it's no longer being used by
630  * the user.
631  *
632  * @param out Pointer to store the loaded refdb
633  * @param repo A repository object
634  * @return 0, or an error code
635  */
636 GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo);
637 
638 /**
639  * Get the Index file for this repository.
640  *
641  * If a custom index has not been set, the default
642  * index for the repository will be returned (the one
643  * located in `.git/index`).
644  *
645  * The index must be freed once it's no longer being used by
646  * the user.
647  *
648  * @param out Pointer to store the loaded index
649  * @param repo A repository object
650  * @return 0, or an error code
651  */
652 GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo);
653 
654 /**
655  * Retrieve git's prepared message
656  *
657  * Operations such as git revert/cherry-pick/merge with the -n option
658  * stop just short of creating a commit with the changes and save
659  * their prepared message in .git/MERGE_MSG so the next git-commit
660  * execution can present it to the user for them to amend if they
661  * wish.
662  *
663  * Use this function to get the contents of this file. Don't forget to
664  * remove the file after you create the commit.
665  *
666  * @param out git_buf to write data into
667  * @param repo Repository to read prepared message from
668  * @return 0, GIT_ENOTFOUND if no message exists or an error code
669  */
670 GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo);
671 
672 /**
673  * Remove git's prepared message.
674  *
675  * Remove the message that `git_repository_message` retrieves.
676  */
677 GIT_EXTERN(int) git_repository_message_remove(git_repository *repo);
678 
679 /**
680  * Remove all the metadata associated with an ongoing command like merge,
681  * revert, cherry-pick, etc.  For example: MERGE_HEAD, MERGE_MSG, etc.
682  *
683  * @param repo A repository object
684  * @return 0 on success, or error
685  */
686 GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo);
687 
688 /**
689  * Callback used to iterate over each FETCH_HEAD entry
690  *
691  * @see git_repository_fetchhead_foreach
692  *
693  * @param ref_name The reference name
694  * @param remote_url The remote URL
695  * @param oid The reference target OID
696  * @param is_merge Was the reference the result of a merge
697  * @param payload Payload passed to git_repository_fetchhead_foreach
698  * @return non-zero to terminate the iteration
699  */
700 typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb)(const char *ref_name,
701 	const char *remote_url,
702 	const git_oid *oid,
703 	unsigned int is_merge,
704 	void *payload);
705 
706 /**
707  * Invoke 'callback' for each entry in the given FETCH_HEAD file.
708  *
709  * Return a non-zero value from the callback to stop the loop.
710  *
711  * @param repo A repository object
712  * @param callback Callback function
713  * @param payload Pointer to callback data (optional)
714  * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if
715  *         there is no FETCH_HEAD file, or other error code.
716  */
717 GIT_EXTERN(int) git_repository_fetchhead_foreach(
718 	git_repository *repo,
719 	git_repository_fetchhead_foreach_cb callback,
720 	void *payload);
721 
722 /**
723  * Callback used to iterate over each MERGE_HEAD entry
724  *
725  * @see git_repository_mergehead_foreach
726  *
727  * @param oid The merge OID
728  * @param payload Payload passed to git_repository_mergehead_foreach
729  * @return non-zero to terminate the iteration
730  */
731 typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb)(const git_oid *oid,
732 	void *payload);
733 
734 /**
735  * If a merge is in progress, invoke 'callback' for each commit ID in the
736  * MERGE_HEAD file.
737  *
738  * Return a non-zero value from the callback to stop the loop.
739  *
740  * @param repo A repository object
741  * @param callback Callback function
742  * @param payload Pointer to callback data (optional)
743  * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if
744  *         there is no MERGE_HEAD file, or other error code.
745  */
746 GIT_EXTERN(int) git_repository_mergehead_foreach(
747 	git_repository *repo,
748 	git_repository_mergehead_foreach_cb callback,
749 	void *payload);
750 
751 /**
752  * Calculate hash of file using repository filtering rules.
753  *
754  * If you simply want to calculate the hash of a file on disk with no filters,
755  * you can just use the `git_odb_hashfile()` API.  However, if you want to
756  * hash a file in the repository and you want to apply filtering rules (e.g.
757  * crlf filters) before generating the SHA, then use this function.
758  *
759  * Note: if the repository has `core.safecrlf` set to fail and the
760  * filtering triggers that failure, then this function will return an
761  * error and not calculate the hash of the file.
762  *
763  * @param out Output value of calculated SHA
764  * @param repo Repository pointer
765  * @param path Path to file on disk whose contents should be hashed. If the
766  *             repository is not NULL, this can be a relative path.
767  * @param type The object type to hash as (e.g. GIT_OBJECT_BLOB)
768  * @param as_path The path to use to look up filtering rules. If this is
769  *             NULL, then the `path` parameter will be used instead. If
770  *             this is passed as the empty string, then no filters will be
771  *             applied when calculating the hash.
772  * @return 0 on success, or an error code
773  */
774 GIT_EXTERN(int) git_repository_hashfile(
775 	git_oid *out,
776 	git_repository *repo,
777 	const char *path,
778 	git_object_t type,
779 	const char *as_path);
780 
781 /**
782  * Make the repository HEAD point to the specified reference.
783  *
784  * If the provided reference points to a Tree or a Blob, the HEAD is
785  * unaltered and -1 is returned.
786  *
787  * If the provided reference points to a branch, the HEAD will point
788  * to that branch, staying attached, or become attached if it isn't yet.
789  * If the branch doesn't exist yet, no error will be return. The HEAD
790  * will then be attached to an unborn branch.
791  *
792  * Otherwise, the HEAD will be detached and will directly point to
793  * the Commit.
794  *
795  * @param repo Repository pointer
796  * @param refname Canonical name of the reference the HEAD should point at
797  * @return 0 on success, or an error code
798  */
799 GIT_EXTERN(int) git_repository_set_head(
800 	git_repository* repo,
801 	const char* refname);
802 
803 /**
804  * Make the repository HEAD directly point to the Commit.
805  *
806  * If the provided committish cannot be found in the repository, the HEAD
807  * is unaltered and GIT_ENOTFOUND is returned.
808  *
809  * If the provided commitish cannot be peeled into a commit, the HEAD
810  * is unaltered and -1 is returned.
811  *
812  * Otherwise, the HEAD will eventually be detached and will directly point to
813  * the peeled Commit.
814  *
815  * @param repo Repository pointer
816  * @param commitish Object id of the Commit the HEAD should point to
817  * @return 0 on success, or an error code
818  */
819 GIT_EXTERN(int) git_repository_set_head_detached(
820 	git_repository* repo,
821 	const git_oid* commitish);
822 
823 /**
824  * Make the repository HEAD directly point to the Commit.
825  *
826  * This behaves like `git_repository_set_head_detached()` but takes an
827  * annotated commit, which lets you specify which extended sha syntax
828  * string was specified by a user, allowing for more exact reflog
829  * messages.
830  *
831  * See the documentation for `git_repository_set_head_detached()`.
832  *
833  * @see git_repository_set_head_detached
834  */
835 GIT_EXTERN(int) git_repository_set_head_detached_from_annotated(
836 	git_repository *repo,
837 	const git_annotated_commit *commitish);
838 
839 /**
840  * Detach the HEAD.
841  *
842  * If the HEAD is already detached and points to a Commit, 0 is returned.
843  *
844  * If the HEAD is already detached and points to a Tag, the HEAD is
845  * updated into making it point to the peeled Commit, and 0 is returned.
846  *
847  * If the HEAD is already detached and points to a non commitish, the HEAD is
848  * unaltered, and -1 is returned.
849  *
850  * Otherwise, the HEAD will be detached and point to the peeled Commit.
851  *
852  * @param repo Repository pointer
853  * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
854  * branch or an error code
855  */
856 GIT_EXTERN(int) git_repository_detach_head(
857 	git_repository* repo);
858 
859 /**
860  * Repository state
861  *
862  * These values represent possible states for the repository to be in,
863  * based on the current operation which is ongoing.
864  */
865 typedef enum {
866 	GIT_REPOSITORY_STATE_NONE,
867 	GIT_REPOSITORY_STATE_MERGE,
868 	GIT_REPOSITORY_STATE_REVERT,
869 	GIT_REPOSITORY_STATE_REVERT_SEQUENCE,
870 	GIT_REPOSITORY_STATE_CHERRYPICK,
871 	GIT_REPOSITORY_STATE_CHERRYPICK_SEQUENCE,
872 	GIT_REPOSITORY_STATE_BISECT,
873 	GIT_REPOSITORY_STATE_REBASE,
874 	GIT_REPOSITORY_STATE_REBASE_INTERACTIVE,
875 	GIT_REPOSITORY_STATE_REBASE_MERGE,
876 	GIT_REPOSITORY_STATE_APPLY_MAILBOX,
877 	GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE,
878 } git_repository_state_t;
879 
880 /**
881  * Determines the status of a git repository - ie, whether an operation
882  * (merge, cherry-pick, etc) is in progress.
883  *
884  * @param repo Repository pointer
885  * @return The state of the repository
886  */
887 GIT_EXTERN(int) git_repository_state(git_repository *repo);
888 
889 /**
890  * Sets the active namespace for this Git Repository
891  *
892  * This namespace affects all reference operations for the repo.
893  * See `man gitnamespaces`
894  *
895  * @param repo The repo
896  * @param nmspace The namespace. This should not include the refs
897  *	folder, e.g. to namespace all references under `refs/namespaces/foo/`,
898  *	use `foo` as the namespace.
899  *	@return 0 on success, -1 on error
900  */
901 GIT_EXTERN(int) git_repository_set_namespace(git_repository *repo, const char *nmspace);
902 
903 /**
904  * Get the currently active namespace for this repository
905  *
906  * @param repo The repo
907  * @return the active namespace, or NULL if there isn't one
908  */
909 GIT_EXTERN(const char *) git_repository_get_namespace(git_repository *repo);
910 
911 
912 /**
913  * Determine if the repository was a shallow clone
914  *
915  * @param repo The repository
916  * @return 1 if shallow, zero if not
917  */
918 GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo);
919 
920 /**
921  * Retrieve the configured identity to use for reflogs
922  *
923  * The memory is owned by the repository and must not be freed by the
924  * user.
925  *
926  * @param name where to store the pointer to the name
927  * @param email where to store the pointer to the email
928  * @param repo the repository
929  */
930 GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo);
931 
932 /**
933  * Set the identity to be used for writing reflogs
934  *
935  * If both are set, this name and email will be used to write to the
936  * reflog. Pass NULL to unset. When unset, the identity will be taken
937  * from the repository's configuration.
938  *
939  * @param repo the repository to configure
940  * @param name the name to use for the reflog entries
941  * @param email the email to use for the reflog entries
942  */
943 GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email);
944 
945 /** @} */
946 GIT_END_DECL
947 #endif
948