2 * Copyright (C) 2009-2012 the libgit2 contributors
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__
15 * @file git2/repository.h
16 * @brief Git repository management routines
17 * @defgroup git_repository Git repository management routines
24 * Open a git repository.
26 * The 'path' argument must point to either a git repository
27 * folder, or an existing work dir.
29 * The method will automatically detect if 'path' is a normal
30 * or bare repository or fail is 'path' is neither.
32 * @param repository pointer to the repo which will be opened
33 * @param path the path to the repository
34 * @return 0 or an error code
36 GIT_EXTERN(int) git_repository_open(git_repository
**repository
, const char *path
);
39 * Create a "fake" repository to wrap an object database
41 * Create a repository object to wrap an object database to be used
42 * with the API when all you have is an object database. This doesn't
43 * have any paths associated with it, so use with care.
45 * @param repository pointer to the repo
46 * @param odb the object database to wrap
47 * @return 0 or an error code
49 GIT_EXTERN(int) git_repository_wrap_odb(git_repository
**repository
, git_odb
*odb
);
52 * Look for a git repository and copy its path in the given buffer.
53 * The lookup start from base_path and walk across parent directories
54 * if nothing has been found. The lookup ends when the first repository
55 * is found, or when reaching a directory referenced in ceiling_dirs
56 * or when the filesystem changes (in case across_fs is true).
58 * The method will automatically detect if the repository is bare
59 * (if there is a repository).
61 * @param repository_path The user allocated buffer which will
62 * contain the found path.
64 * @param size repository_path size
66 * @param start_path The base path where the lookup starts.
68 * @param across_fs If true, then the lookup will not stop when a
69 * filesystem device change is detected while exploring parent directories.
71 * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR separated list of
72 * absolute symbolic link free paths. The lookup will stop when any
73 * of this paths is reached. Note that the lookup always performs on
74 * start_path no matter start_path appears in ceiling_dirs ceiling_dirs
75 * might be NULL (which is equivalent to an empty string)
77 * @return 0 or an error code
79 GIT_EXTERN(int) git_repository_discover(
80 char *repository_path
,
82 const char *start_path
,
84 const char *ceiling_dirs
);
87 * Option flags for `git_repository_open_ext`.
89 * * GIT_REPOSITORY_OPEN_NO_SEARCH - Only open the repository if it can be
90 * immediately found in the start_path. Do not walk up from the
91 * start_path looking at parent directories.
92 * * GIT_REPOSITORY_OPEN_CROSS_FS - Unless this flag is set, open will not
93 * continue searching across filesystem boundaries (i.e. when `st_dev`
94 * changes from the `stat` system call). (E.g. Searching in a user's home
95 * directory "/home/user/source/" will not return "/.git/" as the found
96 * repo if "/" is a different filesystem than "/home".)
99 GIT_REPOSITORY_OPEN_NO_SEARCH
= (1 << 0),
100 GIT_REPOSITORY_OPEN_CROSS_FS
= (1 << 1),
104 * Find and open a repository with extended controls.
106 * @param repo_out Pointer to the repo which will be opened. This can
107 * actually be NULL if you only want to use the error code to
108 * see if a repo at this path could be opened.
109 * @param start_path Path to open as git repository. If the flags
110 * permit "searching", then this can be a path to a subdirectory
111 * inside the working directory of the repository.
112 * @param flags A combination of the GIT_REPOSITORY_OPEN flags above.
113 * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR delimited list of path
114 * prefixes at which the search for a containing repository should
116 * @return 0 on success, GIT_ENOTFOUND if no repository could be found,
117 * or -1 if there was a repository but open failed for some reason
118 * (such as repo corruption or system errors).
120 GIT_EXTERN(int) git_repository_open_ext(
121 git_repository
**repo
,
122 const char *start_path
,
124 const char *ceiling_dirs
);
127 * Free a previously allocated repository
129 * Note that after a repository is free'd, all the objects it has spawned
130 * will still exist until they are manually closed by the user
131 * with `git_object_free`, but accessing any of the attributes of
132 * an object without a backing repository will result in undefined
135 * @param repo repository handle to close. If NULL nothing occurs.
137 GIT_EXTERN(void) git_repository_free(git_repository
*repo
);
140 * Creates a new Git repository in the given folder.
143 * - Reinit the repository
145 * @param repo_out pointer to the repo which will be created or reinitialized
146 * @param path the path to the repository
147 * @param is_bare if true, a Git repository without a working directory is
148 * created at the pointed path. If false, provided path will be
149 * considered as the working directory into which the .git directory
152 * @return 0 or an error code
154 GIT_EXTERN(int) git_repository_init(
155 git_repository
**repo_out
,
160 * Option flags for `git_repository_init_ext`.
162 * These flags configure extra behaviors to `git_repository_init_ext`.
163 * In every case, the default behavior is the zero value (i.e. flag is
164 * not set). Just OR the flag values together for the `flags` parameter
165 * when initializing a new repo. Details of individual values are:
167 * * BARE - Create a bare repository with no working directory.
168 * * NO_REINIT - Return an EEXISTS error if the repo_path appears to
169 * already be an git repository.
170 * * NO_DOTGIT_DIR - Normally a "/.git/" will be appended to the repo
171 * path for non-bare repos (if it is not already there), but
172 * passing this flag prevents that behavior.
173 * * MKDIR - Make the repo_path (and workdir_path) as needed. Init is
174 * always willing to create the ".git" directory even without this
175 * flag. This flag tells init to create the trailing component of
176 * the repo and workdir paths as needed.
177 * * MKPATH - Recursively make all components of the repo and workdir
178 * paths as necessary.
179 * * EXTERNAL_TEMPLATE - libgit2 normally uses internal templates to
180 * initialize a new repo. This flags enables external templates,
181 * looking the "template_path" from the options if set, or the
182 * `init.templatedir` global config if not, or falling back on
183 * "/usr/share/git-core/templates" if it exists.
186 GIT_REPOSITORY_INIT_BARE
= (1u << 0),
187 GIT_REPOSITORY_INIT_NO_REINIT
= (1u << 1),
188 GIT_REPOSITORY_INIT_NO_DOTGIT_DIR
= (1u << 2),
189 GIT_REPOSITORY_INIT_MKDIR
= (1u << 3),
190 GIT_REPOSITORY_INIT_MKPATH
= (1u << 4),
191 GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE
= (1u << 5),
195 * Mode options for `git_repository_init_ext`.
197 * Set the mode field of the `git_repository_init_options` structure
198 * either to the custom mode that you would like, or to one of the
201 * * SHARED_UMASK - Use permissions configured by umask - the default.
202 * * SHARED_GROUP - Use "--shared=group" behavior, chmod'ing the new repo
203 * to be group writable and "g+sx" for sticky group assignment.
204 * * SHARED_ALL - Use "--shared=all" behavior, adding world readability.
205 * * Anything else - Set to custom value.
208 GIT_REPOSITORY_INIT_SHARED_UMASK
= 0,
209 GIT_REPOSITORY_INIT_SHARED_GROUP
= 0002775,
210 GIT_REPOSITORY_INIT_SHARED_ALL
= 0002777,
214 * Extended options structure for `git_repository_init_ext`.
216 * This contains extra options for `git_repository_init_ext` that enable
217 * additional initialization features. The fields are:
219 * * flags - Combination of GIT_REPOSITORY_INIT flags above.
220 * * mode - Set to one of the standard GIT_REPOSITORY_INIT_SHARED_...
221 * constants above, or to a custom value that you would like.
222 * * workdir_path - The path to the working dir or NULL for default (i.e.
223 * repo_path parent on non-bare repos). IF THIS IS RELATIVE PATH,
224 * IT WILL BE EVALUATED RELATIVE TO THE REPO_PATH. If this is not
225 * the "natural" working directory, a .git gitlink file will be
226 * created here linking to the repo_path.
227 * * description - If set, this will be used to initialize the "description"
228 * file in the repository, instead of using the template content.
229 * * template_path - When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set,
230 * this contains the path to use for the template directory. If
231 * this is NULL, the config or default directory options will be
233 * * initial_head - The name of the head to point HEAD at. If NULL, then
234 * this will be treated as "master" and the HEAD ref will be set
235 * to "refs/heads/master". If this begins with "refs/" it will be
236 * used verbatim; otherwise "refs/heads/" will be prefixed.
237 * * origin_url - If this is non-NULL, then after the rest of the
238 * repository initialization is completed, an "origin" remote
239 * will be added pointing to this URL.
244 const char *workdir_path
;
245 const char *description
;
246 const char *template_path
;
247 const char *initial_head
;
248 const char *origin_url
;
249 } git_repository_init_options
;
252 * Create a new Git repository in the given folder with extended controls.
254 * This will initialize a new git repository (creating the repo_path
255 * if requested by flags) and working directory as needed. It will
256 * auto-detect the case sensitivity of the file system and if the
257 * file system supports file mode bits correctly.
259 * @param repo_out Pointer to the repo which will be created or reinitialized.
260 * @param repo_path The path to the repository.
261 * @param opts Pointer to git_repository_init_options struct.
262 * @return 0 or an error code on failure.
264 GIT_EXTERN(int) git_repository_init_ext(
265 git_repository
**repo_out
,
266 const char *repo_path
,
267 git_repository_init_options
*opts
);
270 * Retrieve and resolve the reference pointed at by HEAD.
272 * @param head_out pointer to the reference which will be retrieved
273 * @param repo a repository object
275 * @return 0 on success; error code otherwise
277 GIT_EXTERN(int) git_repository_head(git_reference
**head_out
, git_repository
*repo
);
280 * Check if a repository's HEAD is detached
282 * A repository's HEAD is detached when it points directly to a commit
283 * instead of a branch.
285 * @param repo Repo to test
286 * @return 1 if HEAD is detached, 0 if it's not; error code if there
289 GIT_EXTERN(int) git_repository_head_detached(git_repository
*repo
);
292 * Check if the current branch is an orphan
294 * An orphan branch is one named from HEAD but which doesn't exist in
295 * the refs namespace, because it doesn't have any commit to point to.
297 * @param repo Repo to test
298 * @return 1 if the current branch is an orphan, 0 if it's not; error
299 * code if there was an error
301 GIT_EXTERN(int) git_repository_head_orphan(git_repository
*repo
);
304 * Check if a repository is empty
306 * An empty repository has just been initialized and contains
309 * @param repo Repo to test
310 * @return 1 if the repository is empty, 0 if it isn't, error code
311 * if the repository is corrupted
313 GIT_EXTERN(int) git_repository_is_empty(git_repository
*repo
);
316 * Get the path of this repository
318 * This is the path of the `.git` folder for normal repositories,
319 * or of the repository itself for bare repositories.
321 * @param repo A repository object
322 * @return the path to the repository
324 GIT_EXTERN(const char *) git_repository_path(git_repository
*repo
);
327 * Get the path of the working directory for this repository
329 * If the repository is bare, this function will always return
332 * @param repo A repository object
333 * @return the path to the working dir, if it exists
335 GIT_EXTERN(const char *) git_repository_workdir(git_repository
*repo
);
338 * Set the path to the working directory for this repository
340 * The working directory doesn't need to be the same one
341 * that contains the `.git` folder for this repository.
343 * If this repository is bare, setting its working directory
344 * will turn it into a normal repository, capable of performing
345 * all the common workdir operations (checkout, status, index
346 * manipulation, etc).
348 * @param repo A repository object
349 * @param workdir The path to a working directory
350 * @param update_gitlink Create/update gitlink in workdir and set config
351 * "core.worktree" (if workdir is not the parent of the .git directory)
352 * @return 0, or an error code
354 GIT_EXTERN(int) git_repository_set_workdir(
355 git_repository
*repo
, const char *workdir
, int update_gitlink
);
358 * Check if a repository is bare
360 * @param repo Repo to test
361 * @return 1 if the repository is bare, 0 otherwise.
363 GIT_EXTERN(int) git_repository_is_bare(git_repository
*repo
);
366 * Get the configuration file for this repository.
368 * If a configuration file has not been set, the default
369 * config set for the repository will be returned, including
370 * global and system configurations (if they are available).
372 * The configuration file must be freed once it's no longer
373 * being used by the user.
375 * @param out Pointer to store the loaded config file
376 * @param repo A repository object
377 * @return 0, or an error code
379 GIT_EXTERN(int) git_repository_config(git_config
**out
, git_repository
*repo
);
382 * Set the configuration file for this repository
384 * This configuration file will be used for all configuration
385 * queries involving this repository.
387 * The repository will keep a reference to the config file;
388 * the user must still free the config after setting it
389 * to the repository, or it will leak.
391 * @param repo A repository object
392 * @param config A Config object
394 GIT_EXTERN(void) git_repository_set_config(git_repository
*repo
, git_config
*config
);
397 * Get the Object Database for this repository.
399 * If a custom ODB has not been set, the default
400 * database for the repository will be returned (the one
401 * located in `.git/objects`).
403 * The ODB must be freed once it's no longer being used by
406 * @param out Pointer to store the loaded ODB
407 * @param repo A repository object
408 * @return 0, or an error code
410 GIT_EXTERN(int) git_repository_odb(git_odb
**out
, git_repository
*repo
);
413 * Set the Object Database for this repository
415 * The ODB will be used for all object-related operations
416 * involving this repository.
418 * The repository will keep a reference to the ODB; the user
419 * must still free the ODB object after setting it to the
420 * repository, or it will leak.
422 * @param repo A repository object
423 * @param odb An ODB object
425 GIT_EXTERN(void) git_repository_set_odb(git_repository
*repo
, git_odb
*odb
);
428 * Get the Index file for this repository.
430 * If a custom index has not been set, the default
431 * index for the repository will be returned (the one
432 * located in `.git/index`).
434 * The index must be freed once it's no longer being used by
437 * @param out Pointer to store the loaded index
438 * @param repo A repository object
439 * @return 0, or an error code
441 GIT_EXTERN(int) git_repository_index(git_index
**out
, git_repository
*repo
);
444 * Set the index file for this repository
446 * This index will be used for all index-related operations
447 * involving this repository.
449 * The repository will keep a reference to the index file;
450 * the user must still free the index after setting it
451 * to the repository, or it will leak.
453 * @param repo A repository object
454 * @param index An index object
456 GIT_EXTERN(void) git_repository_set_index(git_repository
*repo
, git_index
*index
);
459 * Retrieve git's prepared message
461 * Operations such as git revert/cherry-pick/merge with the -n option
462 * stop just short of creating a commit with the changes and save
463 * their prepared message in .git/MERGE_MSG so the next git-commit
464 * execution can present it to the user for them to amend if they
467 * Use this function to get the contents of this file. Don't forget to
468 * remove the file after you create the commit.
470 * @param buffer Buffer to write data into or NULL to just read required size
471 * @param len Length of buffer in bytes
472 * @param repo Repository to read prepared message from
473 * @return Bytes written to buffer, GIT_ENOTFOUND if no message, or -1 on error
475 GIT_EXTERN(int) git_repository_message(char *buffer
, size_t len
, git_repository
*repo
);
478 * Remove git's prepared message.
480 * Remove the message that `git_repository_message` retrieves.
482 GIT_EXTERN(int) git_repository_message_remove(git_repository
*repo
);
485 * Calculate hash of file using repository filtering rules.
487 * If you simply want to calculate the hash of a file on disk with no filters,
488 * you can just use the `git_odb_hashfile()` API. However, if you want to
489 * hash a file in the repository and you want to apply filtering rules (e.g.
490 * crlf filters) before generating the SHA, then use this function.
492 * @param out Output value of calculated SHA
493 * @param repo Repository pointer
494 * @param path Path to file on disk whose contents should be hashed. If the
495 * repository is not NULL, this can be a relative path.
496 * @param type The object type to hash as (e.g. GIT_OBJ_BLOB)
497 * @param as_path The path to use to look up filtering rules. If this is
498 * NULL, then the `path` parameter will be used instead. If
499 * this is passed as the empty string, then no filters will be
500 * applied when calculating the hash.
502 GIT_EXTERN(int) git_repository_hashfile(
504 git_repository
*repo
,
507 const char *as_path
);
510 * Make the repository HEAD directly point to the Commit.
512 * If the provided committish cannot be found in the repository, the HEAD
513 * is unaltered and GIT_ENOTFOUND is returned.
515 * If the provided commitish cannot be peeled into a commit, the HEAD
516 * is unaltered and -1 is returned.
518 * Otherwise, the HEAD will eventually be detached and will directly point to
521 * @param repo Repository pointer
522 * @param commitish Object id of the Commit the HEAD should point to
523 * @return 0 on success, or an error code
525 GIT_EXTERN(int) git_repository_set_head_detached(
526 git_repository
* repo
,
527 const git_oid
* commitish
);
532 * If the HEAD is already detached and points to a Commit, 0 is returned.
534 * If the HEAD is already detached and points to a Tag, the HEAD is
535 * updated into making it point to the peeled Commit, and 0 is returned.
537 * If the HEAD is already detached and points to a non commitish, the HEAD is
538 * unaletered, and -1 is returned.
540 * Otherwise, the HEAD will be detached and point to the peeled Commit.
542 * @param repo Repository pointer
543 * @return 0 on success, or an error code
545 GIT_EXTERN(int) git_repository_detach_head(
546 git_repository
* repo
);