1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 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. 6 */ 7 #ifndef INCLUDE_git_repository_h__ 8 #define INCLUDE_git_repository_h__ 9 10 #include "common.h" 11 #include "types.h" 12 #include "oid.h" 13 #include "buffer.h" 14 15 /** 16 * @file git2/repository.h 17 * @brief Git repository management routines 18 * @defgroup git_repository Git repository management routines 19 * @ingroup Git 20 * @{ 21 */ 22 GIT_BEGIN_DECL 23 24 /** 25 * Open a git repository. 26 * 27 * The 'path' argument must point to either a git repository 28 * folder, or an existing work dir. 29 * 30 * The method will automatically detect if 'path' is a normal 31 * or bare repository or fail is 'path' is neither. 32 * 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 36 */ 37 GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path); 38 /** 39 * Open working tree as a repository 40 * 41 * Open the working directory of the working tree as a normal 42 * repository that can then be worked on. 43 * 44 * @param out Output pointer containing opened repository 45 * @param wt Working tree to open 46 * @return 0 or an error code 47 */ 48 GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_worktree *wt); 49 50 /** 51 * Create a "fake" repository to wrap an object database 52 * 53 * Create a repository object to wrap an object database to be used 54 * with the API when all you have is an object database. This doesn't 55 * have any paths associated with it, so use with care. 56 * 57 * @param out pointer to the repo 58 * @param odb the object database to wrap 59 * @return 0 or an error code 60 */ 61 GIT_EXTERN(int) git_repository_wrap_odb(git_repository **out, git_odb *odb); 62 63 /** 64 * Look for a git repository and copy its path in the given buffer. 65 * The lookup start from base_path and walk across parent directories 66 * if nothing has been found. The lookup ends when the first repository 67 * is found, or when reaching a directory referenced in ceiling_dirs 68 * or when the filesystem changes (in case across_fs is true). 69 * 70 * The method will automatically detect if the repository is bare 71 * (if there is a repository). 72 * 73 * @param out A pointer to a user-allocated git_buf which will contain 74 * the found path. 75 * 76 * @param start_path The base path where the lookup starts. 77 * 78 * @param across_fs If true, then the lookup will not stop when a 79 * filesystem device change is detected while exploring parent directories. 80 * 81 * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR separated list of 82 * absolute symbolic link free paths. The lookup will stop when any 83 * of this paths is reached. Note that the lookup always performs on 84 * start_path no matter start_path appears in ceiling_dirs ceiling_dirs 85 * might be NULL (which is equivalent to an empty string) 86 * 87 * @return 0 or an error code 88 */ 89 GIT_EXTERN(int) git_repository_discover( 90 git_buf *out, 91 const char *start_path, 92 int across_fs, 93 const char *ceiling_dirs); 94 95 /** 96 * Option flags for `git_repository_open_ext`. 97 */ 98 typedef enum { 99 /** 100 * Only open the repository if it can be immediately found in the 101 * start_path. Do not walk up from the start_path looking at parent 102 * directories. 103 */ 104 GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0), 105 106 /** 107 * Unless this flag is set, open will not continue searching across 108 * filesystem boundaries (i.e. when `st_dev` changes from the `stat` 109 * system call). For example, searching in a user's home directory at 110 * "/home/user/source/" will not return "/.git/" as the found repo if 111 * "/" is a different filesystem than "/home". 112 */ 113 GIT_REPOSITORY_OPEN_CROSS_FS = (1 << 1), 114 115 /** 116 * Open repository as a bare repo regardless of core.bare config, and 117 * defer loading config file for faster setup. 118 * Unlike `git_repository_open_bare`, this can follow gitlinks. 119 */ 120 GIT_REPOSITORY_OPEN_BARE = (1 << 2), 121 122 /** 123 * Do not check for a repository by appending /.git to the start_path; 124 * only open the repository if start_path itself points to the git 125 * directory. 126 */ 127 GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3), 128 129 /** 130 * Find and open a git repository, respecting the environment variables 131 * used by the git command-line tools. 132 * If set, `git_repository_open_ext` will ignore the other flags and 133 * the `ceiling_dirs` argument, and will allow a NULL `path` to use 134 * `GIT_DIR` or search from the current directory. 135 * The search for a repository will respect $GIT_CEILING_DIRECTORIES and 136 * $GIT_DISCOVERY_ACROSS_FILESYSTEM. The opened repository will 137 * respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and 138 * $GIT_ALTERNATE_OBJECT_DIRECTORIES. 139 * In the future, this flag will also cause `git_repository_open_ext` 140 * to respect $GIT_WORK_TREE and $GIT_COMMON_DIR; currently, 141 * `git_repository_open_ext` with this flag will error out if either 142 * $GIT_WORK_TREE or $GIT_COMMON_DIR is set. 143 */ 144 GIT_REPOSITORY_OPEN_FROM_ENV = (1 << 4), 145 } git_repository_open_flag_t; 146 147 /** 148 * Find and open a repository with extended controls. 149 * 150 * @param out Pointer to the repo which will be opened. This can 151 * actually be NULL if you only want to use the error code to 152 * see if a repo at this path could be opened. 153 * @param path Path to open as git repository. If the flags 154 * permit "searching", then this can be a path to a subdirectory 155 * inside the working directory of the repository. May be NULL if 156 * flags is GIT_REPOSITORY_OPEN_FROM_ENV. 157 * @param flags A combination of the GIT_REPOSITORY_OPEN flags above. 158 * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR delimited list of path 159 * prefixes at which the search for a containing repository should 160 * terminate. 161 * @return 0 on success, GIT_ENOTFOUND if no repository could be found, 162 * or -1 if there was a repository but open failed for some reason 163 * (such as repo corruption or system errors). 164 */ 165 GIT_EXTERN(int) git_repository_open_ext( 166 git_repository **out, 167 const char *path, 168 unsigned int flags, 169 const char *ceiling_dirs); 170 171 /** 172 * Open a bare repository on the serverside. 173 * 174 * This is a fast open for bare repositories that will come in handy 175 * if you're e.g. hosting git repositories and need to access them 176 * efficiently 177 * 178 * @param out Pointer to the repo which will be opened. 179 * @param bare_path Direct path to the bare repository 180 * @return 0 on success, or an error code 181 */ 182 GIT_EXTERN(int) git_repository_open_bare(git_repository **out, const char *bare_path); 183 184 /** 185 * Free a previously allocated repository 186 * 187 * Note that after a repository is free'd, all the objects it has spawned 188 * will still exist until they are manually closed by the user 189 * with `git_object_free`, but accessing any of the attributes of 190 * an object without a backing repository will result in undefined 191 * behavior 192 * 193 * @param repo repository handle to close. If NULL nothing occurs. 194 */ 195 GIT_EXTERN(void) git_repository_free(git_repository *repo); 196 197 /** 198 * Creates a new Git repository in the given folder. 199 * 200 * TODO: 201 * - Reinit the repository 202 * 203 * @param out pointer to the repo which will be created or reinitialized 204 * @param path the path to the repository 205 * @param is_bare if true, a Git repository without a working directory is 206 * created at the pointed path. If false, provided path will be 207 * considered as the working directory into which the .git directory 208 * will be created. 209 * 210 * @return 0 or an error code 211 */ 212 GIT_EXTERN(int) git_repository_init( 213 git_repository **out, 214 const char *path, 215 unsigned is_bare); 216 217 /** 218 * Option flags for `git_repository_init_ext`. 219 * 220 * These flags configure extra behaviors to `git_repository_init_ext`. 221 * In every case, the default behavior is the zero value (i.e. flag is 222 * not set). Just OR the flag values together for the `flags` parameter 223 * when initializing a new repo. Details of individual values are: 224 * 225 * * BARE - Create a bare repository with no working directory. 226 * * NO_REINIT - Return an GIT_EEXISTS error if the repo_path appears to 227 * already be an git repository. 228 * * NO_DOTGIT_DIR - Normally a "/.git/" will be appended to the repo 229 * path for non-bare repos (if it is not already there), but 230 * passing this flag prevents that behavior. 231 * * MKDIR - Make the repo_path (and workdir_path) as needed. Init is 232 * always willing to create the ".git" directory even without this 233 * flag. This flag tells init to create the trailing component of 234 * the repo and workdir paths as needed. 235 * * MKPATH - Recursively make all components of the repo and workdir 236 * paths as necessary. 237 * * EXTERNAL_TEMPLATE - libgit2 normally uses internal templates to 238 * initialize a new repo. This flags enables external templates, 239 * looking the "template_path" from the options if set, or the 240 * `init.templatedir` global config if not, or falling back on 241 * "/usr/share/git-core/templates" if it exists. 242 * * GIT_REPOSITORY_INIT_RELATIVE_GITLINK - If an alternate workdir is 243 * specified, use relative paths for the gitdir and core.worktree. 244 */ 245 typedef enum { 246 GIT_REPOSITORY_INIT_BARE = (1u << 0), 247 GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1), 248 GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2), 249 GIT_REPOSITORY_INIT_MKDIR = (1u << 3), 250 GIT_REPOSITORY_INIT_MKPATH = (1u << 4), 251 GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5), 252 GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6), 253 } git_repository_init_flag_t; 254 255 /** 256 * Mode options for `git_repository_init_ext`. 257 * 258 * Set the mode field of the `git_repository_init_options` structure 259 * either to the custom mode that you would like, or to one of the 260 * following modes: 261 * 262 * * SHARED_UMASK - Use permissions configured by umask - the default. 263 * * SHARED_GROUP - Use "--shared=group" behavior, chmod'ing the new repo 264 * to be group writable and "g+sx" for sticky group assignment. 265 * * SHARED_ALL - Use "--shared=all" behavior, adding world readability. 266 * * Anything else - Set to custom value. 267 */ 268 typedef enum { 269 GIT_REPOSITORY_INIT_SHARED_UMASK = 0, 270 GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775, 271 GIT_REPOSITORY_INIT_SHARED_ALL = 0002777, 272 } git_repository_init_mode_t; 273 274 /** 275 * Extended options structure for `git_repository_init_ext`. 276 * 277 * This contains extra options for `git_repository_init_ext` that enable 278 * additional initialization features. The fields are: 279 * 280 * * flags - Combination of GIT_REPOSITORY_INIT flags above. 281 * * mode - Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... 282 * constants above, or to a custom value that you would like. 283 * * workdir_path - The path to the working dir or NULL for default (i.e. 284 * repo_path parent on non-bare repos). IF THIS IS RELATIVE PATH, 285 * IT WILL BE EVALUATED RELATIVE TO THE REPO_PATH. If this is not 286 * the "natural" working directory, a .git gitlink file will be 287 * created here linking to the repo_path. 288 * * description - If set, this will be used to initialize the "description" 289 * file in the repository, instead of using the template content. 290 * * template_path - When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set, 291 * this contains the path to use for the template directory. If 292 * this is NULL, the config or default directory options will be 293 * used instead. 294 * * initial_head - The name of the head to point HEAD at. If NULL, then 295 * this will be treated as "master" and the HEAD ref will be set 296 * to "refs/heads/master". If this begins with "refs/" it will be 297 * used verbatim; otherwise "refs/heads/" will be prefixed. 298 * * origin_url - If this is non-NULL, then after the rest of the 299 * repository initialization is completed, an "origin" remote 300 * will be added pointing to this URL. 301 */ 302 typedef struct { 303 unsigned int version; 304 uint32_t flags; 305 uint32_t mode; 306 const char *workdir_path; 307 const char *description; 308 const char *template_path; 309 const char *initial_head; 310 const char *origin_url; 311 } git_repository_init_options; 312 313 #define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1 314 #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION} 315 316 /** 317 * Initialize git_repository_init_options structure 318 * 319 * Initializes a `git_repository_init_options` with default values. Equivalent to 320 * creating an instance with `GIT_REPOSITORY_INIT_OPTIONS_INIT`. 321 * 322 * @param opts The `git_repository_init_options` struct to initialize. 323 * @param version The struct version; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`. 324 * @return Zero on success; -1 on failure. 325 */ 326 GIT_EXTERN(int) git_repository_init_options_init( 327 git_repository_init_options *opts, 328 unsigned int version); 329 330 /** 331 * Create a new Git repository in the given folder with extended controls. 332 * 333 * This will initialize a new git repository (creating the repo_path 334 * if requested by flags) and working directory as needed. It will 335 * auto-detect the case sensitivity of the file system and if the 336 * file system supports file mode bits correctly. 337 * 338 * @param out Pointer to the repo which will be created or reinitialized. 339 * @param repo_path The path to the repository. 340 * @param opts Pointer to git_repository_init_options struct. 341 * @return 0 or an error code on failure. 342 */ 343 GIT_EXTERN(int) git_repository_init_ext( 344 git_repository **out, 345 const char *repo_path, 346 git_repository_init_options *opts); 347 348 /** 349 * Retrieve and resolve the reference pointed at by HEAD. 350 * 351 * The returned `git_reference` will be owned by caller and 352 * `git_reference_free()` must be called when done with it to release the 353 * allocated memory and prevent a leak. 354 * 355 * @param out pointer to the reference which will be retrieved 356 * @param repo a repository object 357 * 358 * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing 359 * branch, GIT_ENOTFOUND when HEAD is missing; an error code otherwise 360 */ 361 GIT_EXTERN(int) git_repository_head(git_reference **out, git_repository *repo); 362 363 /** 364 * Retrieve the referenced HEAD for the worktree 365 * 366 * @param out pointer to the reference which will be retrieved 367 * @param repo a repository object 368 * @param name name of the worktree to retrieve HEAD for 369 * @return 0 when successful, error-code otherwise 370 */ 371 GIT_EXTERN(int) git_repository_head_for_worktree(git_reference **out, git_repository *repo, 372 const char *name); 373 374 /** 375 * Check if a repository's HEAD is detached 376 * 377 * A repository's HEAD is detached when it points directly to a commit 378 * instead of a branch. 379 * 380 * @param repo Repo to test 381 * @return 1 if HEAD is detached, 0 if it's not; error code if there 382 * was an error. 383 */ 384 GIT_EXTERN(int) git_repository_head_detached(git_repository *repo); 385 386 /** 387 * Check if a worktree's HEAD is detached 388 * 389 * A worktree's HEAD is detached when it points directly to a 390 * commit instead of a branch. 391 * 392 * @param repo a repository object 393 * @param name name of the worktree to retrieve HEAD for 394 * @return 1 if HEAD is detached, 0 if its not; error code if 395 * there was an error 396 */ 397 GIT_EXTERN(int) git_repository_head_detached_for_worktree(git_repository *repo, 398 const char *name); 399 400 /** 401 * Check if the current branch is unborn 402 * 403 * An unborn branch is one named from HEAD but which doesn't exist in 404 * the refs namespace, because it doesn't have any commit to point to. 405 * 406 * @param repo Repo to test 407 * @return 1 if the current branch is unborn, 0 if it's not; error 408 * code if there was an error 409 */ 410 GIT_EXTERN(int) git_repository_head_unborn(git_repository *repo); 411 412 /** 413 * Check if a repository is empty 414 * 415 * An empty repository has just been initialized and contains no references 416 * apart from HEAD, which must be pointing to the unborn master branch. 417 * 418 * @param repo Repo to test 419 * @return 1 if the repository is empty, 0 if it isn't, error code 420 * if the repository is corrupted 421 */ 422 GIT_EXTERN(int) git_repository_is_empty(git_repository *repo); 423 424 /** 425 * List of items which belong to the git repository layout 426 */ 427 typedef enum { 428 GIT_REPOSITORY_ITEM_GITDIR, 429 GIT_REPOSITORY_ITEM_WORKDIR, 430 GIT_REPOSITORY_ITEM_COMMONDIR, 431 GIT_REPOSITORY_ITEM_INDEX, 432 GIT_REPOSITORY_ITEM_OBJECTS, 433 GIT_REPOSITORY_ITEM_REFS, 434 GIT_REPOSITORY_ITEM_PACKED_REFS, 435 GIT_REPOSITORY_ITEM_REMOTES, 436 GIT_REPOSITORY_ITEM_CONFIG, 437 GIT_REPOSITORY_ITEM_INFO, 438 GIT_REPOSITORY_ITEM_HOOKS, 439 GIT_REPOSITORY_ITEM_LOGS, 440 GIT_REPOSITORY_ITEM_MODULES, 441 GIT_REPOSITORY_ITEM_WORKTREES, 442 GIT_REPOSITORY_ITEM__LAST 443 } git_repository_item_t; 444 445 /** 446 * Get the location of a specific repository file or directory 447 * 448 * This function will retrieve the path of a specific repository 449 * item. It will thereby honor things like the repository's 450 * common directory, gitdir, etc. In case a file path cannot 451 * exist for a given item (e.g. the working directory of a bare 452 * repository), GIT_ENOTFOUND is returned. 453 * 454 * @param out Buffer to store the path at 455 * @param repo Repository to get path for 456 * @param item The repository item for which to retrieve the path 457 * @return 0, GIT_ENOTFOUND if the path cannot exist or an error code 458 */ 459 GIT_EXTERN(int) git_repository_item_path(git_buf *out, const git_repository *repo, git_repository_item_t item); 460 461 /** 462 * Get the path of this repository 463 * 464 * This is the path of the `.git` folder for normal repositories, 465 * or of the repository itself for bare repositories. 466 * 467 * @param repo A repository object 468 * @return the path to the repository 469 */ 470 GIT_EXTERN(const char *) git_repository_path(const git_repository *repo); 471 472 /** 473 * Get the path of the working directory for this repository 474 * 475 * If the repository is bare, this function will always return 476 * NULL. 477 * 478 * @param repo A repository object 479 * @return the path to the working dir, if it exists 480 */ 481 GIT_EXTERN(const char *) git_repository_workdir(const git_repository *repo); 482 483 /** 484 * Get the path of the shared common directory for this repository. 485 * 486 * If the repository is bare, it is the root directory for the repository. 487 * If the repository is a worktree, it is the parent repo's gitdir. 488 * Otherwise, it is the gitdir. 489 * 490 * @param repo A repository object 491 * @return the path to the common dir 492 */ 493 GIT_EXTERN(const char *) git_repository_commondir(const git_repository *repo); 494 495 /** 496 * Set the path to the working directory for this repository 497 * 498 * The working directory doesn't need to be the same one 499 * that contains the `.git` folder for this repository. 500 * 501 * If this repository is bare, setting its working directory 502 * will turn it into a normal repository, capable of performing 503 * all the common workdir operations (checkout, status, index 504 * manipulation, etc). 505 * 506 * @param repo A repository object 507 * @param workdir The path to a working directory 508 * @param update_gitlink Create/update gitlink in workdir and set config 509 * "core.worktree" (if workdir is not the parent of the .git directory) 510 * @return 0, or an error code 511 */ 512 GIT_EXTERN(int) git_repository_set_workdir( 513 git_repository *repo, const char *workdir, int update_gitlink); 514 515 /** 516 * Check if a repository is bare 517 * 518 * @param repo Repo to test 519 * @return 1 if the repository is bare, 0 otherwise. 520 */ 521 GIT_EXTERN(int) git_repository_is_bare(const git_repository *repo); 522 523 /** 524 * Check if a repository is a linked work tree 525 * 526 * @param repo Repo to test 527 * @return 1 if the repository is a linked work tree, 0 otherwise. 528 */ 529 GIT_EXTERN(int) git_repository_is_worktree(const git_repository *repo); 530 531 /** 532 * Get the configuration file for this repository. 533 * 534 * If a configuration file has not been set, the default 535 * config set for the repository will be returned, including 536 * global and system configurations (if they are available). 537 * 538 * The configuration file must be freed once it's no longer 539 * being used by the user. 540 * 541 * @param out Pointer to store the loaded configuration 542 * @param repo A repository object 543 * @return 0, or an error code 544 */ 545 GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo); 546 547 /** 548 * Get a snapshot of the repository's configuration 549 * 550 * Convenience function to take a snapshot from the repository's 551 * configuration. The contents of this snapshot will not change, 552 * even if the underlying config files are modified. 553 * 554 * The configuration file must be freed once it's no longer 555 * being used by the user. 556 * 557 * @param out Pointer to store the loaded configuration 558 * @param repo the repository 559 * @return 0, or an error code 560 */ 561 GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository *repo); 562 563 /** 564 * Get the Object Database for this repository. 565 * 566 * If a custom ODB has not been set, the default 567 * database for the repository will be returned (the one 568 * located in `.git/objects`). 569 * 570 * The ODB must be freed once it's no longer being used by 571 * the user. 572 * 573 * @param out Pointer to store the loaded ODB 574 * @param repo A repository object 575 * @return 0, or an error code 576 */ 577 GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo); 578 579 /** 580 * Get the Reference Database Backend for this repository. 581 * 582 * If a custom refsdb has not been set, the default database for 583 * the repository will be returned (the one that manipulates loose 584 * and packed references in the `.git` directory). 585 * 586 * The refdb must be freed once it's no longer being used by 587 * the user. 588 * 589 * @param out Pointer to store the loaded refdb 590 * @param repo A repository object 591 * @return 0, or an error code 592 */ 593 GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo); 594 595 /** 596 * Get the Index file for this repository. 597 * 598 * If a custom index has not been set, the default 599 * index for the repository will be returned (the one 600 * located in `.git/index`). 601 * 602 * The index must be freed once it's no longer being used by 603 * the user. 604 * 605 * @param out Pointer to store the loaded index 606 * @param repo A repository object 607 * @return 0, or an error code 608 */ 609 GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo); 610 611 /** 612 * Retrieve git's prepared message 613 * 614 * Operations such as git revert/cherry-pick/merge with the -n option 615 * stop just short of creating a commit with the changes and save 616 * their prepared message in .git/MERGE_MSG so the next git-commit 617 * execution can present it to the user for them to amend if they 618 * wish. 619 * 620 * Use this function to get the contents of this file. Don't forget to 621 * remove the file after you create the commit. 622 * 623 * @param out git_buf to write data into 624 * @param repo Repository to read prepared message from 625 * @return 0, GIT_ENOTFOUND if no message exists or an error code 626 */ 627 GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo); 628 629 /** 630 * Remove git's prepared message. 631 * 632 * Remove the message that `git_repository_message` retrieves. 633 */ 634 GIT_EXTERN(int) git_repository_message_remove(git_repository *repo); 635 636 /** 637 * Remove all the metadata associated with an ongoing command like merge, 638 * revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc. 639 * 640 * @param repo A repository object 641 * @return 0 on success, or error 642 */ 643 GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo); 644 645 /** 646 * Callback used to iterate over each FETCH_HEAD entry 647 * 648 * @see git_repository_fetchhead_foreach 649 * 650 * @param ref_name The reference name 651 * @param remote_url The remote URL 652 * @param oid The reference target OID 653 * @param is_merge Was the reference the result of a merge 654 * @param payload Payload passed to git_repository_fetchhead_foreach 655 * @return non-zero to terminate the iteration 656 */ 657 typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb)(const char *ref_name, 658 const char *remote_url, 659 const git_oid *oid, 660 unsigned int is_merge, 661 void *payload); 662 663 /** 664 * Invoke 'callback' for each entry in the given FETCH_HEAD file. 665 * 666 * Return a non-zero value from the callback to stop the loop. 667 * 668 * @param repo A repository object 669 * @param callback Callback function 670 * @param payload Pointer to callback data (optional) 671 * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if 672 * there is no FETCH_HEAD file, or other error code. 673 */ 674 GIT_EXTERN(int) git_repository_fetchhead_foreach( 675 git_repository *repo, 676 git_repository_fetchhead_foreach_cb callback, 677 void *payload); 678 679 /** 680 * Callback used to iterate over each MERGE_HEAD entry 681 * 682 * @see git_repository_mergehead_foreach 683 * 684 * @param oid The merge OID 685 * @param payload Payload passed to git_repository_mergehead_foreach 686 * @return non-zero to terminate the iteration 687 */ 688 typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb)(const git_oid *oid, 689 void *payload); 690 691 /** 692 * If a merge is in progress, invoke 'callback' for each commit ID in the 693 * MERGE_HEAD file. 694 * 695 * Return a non-zero value from the callback to stop the loop. 696 * 697 * @param repo A repository object 698 * @param callback Callback function 699 * @param payload Pointer to callback data (optional) 700 * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if 701 * there is no MERGE_HEAD file, or other error code. 702 */ 703 GIT_EXTERN(int) git_repository_mergehead_foreach( 704 git_repository *repo, 705 git_repository_mergehead_foreach_cb callback, 706 void *payload); 707 708 /** 709 * Calculate hash of file using repository filtering rules. 710 * 711 * If you simply want to calculate the hash of a file on disk with no filters, 712 * you can just use the `git_odb_hashfile()` API. However, if you want to 713 * hash a file in the repository and you want to apply filtering rules (e.g. 714 * crlf filters) before generating the SHA, then use this function. 715 * 716 * Note: if the repository has `core.safecrlf` set to fail and the 717 * filtering triggers that failure, then this function will return an 718 * error and not calculate the hash of the file. 719 * 720 * @param out Output value of calculated SHA 721 * @param repo Repository pointer 722 * @param path Path to file on disk whose contents should be hashed. If the 723 * repository is not NULL, this can be a relative path. 724 * @param type The object type to hash as (e.g. GIT_OBJECT_BLOB) 725 * @param as_path The path to use to look up filtering rules. If this is 726 * NULL, then the `path` parameter will be used instead. If 727 * this is passed as the empty string, then no filters will be 728 * applied when calculating the hash. 729 * @return 0 on success, or an error code 730 */ 731 GIT_EXTERN(int) git_repository_hashfile( 732 git_oid *out, 733 git_repository *repo, 734 const char *path, 735 git_object_t type, 736 const char *as_path); 737 738 /** 739 * Make the repository HEAD point to the specified reference. 740 * 741 * If the provided reference points to a Tree or a Blob, the HEAD is 742 * unaltered and -1 is returned. 743 * 744 * If the provided reference points to a branch, the HEAD will point 745 * to that branch, staying attached, or become attached if it isn't yet. 746 * If the branch doesn't exist yet, no error will be return. The HEAD 747 * will then be attached to an unborn branch. 748 * 749 * Otherwise, the HEAD will be detached and will directly point to 750 * the Commit. 751 * 752 * @param repo Repository pointer 753 * @param refname Canonical name of the reference the HEAD should point at 754 * @return 0 on success, or an error code 755 */ 756 GIT_EXTERN(int) git_repository_set_head( 757 git_repository* repo, 758 const char* refname); 759 760 /** 761 * Make the repository HEAD directly point to the Commit. 762 * 763 * If the provided committish cannot be found in the repository, the HEAD 764 * is unaltered and GIT_ENOTFOUND is returned. 765 * 766 * If the provided commitish cannot be peeled into a commit, the HEAD 767 * is unaltered and -1 is returned. 768 * 769 * Otherwise, the HEAD will eventually be detached and will directly point to 770 * the peeled Commit. 771 * 772 * @param repo Repository pointer 773 * @param commitish Object id of the Commit the HEAD should point to 774 * @return 0 on success, or an error code 775 */ 776 GIT_EXTERN(int) git_repository_set_head_detached( 777 git_repository* repo, 778 const git_oid* commitish); 779 780 /** 781 * Make the repository HEAD directly point to the Commit. 782 * 783 * This behaves like `git_repository_set_head_detached()` but takes an 784 * annotated commit, which lets you specify which extended sha syntax 785 * string was specified by a user, allowing for more exact reflog 786 * messages. 787 * 788 * See the documentation for `git_repository_set_head_detached()`. 789 * 790 * @see git_repository_set_head_detached 791 */ 792 GIT_EXTERN(int) git_repository_set_head_detached_from_annotated( 793 git_repository *repo, 794 const git_annotated_commit *commitish); 795 796 /** 797 * Detach the HEAD. 798 * 799 * If the HEAD is already detached and points to a Commit, 0 is returned. 800 * 801 * If the HEAD is already detached and points to a Tag, the HEAD is 802 * updated into making it point to the peeled Commit, and 0 is returned. 803 * 804 * If the HEAD is already detached and points to a non commitish, the HEAD is 805 * unaltered, and -1 is returned. 806 * 807 * Otherwise, the HEAD will be detached and point to the peeled Commit. 808 * 809 * @param repo Repository pointer 810 * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing 811 * branch or an error code 812 */ 813 GIT_EXTERN(int) git_repository_detach_head( 814 git_repository* repo); 815 816 /** 817 * Repository state 818 * 819 * These values represent possible states for the repository to be in, 820 * based on the current operation which is ongoing. 821 */ 822 typedef enum { 823 GIT_REPOSITORY_STATE_NONE, 824 GIT_REPOSITORY_STATE_MERGE, 825 GIT_REPOSITORY_STATE_REVERT, 826 GIT_REPOSITORY_STATE_REVERT_SEQUENCE, 827 GIT_REPOSITORY_STATE_CHERRYPICK, 828 GIT_REPOSITORY_STATE_CHERRYPICK_SEQUENCE, 829 GIT_REPOSITORY_STATE_BISECT, 830 GIT_REPOSITORY_STATE_REBASE, 831 GIT_REPOSITORY_STATE_REBASE_INTERACTIVE, 832 GIT_REPOSITORY_STATE_REBASE_MERGE, 833 GIT_REPOSITORY_STATE_APPLY_MAILBOX, 834 GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE, 835 } git_repository_state_t; 836 837 /** 838 * Determines the status of a git repository - ie, whether an operation 839 * (merge, cherry-pick, etc) is in progress. 840 * 841 * @param repo Repository pointer 842 * @return The state of the repository 843 */ 844 GIT_EXTERN(int) git_repository_state(git_repository *repo); 845 846 /** 847 * Sets the active namespace for this Git Repository 848 * 849 * This namespace affects all reference operations for the repo. 850 * See `man gitnamespaces` 851 * 852 * @param repo The repo 853 * @param nmspace The namespace. This should not include the refs 854 * folder, e.g. to namespace all references under `refs/namespaces/foo/`, 855 * use `foo` as the namespace. 856 * @return 0 on success, -1 on error 857 */ 858 GIT_EXTERN(int) git_repository_set_namespace(git_repository *repo, const char *nmspace); 859 860 /** 861 * Get the currently active namespace for this repository 862 * 863 * @param repo The repo 864 * @return the active namespace, or NULL if there isn't one 865 */ 866 GIT_EXTERN(const char *) git_repository_get_namespace(git_repository *repo); 867 868 869 /** 870 * Determine if the repository was a shallow clone 871 * 872 * @param repo The repository 873 * @return 1 if shallow, zero if not 874 */ 875 GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo); 876 877 /** 878 * Retrieve the configured identity to use for reflogs 879 * 880 * The memory is owned by the repository and must not be freed by the 881 * user. 882 * 883 * @param name where to store the pointer to the name 884 * @param email where to store the pointer to the email 885 * @param repo the repository 886 */ 887 GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo); 888 889 /** 890 * Set the identity to be used for writing reflogs 891 * 892 * If both are set, this name and email will be used to write to the 893 * reflog. Pass NULL to unset. When unset, the identity will be taken 894 * from the repository's configuration. 895 * 896 * @param repo the repository to configure 897 * @param name the name to use for the reflog entries 898 * @param email the email to use for the reflog entries 899 */ 900 GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email); 901 902 /** @} */ 903 GIT_END_DECL 904 #endif 905
