/* * 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__ #include "common.h" #include "types.h" #include "oid.h" #include "buffer.h" /** * @file git2/repository.h * @brief Git repository management routines * @defgroup git_repository Git repository management routines * @ingroup Git * @{ */ GIT_BEGIN_DECL /** * Open a git repository. * * 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); /** * 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 * the found path. * * @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( git_buf *out, const char *start_path, int across_fs, const char *ceiling_dirs); /** * Option flags for `git_repository_open_ext`. * * * GIT_REPOSITORY_OPEN_NO_SEARCH - 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 directories. * * GIT_REPOSITORY_OPEN_CROSS_FS - Unless this flag is set, open will not * continue searching across filesystem boundaries (i.e. when `st_dev` * changes from the `stat` system call). (E.g. Searching in a user's home * directory "/home/user/source/" will not return "/.git/" as the found * repo if "/" is a different filesystem than "/home".) * * GIT_REPOSITORY_OPEN_BARE - 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. */ typedef enum { GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0), GIT_REPOSITORY_OPEN_CROSS_FS = (1 << 1), GIT_REPOSITORY_OPEN_BARE = (1 << 2), } 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. * @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 * terminate. * @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( git_repository **out, const char *path, unsigned int flags, 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 * efficiently * * @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 * behavior * * @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. * * TODO: * - 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 * will be created. * * @return 0 or an error code */ GIT_EXTERN(int) git_repository_init( git_repository **out, const char *path, unsigned is_bare); /** * 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 * paths as necessary. * * 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. */ typedef enum { 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 * following modes: * * * 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. */ typedef enum { 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 * used instead. * * 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. */ typedef struct { unsigned int version; uint32_t flags; uint32_t mode; const char *workdir_path; const char *description; const char *template_path; const char *initial_head; const char *origin_url; } git_repository_init_options; #define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1 #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION} /** * 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 Version of struct; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION` * @return Zero on success; -1 on failure. */ GIT_EXTERN(int) git_repository_init_init_options( git_repository_init_options *opts, unsigned int version); /** * 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 **out, const char *repo_path, 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); /** * Check if a repository's HEAD is detached * * A repository's HEAD is detached when it points directly to a commit * instead of a branch. * * @param repo Repo to test * @return 1 if HEAD is detached, 0 if it's not; error code if there * was an error. */ GIT_EXTERN(int) git_repository_head_detached(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); /** * 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(git_repository *repo); /** * Get the path of the working directory for this repository * * If the repository is bare, this function will always return * NULL. * * @param repo A repository object * @return the path to the working dir, if it exists */ GIT_EXTERN(const char *) git_repository_workdir(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. * * If this repository is bare, setting its working directory * will turn it into a normal repository, capable of performing * all the common workdir operations (checkout, status, index * manipulation, etc). * * @param repo A repository object * @param workdir The path to a working directory * @param update_gitlink Create/update gitlink in workdir and set config * "core.worktree" (if workdir is not the parent of the .git directory) * @return 0, or an error code */ GIT_EXTERN(int) git_repository_set_workdir( git_repository *repo, const char *workdir, int update_gitlink); /** * Check if a repository is bare * * @param repo Repo to test * @return 1 if the repository is bare, 0 otherwise. */ GIT_EXTERN(int) git_repository_is_bare(git_repository *repo); /** * Get the configuration file for this repository. * * If a configuration file has not been set, the default * config set for the repository will be returned, including * global and system configurations (if they are available). * * The configuration file must be freed once it's no longer * being used by the user. * * @param out Pointer to store the loaded configuration * @param repo A repository object * @return 0, or an error code */ GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo); /** * Get a snapshot of the repository's configuration * * Convenience function to take a snapshot from the repository's * configuration. The contents of this snapshot will not change, * even if the underlying config files are modified. * * The configuration file must be freed once it's no longer * being used by the user. * * @param out Pointer to store the loaded configuration * @param repo the repository * @return 0, or an error code */ GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository *repo); /** * Get the Object Database for this repository. * * If a custom ODB has not been set, the default * database for the repository will be returned (the one * located in `.git/objects`). * * The ODB must be freed once it's no longer being used by * the user. * * @param out Pointer to store the loaded ODB * @param repo A repository object * @return 0, or an error code */ GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo); /** * Get the Reference Database Backend for this repository. * * If a custom refsdb has not been set, the default database for * the repository will be returned (the one that manipulates loose * and packed references in the `.git` directory). * * The refdb must be freed once it's no longer being used by * the user. * * @param out Pointer to store the loaded refdb * @param repo A repository object * @return 0, or an error code */ GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo); /** * Get the Index file for this repository. * * If a custom index has not been set, the default * index for the repository will be returned (the one * located in `.git/index`). * * The index must be freed once it's no longer being used by * the user. * * @param out Pointer to store the loaded index * @param repo A repository object * @return 0, or an error code */ GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo); /** * Retrieve git's prepared message * * Operations such as git revert/cherry-pick/merge with the -n option * stop just short of creating a commit with the changes and save * their prepared message in .git/MERGE_MSG so the next git-commit * execution can present it to the user for them to amend if they * wish. * * Use this function to get the contents of this file. Don't forget to * remove the file after you create the commit. * * @param out git_buf to write data into * @param repo Repository to read prepared message from * @return 0, GIT_ENOTFOUND if no message exists or an error code */ GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo); /** * Remove git's prepared message. * * Remove the message that `git_repository_message` retrieves. */ GIT_EXTERN(int) git_repository_message_remove(git_repository *repo); /** * Remove all the metadata associated with an ongoing command like merge, * revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc. * * @param repo A repository object * @return 0 on success, or error */ GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo); typedef int (*git_repository_fetchhead_foreach_cb)(const char *ref_name, const char *remote_url, const git_oid *oid, unsigned int is_merge, void *payload); /** * Invoke 'callback' for each entry in the given FETCH_HEAD file. * * Return a non-zero value from the callback to stop the loop. * * @param repo A repository object * @param callback Callback function * @param payload Pointer to callback data (optional) * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if * there is no FETCH_HEAD file, or other error code. */ GIT_EXTERN(int) git_repository_fetchhead_foreach( git_repository *repo, git_repository_fetchhead_foreach_cb callback, void *payload); typedef int (*git_repository_mergehead_foreach_cb)(const git_oid *oid, void *payload); /** * If a merge is in progress, invoke 'callback' for each commit ID in the * MERGE_HEAD file. * * Return a non-zero value from the callback to stop the loop. * * @param repo A repository object * @param callback Callback function * @param payload Pointer to callback data (optional) * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if * there is no MERGE_HEAD file, or other error code. */ GIT_EXTERN(int) git_repository_mergehead_foreach( git_repository *repo, git_repository_mergehead_foreach_cb callback, void *payload); /** * Calculate hash of file using repository filtering rules. * * If you simply want to calculate the hash of a file on disk with no filters, * you can just use the `git_odb_hashfile()` API. However, if you want to * hash a file in the repository and you want to apply filtering rules (e.g. * crlf filters) before generating the SHA, then use this function. * * Note: if the repository has `core.safecrlf` set to fail and the * filtering triggers that failure, then this function will return an * error and not calculate the hash of the file. * * @param out Output value of calculated SHA * @param repo Repository pointer * @param path Path to file on disk whose contents should be hashed. If the * repository is not NULL, this can be a relative path. * @param type The object type to hash as (e.g. GIT_OBJ_BLOB) * @param as_path The path to use to look up filtering rules. If this is * NULL, then the `path` parameter will be used instead. If * this is passed as the empty string, then no filters will be * applied when calculating the hash. * @return 0 on success, or an error code */ GIT_EXTERN(int) git_repository_hashfile( git_oid *out, git_repository *repo, const char *path, git_otype type, const char *as_path); /** * Make the repository HEAD point to the specified reference. * * If the provided reference points to a Tree or a Blob, the HEAD is * unaltered and -1 is returned. * * If the provided reference points to a branch, the HEAD will point * to that branch, staying attached, or become attached if it isn't yet. * If the branch doesn't exist yet, no error will be return. The HEAD * will then be attached to an unborn branch. * * Otherwise, the HEAD will be detached and will directly point to * the Commit. * * @param repo Repository pointer * @param refname Canonical name of the reference the HEAD should point at * @return 0 on success, or an error code */ GIT_EXTERN(int) git_repository_set_head( git_repository* repo, const char* refname); /** * Make the repository HEAD directly point to the Commit. * * If the provided committish cannot be found in the repository, the HEAD * is unaltered and GIT_ENOTFOUND is returned. * * If the provided commitish cannot be peeled into a commit, the HEAD * is unaltered and -1 is returned. * * Otherwise, the HEAD will eventually be detached and will directly point to * the peeled Commit. * * @param repo Repository pointer * @param commitish Object id of the Commit the HEAD should point to * @return 0 on success, or an error code */ GIT_EXTERN(int) git_repository_set_head_detached( git_repository* repo, const git_oid* commitish); /** * Make the repository HEAD directly point to the Commit. * * This behaves like `git_repository_set_head_detached()` but takes an * annotated commit, which lets you specify which extended sha syntax * string was specified by a user, allowing for more exact reflog * messages. * * See the documentation for `git_repository_set_head_detached()`. * * @see git_repository_set_head_detached */ GIT_EXTERN(int) git_repository_set_head_detached_from_annotated( git_repository *repo, const git_annotated_commit *commitish); /** * Detach the HEAD. * * If the HEAD is already detached and points to a Commit, 0 is returned. * * If the HEAD is already detached and points to a Tag, the HEAD is * updated into making it point to the peeled Commit, and 0 is returned. * * If the HEAD is already detached and points to a non commitish, the HEAD is * unaltered, and -1 is returned. * * Otherwise, the HEAD will be detached and point to the peeled Commit. * * @param repo Repository pointer * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing * branch or an error code */ GIT_EXTERN(int) git_repository_detach_head( git_repository* repo); /** * Repository state * * These values represent possible states for the repository to be in, * based on the current operation which is ongoing. */ typedef enum { GIT_REPOSITORY_STATE_NONE, GIT_REPOSITORY_STATE_MERGE, GIT_REPOSITORY_STATE_REVERT, GIT_REPOSITORY_STATE_REVERT_SEQUENCE, GIT_REPOSITORY_STATE_CHERRYPICK, GIT_REPOSITORY_STATE_CHERRYPICK_SEQUENCE, GIT_REPOSITORY_STATE_BISECT, GIT_REPOSITORY_STATE_REBASE, GIT_REPOSITORY_STATE_REBASE_INTERACTIVE, GIT_REPOSITORY_STATE_REBASE_MERGE, GIT_REPOSITORY_STATE_APPLY_MAILBOX, GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE, } git_repository_state_t; /** * Determines the status of a git repository - ie, whether an operation * (merge, cherry-pick, etc) is in progress. * * @param repo Repository pointer * @return The state of the repository */ GIT_EXTERN(int) git_repository_state(git_repository *repo); /** * Sets the active namespace for this Git Repository * * This namespace affects all reference operations for the repo. * See `man gitnamespaces` * * @param repo The repo * @param nmspace The namespace. This should not include the refs * folder, e.g. to namespace all references under `refs/namespaces/foo/`, * use `foo` as the namespace. * @return 0 on success, -1 on error */ GIT_EXTERN(int) git_repository_set_namespace(git_repository *repo, const char *nmspace); /** * Get the currently active namespace for this repository * * @param repo The repo * @return the active namespace, or NULL if there isn't one */ GIT_EXTERN(const char *) git_repository_get_namespace(git_repository *repo); /** * Determine if the repository was a shallow clone * * @param repo The repository * @return 1 if shallow, zero if not */ GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo); /** * Retrieve the configured identity to use for reflogs * * The memory is owned by the repository and must not be freed by the * user. * * @param name where to store the pointer to the name * @param email where to store the pointer to the email * @param repo the repository */ GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo); /** * Set the identity to be used for writing reflogs * * If both are set, this name and email will be used to write to the * reflog. Pass NULL to unset. When unset, the identity will be taken * from the repository's configuration. * * @param repo the repository to configure * @param name the name to use for the reflog entries * @param email the email to use for the reflog entries */ GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email); /** @} */ GIT_END_DECL #endif