* Copyright (C) the libgit2 contributors. All rights reserved.
* This file is part of libgit2, distributed under the GNU GPL v2 with
* a Linking Exception. For full terms see the included COPYING file.
#ifndef INCLUDE_git_repository_h__
#define INCLUDE_git_repository_h__
* @file git2/repository.h
* @brief Git repository management routines
* @defgroup git_repository Git repository management routines
* The 'path' argument must point to either a git repository
* folder, or an existing work dir.
* The method will automatically detect if 'path' is a normal
* or bare repository or fail is 'path' is neither.
* @param out pointer to the repo which will be opened
* @param path the path to the repository
* @return 0 or an error code
GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path);
* Open working tree as a repository
* Open the working directory of the working tree as a normal
* repository that can then be worked on.
* @param out Output pointer containing opened repository
* @param wt Working tree to open
* @return 0 or an error code
GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_worktree *wt);
* Create a "fake" repository to wrap an object database
* Create a repository object to wrap an object database to be used
* with the API when all you have is an object database. This doesn't
* have any paths associated with it, so use with care.
* @param out pointer to the repo
* @param odb the object database to wrap
* @return 0 or an error code
GIT_EXTERN(int) git_repository_wrap_odb(git_repository **out, git_odb *odb);
* Look for a git repository and copy its path in the given buffer.
* The lookup start from base_path and walk across parent directories
* if nothing has been found. The lookup ends when the first repository
* is found, or when reaching a directory referenced in ceiling_dirs
* or when the filesystem changes (in case across_fs is true).
* The method will automatically detect if the repository is bare
* (if there is a repository).
* @param out A pointer to a user-allocated git_buf which will contain
* @param start_path The base path where the lookup starts.
* @param across_fs If true, then the lookup will not stop when a
* filesystem device change is detected while exploring parent directories.
* @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR separated list of
* absolute symbolic link free paths. The lookup will stop when any
* of this paths is reached. Note that the lookup always performs on
* start_path no matter start_path appears in ceiling_dirs ceiling_dirs
* might be NULL (which is equivalent to an empty string)
* @return 0 or an error code
GIT_EXTERN(int) git_repository_discover(
const char *ceiling_dirs);
* Option flags for `git_repository_open_ext`.
* Only open the repository if it can be immediately found in the
* start_path. Do not walk up from the start_path looking at parent
GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0),
* Unless this flag is set, open will not continue searching across
* filesystem boundaries (i.e. when `st_dev` changes from the `stat`
* system call). For example, searching in a user's home directory at
* "/home/user/source/" will not return "/.git/" as the found repo if
* "/" is a different filesystem than "/home".
GIT_REPOSITORY_OPEN_CROSS_FS = (1 << 1),
* Open repository as a bare repo regardless of core.bare config, and
* defer loading config file for faster setup.
* Unlike `git_repository_open_bare`, this can follow gitlinks.
GIT_REPOSITORY_OPEN_BARE = (1 << 2),
* Do not check for a repository by appending /.git to the start_path;
* only open the repository if start_path itself points to the git
GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3),
* Find and open a git repository, respecting the environment variables
* used by the git command-line tools.
* If set, `git_repository_open_ext` will ignore the other flags and
* the `ceiling_dirs` argument, and will allow a NULL `path` to use
* `GIT_DIR` or search from the current directory.
* The search for a repository will respect $GIT_CEILING_DIRECTORIES and
* $GIT_DISCOVERY_ACROSS_FILESYSTEM. The opened repository will
* respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and
* $GIT_ALTERNATE_OBJECT_DIRECTORIES.
* In the future, this flag will also cause `git_repository_open_ext`
* to respect $GIT_WORK_TREE and $GIT_COMMON_DIR; currently,
* `git_repository_open_ext` with this flag will error out if either
* $GIT_WORK_TREE or $GIT_COMMON_DIR is set.
GIT_REPOSITORY_OPEN_FROM_ENV = (1 << 4),
} git_repository_open_flag_t;
* Find and open a repository with extended controls.
* @param out Pointer to the repo which will be opened. This can
* actually be NULL if you only want to use the error code to
* see if a repo at this path could be opened.
* @param path Path to open as git repository. If the flags
* permit "searching", then this can be a path to a subdirectory
* inside the working directory of the repository. May be NULL if
* flags is GIT_REPOSITORY_OPEN_FROM_ENV.
* @param flags A combination of the GIT_REPOSITORY_OPEN flags above.
* @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR delimited list of path
* prefixes at which the search for a containing repository should
* @return 0 on success, GIT_ENOTFOUND if no repository could be found,
* or -1 if there was a repository but open failed for some reason
* (such as repo corruption or system errors).
GIT_EXTERN(int) git_repository_open_ext(
const char *ceiling_dirs);
* Open a bare repository on the serverside.
* This is a fast open for bare repositories that will come in handy
* if you're e.g. hosting git repositories and need to access them
* @param out Pointer to the repo which will be opened.
* @param bare_path Direct path to the bare repository
* @return 0 on success, or an error code
GIT_EXTERN(int) git_repository_open_bare(git_repository **out, const char *bare_path);
* Free a previously allocated repository
* Note that after a repository is free'd, all the objects it has spawned
* will still exist until they are manually closed by the user
* with `git_object_free`, but accessing any of the attributes of
* an object without a backing repository will result in undefined
* @param repo repository handle to close. If NULL nothing occurs.
GIT_EXTERN(void) git_repository_free(git_repository *repo);
* Creates a new Git repository in the given folder.
* - Reinit the repository
* @param out pointer to the repo which will be created or reinitialized
* @param path the path to the repository
* @param is_bare if true, a Git repository without a working directory is
* created at the pointed path. If false, provided path will be
* considered as the working directory into which the .git directory
* @return 0 or an error code
GIT_EXTERN(int) git_repository_init(
* Option flags for `git_repository_init_ext`.
* These flags configure extra behaviors to `git_repository_init_ext`.
* In every case, the default behavior is the zero value (i.e. flag is
* not set). Just OR the flag values together for the `flags` parameter
* when initializing a new repo. Details of individual values are:
* * BARE - Create a bare repository with no working directory.
* * NO_REINIT - Return an GIT_EEXISTS error if the repo_path appears to
* already be an git repository.
* * NO_DOTGIT_DIR - Normally a "/.git/" will be appended to the repo
* path for non-bare repos (if it is not already there), but
* passing this flag prevents that behavior.
* * MKDIR - Make the repo_path (and workdir_path) as needed. Init is
* always willing to create the ".git" directory even without this
* flag. This flag tells init to create the trailing component of
* the repo and workdir paths as needed.
* * MKPATH - Recursively make all components of the repo and workdir
* * EXTERNAL_TEMPLATE - libgit2 normally uses internal templates to
* initialize a new repo. This flags enables external templates,
* looking the "template_path" from the options if set, or the
* `init.templatedir` global config if not, or falling back on
* "/usr/share/git-core/templates" if it exists.
* * GIT_REPOSITORY_INIT_RELATIVE_GITLINK - If an alternate workdir is
* specified, use relative paths for the gitdir and core.worktree.
GIT_REPOSITORY_INIT_BARE = (1u << 0),
GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1),
GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2),
GIT_REPOSITORY_INIT_MKDIR = (1u << 3),
GIT_REPOSITORY_INIT_MKPATH = (1u << 4),
GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5),
GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6),
} git_repository_init_flag_t;
* Mode options for `git_repository_init_ext`.
* Set the mode field of the `git_repository_init_options` structure
* either to the custom mode that you would like, or to one of the
* * SHARED_UMASK - Use permissions configured by umask - the default.
* * SHARED_GROUP - Use "--shared=group" behavior, chmod'ing the new repo
* to be group writable and "g+sx" for sticky group assignment.
* * SHARED_ALL - Use "--shared=all" behavior, adding world readability.
* * Anything else - Set to custom value.
GIT_REPOSITORY_INIT_SHARED_UMASK = 0,
GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775,
GIT_REPOSITORY_INIT_SHARED_ALL = 0002777,
} git_repository_init_mode_t;
* Extended options structure for `git_repository_init_ext`.
* This contains extra options for `git_repository_init_ext` that enable
* additional initialization features. The fields are:
* * flags - Combination of GIT_REPOSITORY_INIT flags above.
* * mode - Set to one of the standard GIT_REPOSITORY_INIT_SHARED_...
* constants above, or to a custom value that you would like.
* * workdir_path - The path to the working dir or NULL for default (i.e.
* repo_path parent on non-bare repos). IF THIS IS RELATIVE PATH,
* IT WILL BE EVALUATED RELATIVE TO THE REPO_PATH. If this is not
* the "natural" working directory, a .git gitlink file will be
* created here linking to the repo_path.
* * description - If set, this will be used to initialize the "description"
* file in the repository, instead of using the template content.
* * template_path - When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set,
* this contains the path to use for the template directory. If
* this is NULL, the config or default directory options will be
* * initial_head - The name of the head to point HEAD at. If NULL, then
* this will be treated as "master" and the HEAD ref will be set
* to "refs/heads/master". If this begins with "refs/" it will be
* used verbatim; otherwise "refs/heads/" will be prefixed.
* * origin_url - If this is non-NULL, then after the rest of the
* repository initialization is completed, an "origin" remote
* will be added pointing to this URL.
const char *workdir_path;
const char *template_path;
const char *initial_head;
} git_repository_init_options;
#define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1
#define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION}
* Initialize git_repository_init_options structure
* Initializes a `git_repository_init_options` with default values. Equivalent to
* creating an instance with `GIT_REPOSITORY_INIT_OPTIONS_INIT`.
* @param opts The `git_repository_init_options` struct to initialize.
* @param version The struct version; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`.
* @return Zero on success; -1 on failure.
GIT_EXTERN(int) git_repository_init_options_init(
git_repository_init_options *opts,
* Create a new Git repository in the given folder with extended controls.
* This will initialize a new git repository (creating the repo_path
* if requested by flags) and working directory as needed. It will
* auto-detect the case sensitivity of the file system and if the
* file system supports file mode bits correctly.
* @param out Pointer to the repo which will be created or reinitialized.
* @param repo_path The path to the repository.
* @param opts Pointer to git_repository_init_options struct.
* @return 0 or an error code on failure.
GIT_EXTERN(int) git_repository_init_ext(
git_repository_init_options *opts);
* Retrieve and resolve the reference pointed at by HEAD.
* The returned `git_reference` will be owned by caller and
* `git_reference_free()` must be called when done with it to release the
* allocated memory and prevent a leak.
* @param out pointer to the reference which will be retrieved
* @param repo a repository object
* @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
* branch, GIT_ENOTFOUND when HEAD is missing; an error code otherwise
GIT_EXTERN(int) git_repository_head(git_reference **out, git_repository *repo);
* Retrieve the referenced HEAD for the worktree
* @param out pointer to the reference which will be retrieved
* @param repo a repository object
* @param name name of the worktree to retrieve HEAD for
* @return 0 when successful, error-code otherwise
GIT_EXTERN(int) git_repository_head_for_worktree(git_reference **out, git_repository *repo,
* Check if a repository's HEAD is detached
* A repository's HEAD is detached when it points directly to a commit
* @param repo Repo to test
* @return 1 if HEAD is detached, 0 if it's not; error code if there
GIT_EXTERN(int) git_repository_head_detached(git_repository *repo);
* Check if a worktree's HEAD is detached
* A worktree's HEAD is detached when it points directly to a
* commit instead of a branch.
* @param repo a repository object
* @param name name of the worktree to retrieve HEAD for
* @return 1 if HEAD is detached, 0 if its not; error code if
GIT_EXTERN(int) git_repository_head_detached_for_worktree(git_repository *repo,
* Check if the current branch is unborn
* An unborn branch is one named from HEAD but which doesn't exist in
* the refs namespace, because it doesn't have any commit to point to.
* @param repo Repo to test
* @return 1 if the current branch is unborn, 0 if it's not; error
* code if there was an error
GIT_EXTERN(int) git_repository_head_unborn(git_repository *repo);
* Check if a repository is empty
* An empty repository has just been initialized and contains no references
* apart from HEAD, which must be pointing to the unborn master branch.
* @param repo Repo to test
* @return 1 if the repository is empty, 0 if it isn't, error code
* if the repository is corrupted
GIT_EXTERN(int) git_repository_is_empty(git_repository *repo);
* List of items which belong to the git repository layout
GIT_REPOSITORY_ITEM_GITDIR,
GIT_REPOSITORY_ITEM_WORKDIR,
GIT_REPOSITORY_ITEM_COMMONDIR,
GIT_REPOSITORY_ITEM_INDEX,
GIT_REPOSITORY_ITEM_OBJECTS,
GIT_REPOSITORY_ITEM_REFS,
GIT_REPOSITORY_ITEM_PACKED_REFS,
GIT_REPOSITORY_ITEM_REMOTES,
GIT_REPOSITORY_ITEM_CONFIG,
GIT_REPOSITORY_ITEM_INFO,
GIT_REPOSITORY_ITEM_HOOKS,
GIT_REPOSITORY_ITEM_LOGS,
GIT_REPOSITORY_ITEM_MODULES,
GIT_REPOSITORY_ITEM_WORKTREES,
GIT_REPOSITORY_ITEM__LAST
* Get the location of a specific repository file or directory
* This function will retrieve the path of a specific repository
* item. It will thereby honor things like the repository's
* common directory, gitdir, etc. In case a file path cannot
* exist for a given item (e.g. the working directory of a bare
* repository), GIT_ENOTFOUND is returned.
* @param out Buffer to store the path at
* @param repo Repository to get path for
* @param item The repository item for which to retrieve the path
* @return 0, GIT_ENOTFOUND if the path cannot exist or an error code
GIT_EXTERN(int) git_repository_item_path(git_buf *out, const git_repository *repo, git_repository_item_t item);
* Get the path of this repository
* This is the path of the `.git` folder for normal repositories,
* or of the repository itself for bare repositories.
* @param repo A repository object
* @return the path to the repository
GIT_EXTERN(const char *) git_repository_path(const git_repository *repo);
* Get the path of the working directory for this repository
* If the repository is bare, this function will always return
* @param repo A repository object
* @return the path to the working dir, if it exists
GIT_EXTERN(const char *) git_repository_workdir(const git_repository *repo);
* Get the path of the shared common directory for this repository.
* If the repository is bare, it is the root directory for the repository.
* If the repository is a worktree, it is the parent repo's gitdir.
* Otherwise, it is the gitdir.
* @param repo A repository object
* @return the path to the common dir
GIT_EXTERN(const char *) git_repository_commondir(const git_repository *repo);
* Set the path to the working directory for this repository
* The working directory doesn't need to be the same one
* that contains the `.git` folder for this repository.
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
