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_git_repository_h__
8 #define INCLUDE_git_repository_h__
16 * @file git2/repository.h
17 * @brief Git repository management routines
18 * @defgroup git_repository Git repository management routines
25 * Open a git repository.
27 * The 'path' argument must point to either a git repository
28 * folder, or an existing work dir.
30 * The method will automatically detect if 'path' is a normal
31 * or bare repository or fail is 'path' is neither.
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
37 GIT_EXTERN(int) git_repository_open(git_repository
**out
, const char *path
);
39 * Open working tree as a repository
41 * Open the working directory of the working tree as a normal
42 * repository that can then be worked on.
44 * @param out Output pointer containing opened repository
45 * @param wt Working tree to open
46 * @return 0 or an error code
48 GIT_EXTERN(int) git_repository_open_from_worktree(git_repository
**out
, git_worktree
*wt
);
51 * Create a "fake" repository to wrap an object database
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.
57 * @param out pointer to the repo
58 * @param odb the object database to wrap
59 * @return 0 or an error code
61 GIT_EXTERN(int) git_repository_wrap_odb(git_repository
**out
, git_odb
*odb
);
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).
70 * The method will automatically detect if the repository is bare
71 * (if there is a repository).
73 * @param out A pointer to a user-allocated git_buf which will contain
76 * @param start_path The base path where the lookup starts.
78 * @param across_fs If true, then the lookup will not stop when a
79 * filesystem device change is detected while exploring parent directories.
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)
87 * @return 0 or an error code
89 GIT_EXTERN(int) git_repository_discover(
91 const char *start_path
,
93 const char *ceiling_dirs
);
96 * Option flags for `git_repository_open_ext`.
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
104 GIT_REPOSITORY_OPEN_NO_SEARCH
= (1 << 0),
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".
113 GIT_REPOSITORY_OPEN_CROSS_FS
= (1 << 1),
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.
120 GIT_REPOSITORY_OPEN_BARE
= (1 << 2),
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
127 GIT_REPOSITORY_OPEN_NO_DOTGIT
= (1 << 3),
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.
144 GIT_REPOSITORY_OPEN_FROM_ENV
= (1 << 4),
145 } git_repository_open_flag_t
;
148 * Find and open a repository with extended controls.
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
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).
165 GIT_EXTERN(int) git_repository_open_ext(
166 git_repository
**out
,
169 const char *ceiling_dirs
);
172 * Open a bare repository on the serverside.
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
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
182 GIT_EXTERN(int) git_repository_open_bare(git_repository
**out
, const char *bare_path
);
185 * Free a previously allocated repository
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
193 * @param repo repository handle to close. If NULL nothing occurs.
195 GIT_EXTERN(void) git_repository_free(git_repository
*repo
);
198 * Creates a new Git repository in the given folder.
201 * - Reinit the repository
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
210 * @return 0 or an error code
212 GIT_EXTERN(int) git_repository_init(
213 git_repository
**out
,
218 * Option flags for `git_repository_init_ext`.
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.
227 * Create a bare repository with no working directory.
229 GIT_REPOSITORY_INIT_BARE
= (1u << 0),
232 * Return an GIT_EEXISTS error if the repo_path appears to already be
235 GIT_REPOSITORY_INIT_NO_REINIT
= (1u << 1),
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.
242 GIT_REPOSITORY_INIT_NO_DOTGIT_DIR
= (1u << 2),
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
250 GIT_REPOSITORY_INIT_MKDIR
= (1u << 3),
253 * Recursively make all components of the repo and workdir paths as
256 GIT_REPOSITORY_INIT_MKPATH
= (1u << 4),
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.
264 GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE
= (1u << 5),
267 * If an alternate workdir is specified, use relative paths for the gitdir
270 GIT_REPOSITORY_INIT_RELATIVE_GITLINK
= (1u << 6),
271 } git_repository_init_flag_t
;
274 * Mode options for `git_repository_init_ext`.
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
282 * Use permissions configured by umask - the default.
284 GIT_REPOSITORY_INIT_SHARED_UMASK
= 0,
287 * Use "--shared=group" behavior, chmod'ing the new repo to be group
288 * writable and "g+sx" for sticky group assignment.
290 GIT_REPOSITORY_INIT_SHARED_GROUP
= 0002775,
293 * Use "--shared=all" behavior, adding world readability.
295 GIT_REPOSITORY_INIT_SHARED_ALL
= 0002777,
296 } git_repository_init_mode_t
;
299 * Extended options structure for `git_repository_init_ext`.
301 * This contains extra options for `git_repository_init_ext` that enable
302 * additional initialization features.
305 unsigned int version
;
308 * Combination of GIT_REPOSITORY_INIT flags above.
313 * Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... constants
314 * above, or to a custom value that you would like.
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
325 const char *workdir_path
;
328 * If set, this will be used to initialize the "description" file in the
329 * repository, instead of using the template content.
331 const char *description
;
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.
338 const char *template_path
;
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.
346 const char *initial_head
;
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.
353 const char *origin_url
;
354 } git_repository_init_options
;
356 #define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1
357 #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION}
360 * Initialize git_repository_init_options structure
362 * Initializes a `git_repository_init_options` with default values. Equivalent to
363 * creating an instance with `GIT_REPOSITORY_INIT_OPTIONS_INIT`.
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.
369 GIT_EXTERN(int) git_repository_init_options_init(
370 git_repository_init_options
*opts
,
371 unsigned int version
);
374 * Create a new Git repository in the given folder with extended controls.
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.
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.
386 GIT_EXTERN(int) git_repository_init_ext(
387 git_repository
**out
,
388 const char *repo_path
,
389 git_repository_init_options
*opts
);
392 * Retrieve and resolve the reference pointed at by HEAD.
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.
398 * @param out pointer to the reference which will be retrieved
399 * @param repo a repository object
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
404 GIT_EXTERN(int) git_repository_head(git_reference
**out
, git_repository
*repo
);
407 * Retrieve the referenced HEAD for the worktree
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
414 GIT_EXTERN(int) git_repository_head_for_worktree(git_reference
**out
, git_repository
*repo
,
418 * Check if a repository's HEAD is detached
420 * A repository's HEAD is detached when it points directly to a commit
421 * instead of a branch.
423 * @param repo Repo to test
424 * @return 1 if HEAD is detached, 0 if it's not; error code if there
427 GIT_EXTERN(int) git_repository_head_detached(git_repository
*repo
);
430 * Check if a worktree's HEAD is detached
432 * A worktree's HEAD is detached when it points directly to a
433 * commit instead of a branch.
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
440 GIT_EXTERN(int) git_repository_head_detached_for_worktree(git_repository
*repo
,
444 * Check if the current branch is unborn
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.
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
453 GIT_EXTERN(int) git_repository_head_unborn(git_repository
*repo
);
456 * Check if a repository is empty
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.
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
465 GIT_EXTERN(int) git_repository_is_empty(git_repository
*repo
);
468 * List of items which belong to the git repository layout
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
;
489 * Get the location of a specific repository file or directory
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.
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
502 GIT_EXTERN(int) git_repository_item_path(git_buf
*out
, const git_repository
*repo
, git_repository_item_t item
);
505 * Get the path of this repository
507 * This is the path of the `.git` folder for normal repositories,
508 * or of the repository itself for bare repositories.
510 * @param repo A repository object
511 * @return the path to the repository
513 GIT_EXTERN(const char *) git_repository_path(const git_repository
*repo
);
516 * Get the path of the working directory for this repository
518 * If the repository is bare, this function will always return
521 * @param repo A repository object
522 * @return the path to the working dir, if it exists
524 GIT_EXTERN(const char *) git_repository_workdir(const git_repository
*repo
);
527 * Get the path of the shared common directory for this repository.
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.
533 * @param repo A repository object
534 * @return the path to the common dir
536 GIT_EXTERN(const char *) git_repository_commondir(const git_repository
*repo
);
539 * Set the path to the working directory for this repository
541 * The working directory doesn't need to be the same one
542 * that contains the `.git` folder for this repository.
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).
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
555 GIT_EXTERN(int) git_repository_set_workdir(
556 git_repository
*repo
, const char *workdir
, int update_gitlink
);
559 * Check if a repository is bare
561 * @param repo Repo to test
562 * @return 1 if the repository is bare, 0 otherwise.
564 GIT_EXTERN(int) git_repository_is_bare(const git_repository
*repo
);
567 * Check if a repository is a linked work tree
569 * @param repo Repo to test
570 * @return 1 if the repository is a linked work tree, 0 otherwise.
572 GIT_EXTERN(int) git_repository_is_worktree(const git_repository
*repo
);
575 * Get the configuration file for this repository.
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).
581 * The configuration file must be freed once it's no longer
582 * being used by the user.
584 * @param out Pointer to store the loaded configuration
585 * @param repo A repository object
586 * @return 0, or an error code
588 GIT_EXTERN(int) git_repository_config(git_config
**out
, git_repository
*repo
);
591 * Get a snapshot of the repository's configuration
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.
597 * The configuration file must be freed once it's no longer
598 * being used by the user.
600 * @param out Pointer to store the loaded configuration
601 * @param repo the repository
602 * @return 0, or an error code
604 GIT_EXTERN(int) git_repository_config_snapshot(git_config
**out
, git_repository
*repo
);
607 * Get the Object Database for this repository.
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`).
613 * The ODB must be freed once it's no longer being used by
616 * @param out Pointer to store the loaded ODB
617 * @param repo A repository object
618 * @return 0, or an error code
620 GIT_EXTERN(int) git_repository_odb(git_odb
**out
, git_repository
*repo
);
623 * Get the Reference Database Backend for this repository.
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).
629 * The refdb must be freed once it's no longer being used by
632 * @param out Pointer to store the loaded refdb
633 * @param repo A repository object
634 * @return 0, or an error code
636 GIT_EXTERN(int) git_repository_refdb(git_refdb
**out
, git_repository
*repo
);
639 * Get the Index file for this repository.
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`).
645 * The index must be freed once it's no longer being used by
648 * @param out Pointer to store the loaded index
649 * @param repo A repository object
650 * @return 0, or an error code
652 GIT_EXTERN(int) git_repository_index(git_index
**out
, git_repository
*repo
);
655 * Retrieve git's prepared message
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
663 * Use this function to get the contents of this file. Don't forget to
664 * remove the file after you create the commit.
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
670 GIT_EXTERN(int) git_repository_message(git_buf
*out
, git_repository
*repo
);
673 * Remove git's prepared message.
675 * Remove the message that `git_repository_message` retrieves.
677 GIT_EXTERN(int) git_repository_message_remove(git_repository
*repo
);
680 * Remove all the metadata associated with an ongoing command like merge,
681 * revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc.
683 * @param repo A repository object
684 * @return 0 on success, or error
686 GIT_EXTERN(int) git_repository_state_cleanup(git_repository
*repo
);
689 * Callback used to iterate over each FETCH_HEAD entry
691 * @see git_repository_fetchhead_foreach
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
700 typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb
)(const char *ref_name
,
701 const char *remote_url
,
703 unsigned int is_merge
,
707 * Invoke 'callback' for each entry in the given FETCH_HEAD file.
709 * Return a non-zero value from the callback to stop the loop.
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.
717 GIT_EXTERN(int) git_repository_fetchhead_foreach(
718 git_repository
*repo
,
719 git_repository_fetchhead_foreach_cb callback
,
723 * Callback used to iterate over each MERGE_HEAD entry
725 * @see git_repository_mergehead_foreach
727 * @param oid The merge OID
728 * @param payload Payload passed to git_repository_mergehead_foreach
729 * @return non-zero to terminate the iteration
731 typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb
)(const git_oid
*oid
,
735 * If a merge is in progress, invoke 'callback' for each commit ID in the
738 * Return a non-zero value from the callback to stop the loop.
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.
746 GIT_EXTERN(int) git_repository_mergehead_foreach(
747 git_repository
*repo
,
748 git_repository_mergehead_foreach_cb callback
,
752 * Calculate hash of file using repository filtering rules.
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.
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.
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. This
766 * may be an absolute path or a relative path, in which case it
767 * will be treated as a path within the working directory.
768 * @param type The object type to hash as (e.g. GIT_OBJECT_BLOB)
769 * @param as_path The path to use to look up filtering rules. If this is
770 * an empty string then no filters will be applied when
771 * calculating the hash. If this is `NULL` and the `path`
772 * parameter is a file within the repository's working
773 * directory, then the `path` will be used.
774 * @return 0 on success, or an error code
776 GIT_EXTERN(int) git_repository_hashfile(
778 git_repository
*repo
,
781 const char *as_path
);
784 * Make the repository HEAD point to the specified reference.
786 * If the provided reference points to a Tree or a Blob, the HEAD is
787 * unaltered and -1 is returned.
789 * If the provided reference points to a branch, the HEAD will point
790 * to that branch, staying attached, or become attached if it isn't yet.
791 * If the branch doesn't exist yet, no error will be return. The HEAD
792 * will then be attached to an unborn branch.
794 * Otherwise, the HEAD will be detached and will directly point to
797 * @param repo Repository pointer
798 * @param refname Canonical name of the reference the HEAD should point at
799 * @return 0 on success, or an error code
801 GIT_EXTERN(int) git_repository_set_head(
802 git_repository
*repo
,
803 const char *refname
);
806 * Make the repository HEAD directly point to the Commit.
808 * If the provided committish cannot be found in the repository, the HEAD
809 * is unaltered and GIT_ENOTFOUND is returned.
811 * If the provided commitish cannot be peeled into a commit, the HEAD
812 * is unaltered and -1 is returned.
814 * Otherwise, the HEAD will eventually be detached and will directly point to
817 * @param repo Repository pointer
818 * @param commitish Object id of the Commit the HEAD should point to
819 * @return 0 on success, or an error code
821 GIT_EXTERN(int) git_repository_set_head_detached(
822 git_repository
*repo
,
823 const git_oid
*commitish
);
826 * Make the repository HEAD directly point to the Commit.
828 * This behaves like `git_repository_set_head_detached()` but takes an
829 * annotated commit, which lets you specify which extended sha syntax
830 * string was specified by a user, allowing for more exact reflog
833 * See the documentation for `git_repository_set_head_detached()`.
835 * @see git_repository_set_head_detached
837 GIT_EXTERN(int) git_repository_set_head_detached_from_annotated(
838 git_repository
*repo
,
839 const git_annotated_commit
*commitish
);
844 * If the HEAD is already detached and points to a Commit, 0 is returned.
846 * If the HEAD is already detached and points to a Tag, the HEAD is
847 * updated into making it point to the peeled Commit, and 0 is returned.
849 * If the HEAD is already detached and points to a non commitish, the HEAD is
850 * unaltered, and -1 is returned.
852 * Otherwise, the HEAD will be detached and point to the peeled Commit.
854 * @param repo Repository pointer
855 * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
856 * branch or an error code
858 GIT_EXTERN(int) git_repository_detach_head(
859 git_repository
*repo
);
864 * These values represent possible states for the repository to be in,
865 * based on the current operation which is ongoing.
868 GIT_REPOSITORY_STATE_NONE
,
869 GIT_REPOSITORY_STATE_MERGE
,
870 GIT_REPOSITORY_STATE_REVERT
,
871 GIT_REPOSITORY_STATE_REVERT_SEQUENCE
,
872 GIT_REPOSITORY_STATE_CHERRYPICK
,
873 GIT_REPOSITORY_STATE_CHERRYPICK_SEQUENCE
,
874 GIT_REPOSITORY_STATE_BISECT
,
875 GIT_REPOSITORY_STATE_REBASE
,
876 GIT_REPOSITORY_STATE_REBASE_INTERACTIVE
,
877 GIT_REPOSITORY_STATE_REBASE_MERGE
,
878 GIT_REPOSITORY_STATE_APPLY_MAILBOX
,
879 GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE
,
880 } git_repository_state_t
;
883 * Determines the status of a git repository - ie, whether an operation
884 * (merge, cherry-pick, etc) is in progress.
886 * @param repo Repository pointer
887 * @return The state of the repository
889 GIT_EXTERN(int) git_repository_state(git_repository
*repo
);
892 * Sets the active namespace for this Git Repository
894 * This namespace affects all reference operations for the repo.
895 * See `man gitnamespaces`
897 * @param repo The repo
898 * @param nmspace The namespace. This should not include the refs
899 * folder, e.g. to namespace all references under `refs/namespaces/foo/`,
900 * use `foo` as the namespace.
901 * @return 0 on success, -1 on error
903 GIT_EXTERN(int) git_repository_set_namespace(git_repository
*repo
, const char *nmspace
);
906 * Get the currently active namespace for this repository
908 * @param repo The repo
909 * @return the active namespace, or NULL if there isn't one
911 GIT_EXTERN(const char *) git_repository_get_namespace(git_repository
*repo
);
915 * Determine if the repository was a shallow clone
917 * @param repo The repository
918 * @return 1 if shallow, zero if not
920 GIT_EXTERN(int) git_repository_is_shallow(git_repository
*repo
);
923 * Retrieve the configured identity to use for reflogs
925 * The memory is owned by the repository and must not be freed by the
928 * @param name where to store the pointer to the name
929 * @param email where to store the pointer to the email
930 * @param repo the repository
932 GIT_EXTERN(int) git_repository_ident(const char **name
, const char **email
, const git_repository
*repo
);
935 * Set the identity to be used for writing reflogs
937 * If both are set, this name and email will be used to write to the
938 * reflog. Pass NULL to unset. When unset, the identity will be taken
939 * from the repository's configuration.
941 * @param repo the repository to configure
942 * @param name the name to use for the reflog entries
943 * @param email the email to use for the reflog entries
945 GIT_EXTERN(int) git_repository_set_ident(git_repository
*repo
, const char *name
, const char *email
);