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
);
40 * Create a "fake" repository to wrap an object database
42 * Create a repository object to wrap an object database to be used
43 * with the API when all you have is an object database. This doesn't
44 * have any paths associated with it, so use with care.
46 * @param out pointer to the repo
47 * @param odb the object database to wrap
48 * @return 0 or an error code
50 GIT_EXTERN(int) git_repository_wrap_odb(git_repository
**out
, git_odb
*odb
);
53 * Look for a git repository and copy its path in the given buffer.
54 * The lookup start from base_path and walk across parent directories
55 * if nothing has been found. The lookup ends when the first repository
56 * is found, or when reaching a directory referenced in ceiling_dirs
57 * or when the filesystem changes (in case across_fs is true).
59 * The method will automatically detect if the repository is bare
60 * (if there is a repository).
62 * @param out A pointer to a user-allocated git_buf which will contain
65 * @param start_path The base path where the lookup starts.
67 * @param across_fs If true, then the lookup will not stop when a
68 * filesystem device change is detected while exploring parent directories.
70 * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR separated list of
71 * absolute symbolic link free paths. The lookup will stop when any
72 * of this paths is reached. Note that the lookup always performs on
73 * start_path no matter start_path appears in ceiling_dirs ceiling_dirs
74 * might be NULL (which is equivalent to an empty string)
76 * @return 0 or an error code
78 GIT_EXTERN(int) git_repository_discover(
80 const char *start_path
,
82 const char *ceiling_dirs
);
85 * Option flags for `git_repository_open_ext`.
87 * * GIT_REPOSITORY_OPEN_NO_SEARCH - Only open the repository if it can be
88 * immediately found in the start_path. Do not walk up from the
89 * start_path looking at parent directories.
90 * * GIT_REPOSITORY_OPEN_CROSS_FS - Unless this flag is set, open will not
91 * continue searching across filesystem boundaries (i.e. when `st_dev`
92 * changes from the `stat` system call). (E.g. Searching in a user's home
93 * directory "/home/user/source/" will not return "/.git/" as the found
94 * repo if "/" is a different filesystem than "/home".)
95 * * GIT_REPOSITORY_OPEN_BARE - Open repository as a bare repo regardless
96 * of core.bare config, and defer loading config file for faster setup.
97 * Unlike `git_repository_open_bare`, this can follow gitlinks.
100 GIT_REPOSITORY_OPEN_NO_SEARCH
= (1 << 0),
101 GIT_REPOSITORY_OPEN_CROSS_FS
= (1 << 1),
102 GIT_REPOSITORY_OPEN_BARE
= (1 << 2),
103 } git_repository_open_flag_t
;
106 * Find and open a repository with extended controls.
108 * @param out Pointer to the repo which will be opened. This can
109 * actually be NULL if you only want to use the error code to
110 * see if a repo at this path could be opened.
111 * @param path Path to open as git repository. If the flags
112 * permit "searching", then this can be a path to a subdirectory
113 * inside the working directory of the repository.
114 * @param flags A combination of the GIT_REPOSITORY_OPEN flags above.
115 * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR delimited list of path
116 * prefixes at which the search for a containing repository should
118 * @return 0 on success, GIT_ENOTFOUND if no repository could be found,
119 * or -1 if there was a repository but open failed for some reason
120 * (such as repo corruption or system errors).
122 GIT_EXTERN(int) git_repository_open_ext(
123 git_repository
**out
,
126 const char *ceiling_dirs
);
129 * Open a bare repository on the serverside.
131 * This is a fast open for bare repositories that will come in handy
132 * if you're e.g. hosting git repositories and need to access them
135 * @param out Pointer to the repo which will be opened.
136 * @param bare_path Direct path to the bare repository
137 * @return 0 on success, or an error code
139 GIT_EXTERN(int) git_repository_open_bare(git_repository
**out
, const char *bare_path
);
142 * Free a previously allocated repository
144 * Note that after a repository is free'd, all the objects it has spawned
145 * will still exist until they are manually closed by the user
146 * with `git_object_free`, but accessing any of the attributes of
147 * an object without a backing repository will result in undefined
150 * @param repo repository handle to close. If NULL nothing occurs.
152 GIT_EXTERN(void) git_repository_free(git_repository
*repo
);
155 * Creates a new Git repository in the given folder.
158 * - Reinit the repository
160 * @param out pointer to the repo which will be created or reinitialized
161 * @param path the path to the repository
162 * @param is_bare if true, a Git repository without a working directory is
163 * created at the pointed path. If false, provided path will be
164 * considered as the working directory into which the .git directory
167 * @return 0 or an error code
169 GIT_EXTERN(int) git_repository_init(
170 git_repository
**out
,
175 * Option flags for `git_repository_init_ext`.
177 * These flags configure extra behaviors to `git_repository_init_ext`.
178 * In every case, the default behavior is the zero value (i.e. flag is
179 * not set). Just OR the flag values together for the `flags` parameter
180 * when initializing a new repo. Details of individual values are:
182 * * BARE - Create a bare repository with no working directory.
183 * * NO_REINIT - Return an GIT_EEXISTS error if the repo_path appears to
184 * already be an git repository.
185 * * NO_DOTGIT_DIR - Normally a "/.git/" will be appended to the repo
186 * path for non-bare repos (if it is not already there), but
187 * passing this flag prevents that behavior.
188 * * MKDIR - Make the repo_path (and workdir_path) as needed. Init is
189 * always willing to create the ".git" directory even without this
190 * flag. This flag tells init to create the trailing component of
191 * the repo and workdir paths as needed.
192 * * MKPATH - Recursively make all components of the repo and workdir
193 * paths as necessary.
194 * * EXTERNAL_TEMPLATE - libgit2 normally uses internal templates to
195 * initialize a new repo. This flags enables external templates,
196 * looking the "template_path" from the options if set, or the
197 * `init.templatedir` global config if not, or falling back on
198 * "/usr/share/git-core/templates" if it exists.
199 * * GIT_REPOSITORY_INIT_RELATIVE_GITLINK - If an alternate workdir is
200 * specified, use relative paths for the gitdir and core.worktree.
203 GIT_REPOSITORY_INIT_BARE
= (1u << 0),
204 GIT_REPOSITORY_INIT_NO_REINIT
= (1u << 1),
205 GIT_REPOSITORY_INIT_NO_DOTGIT_DIR
= (1u << 2),
206 GIT_REPOSITORY_INIT_MKDIR
= (1u << 3),
207 GIT_REPOSITORY_INIT_MKPATH
= (1u << 4),
208 GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE
= (1u << 5),
209 GIT_REPOSITORY_INIT_RELATIVE_GITLINK
= (1u << 6),
210 } git_repository_init_flag_t
;
213 * Mode options for `git_repository_init_ext`.
215 * Set the mode field of the `git_repository_init_options` structure
216 * either to the custom mode that you would like, or to one of the
219 * * SHARED_UMASK - Use permissions configured by umask - the default.
220 * * SHARED_GROUP - Use "--shared=group" behavior, chmod'ing the new repo
221 * to be group writable and "g+sx" for sticky group assignment.
222 * * SHARED_ALL - Use "--shared=all" behavior, adding world readability.
223 * * Anything else - Set to custom value.
226 GIT_REPOSITORY_INIT_SHARED_UMASK
= 0,
227 GIT_REPOSITORY_INIT_SHARED_GROUP
= 0002775,
228 GIT_REPOSITORY_INIT_SHARED_ALL
= 0002777,
229 } git_repository_init_mode_t
;
232 * Extended options structure for `git_repository_init_ext`.
234 * This contains extra options for `git_repository_init_ext` that enable
235 * additional initialization features. The fields are:
237 * * flags - Combination of GIT_REPOSITORY_INIT flags above.
238 * * mode - Set to one of the standard GIT_REPOSITORY_INIT_SHARED_...
239 * constants above, or to a custom value that you would like.
240 * * workdir_path - The path to the working dir or NULL for default (i.e.
241 * repo_path parent on non-bare repos). IF THIS IS RELATIVE PATH,
242 * IT WILL BE EVALUATED RELATIVE TO THE REPO_PATH. If this is not
243 * the "natural" working directory, a .git gitlink file will be
244 * created here linking to the repo_path.
245 * * description - If set, this will be used to initialize the "description"
246 * file in the repository, instead of using the template content.
247 * * template_path - When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set,
248 * this contains the path to use for the template directory. If
249 * this is NULL, the config or default directory options will be
251 * * initial_head - The name of the head to point HEAD at. If NULL, then
252 * this will be treated as "master" and the HEAD ref will be set
253 * to "refs/heads/master". If this begins with "refs/" it will be
254 * used verbatim; otherwise "refs/heads/" will be prefixed.
255 * * origin_url - If this is non-NULL, then after the rest of the
256 * repository initialization is completed, an "origin" remote
257 * will be added pointing to this URL.
260 unsigned int version
;
263 const char *workdir_path
;
264 const char *description
;
265 const char *template_path
;
266 const char *initial_head
;
267 const char *origin_url
;
268 } git_repository_init_options
;
270 #define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1
271 #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION}
274 * Initializes a `git_repository_init_options` with default values. Equivalent
275 * to creating an instance with GIT_REPOSITORY_INIT_OPTIONS_INIT.
277 * @param opts the `git_repository_init_options` struct to initialize
278 * @param version Version of struct; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`
279 * @return Zero on success; -1 on failure.
281 GIT_EXTERN(int) git_repository_init_init_options(
282 git_repository_init_options
*opts
,
283 unsigned int version
);
286 * Create a new Git repository in the given folder with extended controls.
288 * This will initialize a new git repository (creating the repo_path
289 * if requested by flags) and working directory as needed. It will
290 * auto-detect the case sensitivity of the file system and if the
291 * file system supports file mode bits correctly.
293 * @param out Pointer to the repo which will be created or reinitialized.
294 * @param repo_path The path to the repository.
295 * @param opts Pointer to git_repository_init_options struct.
296 * @return 0 or an error code on failure.
298 GIT_EXTERN(int) git_repository_init_ext(
299 git_repository
**out
,
300 const char *repo_path
,
301 git_repository_init_options
*opts
);
304 * Retrieve and resolve the reference pointed at by HEAD.
306 * The returned `git_reference` will be owned by caller and
307 * `git_reference_free()` must be called when done with it to release the
308 * allocated memory and prevent a leak.
310 * @param out pointer to the reference which will be retrieved
311 * @param repo a repository object
313 * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
314 * branch, GIT_ENOTFOUND when HEAD is missing; an error code otherwise
316 GIT_EXTERN(int) git_repository_head(git_reference
**out
, git_repository
*repo
);
319 * Check if a repository's HEAD is detached
321 * A repository's HEAD is detached when it points directly to a commit
322 * instead of a branch.
324 * @param repo Repo to test
325 * @return 1 if HEAD is detached, 0 if it's not; error code if there
328 GIT_EXTERN(int) git_repository_head_detached(git_repository
*repo
);
331 * Check if the current branch is unborn
333 * An unborn branch is one named from HEAD but which doesn't exist in
334 * the refs namespace, because it doesn't have any commit to point to.
336 * @param repo Repo to test
337 * @return 1 if the current branch is unborn, 0 if it's not; error
338 * code if there was an error
340 GIT_EXTERN(int) git_repository_head_unborn(git_repository
*repo
);
343 * Check if a repository is empty
345 * An empty repository has just been initialized and contains no references
346 * apart from HEAD, which must be pointing to the unborn master branch.
348 * @param repo Repo to test
349 * @return 1 if the repository is empty, 0 if it isn't, error code
350 * if the repository is corrupted
352 GIT_EXTERN(int) git_repository_is_empty(git_repository
*repo
);
355 * Get the path of this repository
357 * This is the path of the `.git` folder for normal repositories,
358 * or of the repository itself for bare repositories.
360 * @param repo A repository object
361 * @return the path to the repository
363 GIT_EXTERN(const char *) git_repository_path(git_repository
*repo
);
366 * Get the path of the working directory for this repository
368 * If the repository is bare, this function will always return
371 * @param repo A repository object
372 * @return the path to the working dir, if it exists
374 GIT_EXTERN(const char *) git_repository_workdir(git_repository
*repo
);
377 * Set the path to the working directory for this repository
379 * The working directory doesn't need to be the same one
380 * that contains the `.git` folder for this repository.
382 * If this repository is bare, setting its working directory
383 * will turn it into a normal repository, capable of performing
384 * all the common workdir operations (checkout, status, index
385 * manipulation, etc).
387 * @param repo A repository object
388 * @param workdir The path to a working directory
389 * @param update_gitlink Create/update gitlink in workdir and set config
390 * "core.worktree" (if workdir is not the parent of the .git directory)
391 * @return 0, or an error code
393 GIT_EXTERN(int) git_repository_set_workdir(
394 git_repository
*repo
, const char *workdir
, int update_gitlink
);
397 * Check if a repository is bare
399 * @param repo Repo to test
400 * @return 1 if the repository is bare, 0 otherwise.
402 GIT_EXTERN(int) git_repository_is_bare(git_repository
*repo
);
405 * Get the configuration file for this repository.
407 * If a configuration file has not been set, the default
408 * config set for the repository will be returned, including
409 * global and system configurations (if they are available).
411 * The configuration file must be freed once it's no longer
412 * being used by the user.
414 * @param out Pointer to store the loaded configuration
415 * @param repo A repository object
416 * @return 0, or an error code
418 GIT_EXTERN(int) git_repository_config(git_config
**out
, git_repository
*repo
);
421 * Get a snapshot of the repository's configuration
423 * Convenience function to take a snapshot from the repository's
424 * configuration. The contents of this snapshot will not change,
425 * even if the underlying config files are modified.
427 * The configuration file must be freed once it's no longer
428 * being used by the user.
430 * @param out Pointer to store the loaded configuration
431 * @param repo the repository
432 * @return 0, or an error code
434 GIT_EXTERN(int) git_repository_config_snapshot(git_config
**out
, git_repository
*repo
);
437 * Get the Object Database for this repository.
439 * If a custom ODB has not been set, the default
440 * database for the repository will be returned (the one
441 * located in `.git/objects`).
443 * The ODB must be freed once it's no longer being used by
446 * @param out Pointer to store the loaded ODB
447 * @param repo A repository object
448 * @return 0, or an error code
450 GIT_EXTERN(int) git_repository_odb(git_odb
**out
, git_repository
*repo
);
453 * Get the Reference Database Backend for this repository.
455 * If a custom refsdb has not been set, the default database for
456 * the repository will be returned (the one that manipulates loose
457 * and packed references in the `.git` directory).
459 * The refdb must be freed once it's no longer being used by
462 * @param out Pointer to store the loaded refdb
463 * @param repo A repository object
464 * @return 0, or an error code
466 GIT_EXTERN(int) git_repository_refdb(git_refdb
**out
, git_repository
*repo
);
469 * Get the Index file for this repository.
471 * If a custom index has not been set, the default
472 * index for the repository will be returned (the one
473 * located in `.git/index`).
475 * The index must be freed once it's no longer being used by
478 * @param out Pointer to store the loaded index
479 * @param repo A repository object
480 * @return 0, or an error code
482 GIT_EXTERN(int) git_repository_index(git_index
**out
, git_repository
*repo
);
485 * Retrieve git's prepared message
487 * Operations such as git revert/cherry-pick/merge with the -n option
488 * stop just short of creating a commit with the changes and save
489 * their prepared message in .git/MERGE_MSG so the next git-commit
490 * execution can present it to the user for them to amend if they
493 * Use this function to get the contents of this file. Don't forget to
494 * remove the file after you create the commit.
496 * @param out git_buf to write data into
497 * @param repo Repository to read prepared message from
498 * @return 0, GIT_ENOTFOUND if no message exists or an error code
500 GIT_EXTERN(int) git_repository_message(git_buf
*out
, git_repository
*repo
);
503 * Remove git's prepared message.
505 * Remove the message that `git_repository_message` retrieves.
507 GIT_EXTERN(int) git_repository_message_remove(git_repository
*repo
);
510 * Remove all the metadata associated with an ongoing command like merge,
511 * revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc.
513 * @param repo A repository object
514 * @return 0 on success, or error
516 GIT_EXTERN(int) git_repository_state_cleanup(git_repository
*repo
);
518 typedef int (*git_repository_fetchhead_foreach_cb
)(const char *ref_name
,
519 const char *remote_url
,
521 unsigned int is_merge
,
525 * Invoke 'callback' for each entry in the given FETCH_HEAD file.
527 * Return a non-zero value from the callback to stop the loop.
529 * @param repo A repository object
530 * @param callback Callback function
531 * @param payload Pointer to callback data (optional)
532 * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if
533 * there is no FETCH_HEAD file, or other error code.
535 GIT_EXTERN(int) git_repository_fetchhead_foreach(
536 git_repository
*repo
,
537 git_repository_fetchhead_foreach_cb callback
,
540 typedef int (*git_repository_mergehead_foreach_cb
)(const git_oid
*oid
,
544 * If a merge is in progress, invoke 'callback' for each commit ID in the
547 * Return a non-zero value from the callback to stop the loop.
549 * @param repo A repository object
550 * @param callback Callback function
551 * @param payload Pointer to callback data (optional)
552 * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if
553 * there is no MERGE_HEAD file, or other error code.
555 GIT_EXTERN(int) git_repository_mergehead_foreach(
556 git_repository
*repo
,
557 git_repository_mergehead_foreach_cb callback
,
561 * Calculate hash of file using repository filtering rules.
563 * If you simply want to calculate the hash of a file on disk with no filters,
564 * you can just use the `git_odb_hashfile()` API. However, if you want to
565 * hash a file in the repository and you want to apply filtering rules (e.g.
566 * crlf filters) before generating the SHA, then use this function.
568 * Note: if the repository has `core.safecrlf` set to fail and the
569 * filtering triggers that failure, then this function will return an
570 * error and not calculate the hash of the file.
572 * @param out Output value of calculated SHA
573 * @param repo Repository pointer
574 * @param path Path to file on disk whose contents should be hashed. If the
575 * repository is not NULL, this can be a relative path.
576 * @param type The object type to hash as (e.g. GIT_OBJ_BLOB)
577 * @param as_path The path to use to look up filtering rules. If this is
578 * NULL, then the `path` parameter will be used instead. If
579 * this is passed as the empty string, then no filters will be
580 * applied when calculating the hash.
581 * @return 0 on success, or an error code
583 GIT_EXTERN(int) git_repository_hashfile(
585 git_repository
*repo
,
588 const char *as_path
);
591 * Make the repository HEAD point to the specified reference.
593 * If the provided reference points to a Tree or a Blob, the HEAD is
594 * unaltered and -1 is returned.
596 * If the provided reference points to a branch, the HEAD will point
597 * to that branch, staying attached, or become attached if it isn't yet.
598 * If the branch doesn't exist yet, no error will be return. The HEAD
599 * will then be attached to an unborn branch.
601 * Otherwise, the HEAD will be detached and will directly point to
604 * @param repo Repository pointer
605 * @param refname Canonical name of the reference the HEAD should point at
606 * @param signature The identity that will used to populate the reflog entry
607 * @param log_message The one line long message to be appended to the reflog
608 * @return 0 on success, or an error code
610 GIT_EXTERN(int) git_repository_set_head(
611 git_repository
* repo
,
613 const git_signature
*signature
,
614 const char *log_message
);
617 * Make the repository HEAD directly point to the Commit.
619 * If the provided committish cannot be found in the repository, the HEAD
620 * is unaltered and GIT_ENOTFOUND is returned.
622 * If the provided commitish cannot be peeled into a commit, the HEAD
623 * is unaltered and -1 is returned.
625 * Otherwise, the HEAD will eventually be detached and will directly point to
628 * @param repo Repository pointer
629 * @param commitish Object id of the Commit the HEAD should point to
630 * @param signature The identity that will used to populate the reflog entry
631 * @param log_message The one line long message to be appended to the reflog
632 * @return 0 on success, or an error code
634 GIT_EXTERN(int) git_repository_set_head_detached(
635 git_repository
* repo
,
636 const git_oid
* commitish
,
637 const git_signature
*signature
,
638 const char *log_message
);
643 * If the HEAD is already detached and points to a Commit, 0 is returned.
645 * If the HEAD is already detached and points to a Tag, the HEAD is
646 * updated into making it point to the peeled Commit, and 0 is returned.
648 * If the HEAD is already detached and points to a non commitish, the HEAD is
649 * unaltered, and -1 is returned.
651 * Otherwise, the HEAD will be detached and point to the peeled Commit.
653 * @param repo Repository pointer
654 * @param signature The identity that will used to populate the reflog entry
655 * @param reflog_message The one line long message to be appended to the reflog
656 * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
657 * branch or an error code
659 GIT_EXTERN(int) git_repository_detach_head(
660 git_repository
* repo
,
661 const git_signature
*signature
,
662 const char *reflog_message
);
667 * These values represent possible states for the repository to be in,
668 * based on the current operation which is ongoing.
671 GIT_REPOSITORY_STATE_NONE
,
672 GIT_REPOSITORY_STATE_MERGE
,
673 GIT_REPOSITORY_STATE_REVERT
,
674 GIT_REPOSITORY_STATE_CHERRYPICK
,
675 GIT_REPOSITORY_STATE_BISECT
,
676 GIT_REPOSITORY_STATE_REBASE
,
677 GIT_REPOSITORY_STATE_REBASE_INTERACTIVE
,
678 GIT_REPOSITORY_STATE_REBASE_MERGE
,
679 GIT_REPOSITORY_STATE_APPLY_MAILBOX
,
680 GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE
,
681 } git_repository_state_t
;
684 * Determines the status of a git repository - ie, whether an operation
685 * (merge, cherry-pick, etc) is in progress.
687 * @param repo Repository pointer
688 * @return The state of the repository
690 GIT_EXTERN(int) git_repository_state(git_repository
*repo
);
693 * Sets the active namespace for this Git Repository
695 * This namespace affects all reference operations for the repo.
696 * See `man gitnamespaces`
698 * @param repo The repo
699 * @param nmspace The namespace. This should not include the refs
700 * folder, e.g. to namespace all references under `refs/namespaces/foo/`,
701 * use `foo` as the namespace.
702 * @return 0 on success, -1 on error
704 GIT_EXTERN(int) git_repository_set_namespace(git_repository
*repo
, const char *nmspace
);
707 * Get the currently active namespace for this repository
709 * @param repo The repo
710 * @return the active namespace, or NULL if there isn't one
712 GIT_EXTERN(const char *) git_repository_get_namespace(git_repository
*repo
);
716 * Determine if the repository was a shallow clone
718 * @param repo The repository
719 * @return 1 if shallow, zero if not
721 GIT_EXTERN(int) git_repository_is_shallow(git_repository
*repo
);