* @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
/**
* 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 {
+ /**
+ * 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_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
+ * directory.
+ */
+ 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;
/**
* 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.
+ * 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
*
* 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.
+ * not set). Just OR the flag values together for the `flags` parameter
+ * when initializing a new repo.
*/
typedef enum {
+ /**
+ * Create a bare repository with no working directory.
+ */
GIT_REPOSITORY_INIT_BARE = (1u << 0),
+
+ /**
+ * Return an GIT_EEXISTS error if the repo_path appears to already be
+ * an git repository.
+ */
GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1),
+
+ /**
+ * 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.
+ */
GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2),
+
+ /**
+ * 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.
+ */
GIT_REPOSITORY_INIT_MKDIR = (1u << 3),
+
+ /**
+ * Recursively make all components of the repo and workdir paths as
+ * necessary.
+ */
GIT_REPOSITORY_INIT_MKPATH = (1u << 4),
+
+ /**
+ * 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_EXTERNAL_TEMPLATE = (1u << 5),
- GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6),
+
+ /**
+ * If an alternate workdir is specified, use relative paths for the gitdir
+ * and core.worktree.
+ */
+ GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6)
} git_repository_init_flag_t;
/**
*
* 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.
+ * defined modes.
*/
typedef enum {
+ /**
+ * Use permissions configured by umask - the default.
+ */
GIT_REPOSITORY_INIT_SHARED_UMASK = 0,
+
+ /**
+ * Use "--shared=group" behavior, chmod'ing the new repo to be group
+ * writable and "g+sx" for sticky group assignment.
+ */
GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775,
- GIT_REPOSITORY_INIT_SHARED_ALL = 0002777,
+
+ /**
+ * Use "--shared=all" behavior, adding world readability.
+ */
+ 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.
+ * additional initialization features.
*/
typedef struct {
unsigned int version;
+
+ /**
+ * Combination of GIT_REPOSITORY_INIT flags above.
+ */
uint32_t flags;
+
+ /**
+ * Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... constants
+ * above, or to a custom value that you would like.
+ */
uint32_t mode;
+
+ /**
+ * 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.
+ */
const char *workdir_path;
+
+ /**
+ * If set, this will be used to initialize the "description" file in the
+ * repository, instead of using the template content.
+ */
const char *description;
+
+ /**
+ * 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.
+ */
const char *template_path;
+
+ /**
+ * 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.
+ */
const char *initial_head;
+
+ /**
+ * 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 *origin_url;
} git_repository_init_options;
#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.
+ * 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 Version of struct; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`
+ * @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_init_options(
+GIT_EXTERN(int) git_repository_init_options_init(
git_repository_init_options *opts,
unsigned int version);
*/
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,
+ const char *name);
+
/**
* Check if a repository's HEAD is detached
*
*/
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
+ * there was an error
+ */
+GIT_EXTERN(int) git_repository_head_detached_for_worktree(git_repository *repo,
+ const char *name);
+
/**
* Check if the current branch is unborn
*
*/
GIT_EXTERN(int) git_repository_is_empty(git_repository *repo);
+/**
+ * List of items which belong to the git repository layout
+ */
+typedef enum {
+ 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
+} git_repository_item_t;
+
+/**
+ * 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
*
* @param repo A repository object
* @return the path to the repository
*/
-GIT_EXTERN(const char *) git_repository_path(git_repository *repo);
+GIT_EXTERN(const char *) git_repository_path(const git_repository *repo);
/**
* Get the path of the working directory for this repository
* @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);
+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
* @param repo Repo to test
* @return 1 if the repository is bare, 0 otherwise.
*/
-GIT_EXTERN(int) git_repository_is_bare(git_repository *repo);
+GIT_EXTERN(int) git_repository_is_bare(const git_repository *repo);
+
+/**
+ * Check if a repository is a linked work tree
+ *
+ * @param repo Repo to test
+ * @return 1 if the repository is a linked work tree, 0 otherwise.
+ */
+GIT_EXTERN(int) git_repository_is_worktree(const git_repository *repo);
/**
* Get the configuration file for this repository.
* Remove git's prepared message.
*
* Remove the message that `git_repository_message` retrieves.
+ *
+ * @param repo Repository to remove prepared message from.
+ * @return 0 or an error code.
*/
GIT_EXTERN(int) git_repository_message_remove(git_repository *repo);
*/
GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo);
-typedef int (*git_repository_fetchhead_foreach_cb)(const char *ref_name,
+/**
+ * Callback used to iterate over each FETCH_HEAD entry
+ *
+ * @see git_repository_fetchhead_foreach
+ *
+ * @param ref_name The reference name
+ * @param remote_url The remote URL
+ * @param oid The reference target OID
+ * @param is_merge Was the reference the result of a merge
+ * @param payload Payload passed to git_repository_fetchhead_foreach
+ * @return non-zero to terminate the iteration
+ */
+typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb)(const char *ref_name,
const char *remote_url,
const git_oid *oid,
unsigned int is_merge,
git_repository_fetchhead_foreach_cb callback,
void *payload);
-typedef int (*git_repository_mergehead_foreach_cb)(const git_oid *oid,
+/**
+ * Callback used to iterate over each MERGE_HEAD entry
+ *
+ * @see git_repository_mergehead_foreach
+ *
+ * @param oid The merge OID
+ * @param payload Payload passed to git_repository_mergehead_foreach
+ * @return non-zero to terminate the iteration
+ */
+typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb)(const git_oid *oid,
void *payload);
/**
*
* @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 path Path to file on disk whose contents should be hashed. This
+ * may be an absolute path or a relative path, in which case it
+ * will be treated as a path within the working directory.
+ * @param type The object type to hash as (e.g. GIT_OBJECT_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.
+ * an empty string then no filters will be applied when
+ * calculating the hash. If this is `NULL` and the `path`
+ * parameter is a file within the repository's working
+ * directory, then the `path` will be used.
* @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,
+ git_object_t type,
const char *as_path);
/**
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_repository_set_head(
- git_repository* repo,
- const char* refname);
+ 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
+ * If the provided committish 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
+ * @param committish 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);
+ git_repository *repo,
+ const git_oid *committish);
/**
* Make the repository HEAD directly point to the Commit.
*/
GIT_EXTERN(int) git_repository_set_head_detached_from_annotated(
git_repository *repo,
- const git_annotated_commit *commitish);
+ const git_annotated_commit *committish);
/**
* Detach the HEAD.
* 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
+ * If the HEAD is already detached and points to a non committish, the HEAD is
* unaltered, and -1 is returned.
*
* Otherwise, the HEAD will be detached and point to the peeled Commit.
* branch or an error code
*/
GIT_EXTERN(int) git_repository_detach_head(
- git_repository* repo);
+ git_repository *repo);
/**
* Repository state
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_APPLY_MAILBOX_OR_REBASE
} git_repository_state_t;
/**
* @param name where to store the pointer to the name
* @param email where to store the pointer to the email
* @param repo the repository
+ * @return 0 or an error code
*/
GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo);
* @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
+ * @return 0 or an error code.
*/
GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email);
projects / libgit2.git / blobdiff