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. 224 */ 225 typedef enum { 226 /** 227 * Create a bare repository with no working directory. 228 */ 229 GIT_REPOSITORY_INIT_BARE = (1u << 0), 230 231 /** 232 * Return an GIT_EEXISTS error if the repo_path appears to already be 233 * an git repository. 234 */ 235 GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1), 236 237 /** 238 * Normally a "/.git/" will be appended to the repo path for 239 * non-bare repos (if it is not already there), but passing this flag 240 * prevents that behavior. 241 */ 242 GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2), 243 244 /** 245 * Make the repo_path (and workdir_path) as needed. Init is always willing 246 * to create the ".git" directory even without this flag. This flag tells 247 * init to create the trailing component of the repo and workdir paths 248 * as needed. 249 */ 250 GIT_REPOSITORY_INIT_MKDIR = (1u << 3), 251 252 /** 253 * Recursively make all components of the repo and workdir paths as 254 * necessary. 255 */ 256 GIT_REPOSITORY_INIT_MKPATH = (1u << 4), 257 258 /** 259 * libgit2 normally uses internal templates to initialize a new repo. 260 * This flags enables external templates, looking the "template_path" from 261 * the options if set, or the `init.templatedir` global config if not, 262 * or falling back on "/usr/share/git-core/templates" if it exists. 263 */ 264 GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5), 265 266 /** 267 * If an alternate workdir is specified, use relative paths for the gitdir 268 * and core.worktree. 269 */ 270 GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6), 271 } git_repository_init_flag_t; 272 273 /** 274 * Mode options for `git_repository_init_ext`. 275 * 276 * Set the mode field of the `git_repository_init_options` structure 277 * either to the custom mode that you would like, or to one of the 278 * defined modes. 279 */ 280 typedef enum { 281 /** 282 * Use permissions configured by umask - the default. 283 */ 284 GIT_REPOSITORY_INIT_SHARED_UMASK = 0, 285 286 /** 287 * Use "--shared=group" behavior, chmod'ing the new repo to be group 288 * writable and "g+sx" for sticky group assignment. 289 */ 290 GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775, 291 292 /** 293 * Use "--shared=all" behavior, adding world readability. 294 */ 295 GIT_REPOSITORY_INIT_SHARED_ALL = 0002777, 296 } git_repository_init_mode_t; 297 298 /** 299 * Extended options structure for `git_repository_init_ext`. 300 * 301 * This contains extra options for `git_repository_init_ext` that enable 302 * additional initialization features. 303 */ 304 typedef struct { 305 unsigned int version; 306 307 /** 308 * Combination of GIT_REPOSITORY_INIT flags above. 309 */ 310 uint32_t flags; 311 312 /** 313 * Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... constants 314 * above, or to a custom value that you would like. 315 */ 316 uint32_t mode; 317 318 /** 319 * The path to the working dir or NULL for default (i.e. repo_path parent 320 * on non-bare repos). IF THIS IS RELATIVE PATH, IT WILL BE EVALUATED 321 * RELATIVE TO THE REPO_PATH. If this is not the "natural" working 322 * directory, a .git gitlink file will be created here linking to the 323 * repo_path. 324 */ 325 const char *workdir_path; 326 327 /** 328 * If set, this will be used to initialize the "description" file in the 329 * repository, instead of using the template content. 330 */ 331 const char *description; 332 333 /** 334 * When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set, this contains 335 * the path to use for the template directory. If this is NULL, the config 336 * or default directory options will be used instead. 337 */ 338 const char *template_path; 339 340 /** 341 * The name of the head to point HEAD at. If NULL, then this will be 342 * treated as "master" and the HEAD ref will be set to "refs/heads/master". 343 * If this begins with "refs/" it will be used verbatim; 344 * otherwise "refs/heads/" will be prefixed. 345 */ 346 const char *initial_head; 347 348 /** 349 * If this is non-NULL, then after the rest of the repository 350 * initialization is completed, an "origin" remote will be added 351 * pointing to this URL. 352 */ 353 const char *origin_url; 354 } git_repository_init_options; 355 356 #define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1 357 #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION} 358 359 /** 360 * Initialize git_repository_init_options structure 361 * 362 * Initializes a `git_repository_init_options` with default values. Equivalent to 363 * creating an instance with `GIT_REPOSITORY_INIT_OPTIONS_INIT`. 364 * 365 * @param opts The `git_repository_init_options` struct to initialize. 366 * @param version The struct version; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`. 367 * @return Zero on success; -1 on failure. 368 */ 369 GIT_EXTERN(int) git_repository_init_options_init( 370 git_repository_init_options *opts, 371 unsigned int version); 372 373 /** 374 * Create a new Git repository in the given folder with extended controls. 375 * 376 * This will initialize a new git repository (creating the repo_path 377 * if requested by flags) and working directory as needed. It will 378 * auto-detect the case sensitivity of the file system and if the 379 * file system supports file mode bits correctly. 380 * 381 * @param out Pointer to the repo which will be created or reinitialized. 382 * @param repo_path The path to the repository. 383 * @param opts Pointer to git_repository_init_options struct. 384 * @return 0 or an error code on failure. 385 */ 386 GIT_EXTERN(int) git_repository_init_ext( 387 git_repository **out, 388 const char *repo_path, 389 git_repository_init_options *opts); 390 391 /** 392 * Retrieve and resolve the reference pointed at by HEAD. 393 * 394 * The returned `git_reference` will be owned by caller and 395 * `git_reference_free()` must be called when done with it to release the 396 * allocated memory and prevent a leak. 397 * 398 * @param out pointer to the reference which will be retrieved 399 * @param repo a repository object 400 * 401 * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing 402 * branch, GIT_ENOTFOUND when HEAD is missing; an error code otherwise 403 */ 404 GIT_EXTERN(int) git_repository_head(git_reference **out, git_repository *repo); 405 406 /** 407 * Retrieve the referenced HEAD for the worktree 408 * 409 * @param out pointer to the reference which will be retrieved 410 * @param repo a repository object 411 * @param name name of the worktree to retrieve HEAD for 412 * @return 0 when successful, error-code otherwise 413 */ 414 GIT_EXTERN(int) git_repository_head_for_worktree(git_reference **out, git_repository *repo, 415 const char *name); 416 417 /** 418 * Check if a repository's HEAD is detached 419 * 420 * A repository's HEAD is detached when it points directly to a commit 421 * instead of a branch. 422 * 423 * @param repo Repo to test 424 * @return 1 if HEAD is detached, 0 if it's not; error code if there 425 * was an error. 426 */ 427 GIT_EXTERN(int) git_repository_head_detached(git_repository *repo); 428 429 /** 430 * Check if a worktree's HEAD is detached 431 * 432 * A worktree's HEAD is detached when it points directly to a 433 * commit instead of a branch. 434 * 435 * @param repo a repository object 436 * @param name name of the worktree to retrieve HEAD for 437 * @return 1 if HEAD is detached, 0 if its not; error code if 438 * there was an error 439 */ 440 GIT_EXTERN(int) git_repository_head_detached_for_worktree(git_repository *repo, 441 const char *name); 442 443 /** 444 * Check if the current branch is unborn 445 * 446 * An unborn branch is one named from HEAD but which doesn't exist in 447 * the refs namespace, because it doesn't have any commit to point to. 448 * 449 * @param repo Repo to test 450 * @return 1 if the current branch is unborn, 0 if it's not; error 451 * code if there was an error 452 */ 453 GIT_EXTERN(int) git_repository_head_unborn(git_repository *repo); 454 455 /** 456 * Check if a repository is empty 457 * 458 * An empty repository has just been initialized and contains no references 459 * apart from HEAD, which must be pointing to the unborn master branch. 460 * 461 * @param repo Repo to test 462 * @return 1 if the repository is empty, 0 if it isn't, error code 463 * if the repository is corrupted 464 */ 465 GIT_EXTERN(int) git_repository_is_empty(git_repository *repo); 466 467 /** 468 * List of items which belong to the git repository layout 469 */ 470 typedef enum { 471 GIT_REPOSITORY_ITEM_GITDIR, 472 GIT_REPOSITORY_ITEM_WORKDIR, 473 GIT_REPOSITORY_ITEM_COMMONDIR, 474 GIT_REPOSITORY_ITEM_INDEX, 475 GIT_REPOSITORY_ITEM_OBJECTS, 476 GIT_REPOSITORY_ITEM_REFS, 477 GIT_REPOSITORY_ITEM_PACKED_REFS, 478 GIT_REPOSITORY_ITEM_REMOTES, 479 GIT_REPOSITORY_ITEM_CONFIG, 480 GIT_REPOSITORY_ITEM_INFO, 481 GIT_REPOSITORY_ITEM_HOOKS, 482 GIT_REPOSITORY_ITEM_LOGS, 483 GIT_REPOSITORY_ITEM_MODULES, 484 GIT_REPOSITORY_ITEM_WORKTREES, 485 GIT_REPOSITORY_ITEM__LAST 486 } git_repository_item_t; 487 488 /** 489 * Get the location of a specific repository file or directory 490 * 491 * This function will retrieve the path of a specific repository 492 * item. It will thereby honor things like the repository's 493 * common directory, gitdir, etc. In case a file path cannot 494 * exist for a given item (e.g. the working directory of a bare 495 * repository), GIT_ENOTFOUND is returned. 496 * 497 * @param out Buffer to store the path at 498 * @param repo Repository to get path for 499 * @param item The repository item for which to retrieve the path 500 * @return 0, GIT_ENOTFOUND if the path cannot exist or an error code 501 */ 502 GIT_EXTERN(int) git_repository_item_path(git_buf *out, const git_repository *repo, git_repository_item_t item); 503 504 /** 505 * Get the path of this repository 506 * 507 * This is the path of the `.git` folder for normal repositories, 508 * or of the repository itself for bare repositories. 509 * 510 * @param repo A repository object 511 * @return the path to the repository 512 */ 513 GIT_EXTERN(const char *) git_repository_path(const git_repository *repo); 514 515 /** 516 * Get the path of the working directory for this repository 517 * 518 * If the repository is bare, this function will always return 519 * NULL. 520 * 521 * @param repo A repository object 522 * @return the path to the working dir, if it exists 523 */ 524 GIT_EXTERN(const char *) git_repository_workdir(const git_repository *repo); 525 526 /** 527 * Get the path of the shared common directory for this repository. 528 * 529 * If the repository is bare, it is the root directory for the repository. 530 * If the repository is a worktree, it is the parent repo's gitdir. 531 * Otherwise, it is the gitdir. 532 * 533 * @param repo A repository object 534 * @return the path to the common dir 535 */ 536 GIT_EXTERN(const char *) git_repository_commondir(const git_repository *repo); 537 538 /** 539 * Set the path to the working directory for this repository 540 * 541 * The working directory doesn't need to be the same one 542 * that contains the `.git` folder for this repository. 543 * 544 * If this repository is bare, setting its working directory 545 * will turn it into a normal repository, capable of performing 546 * all the common workdir operations (checkout, status, index 547 * manipulation, etc). 548 * 549 * @param repo A repository object 550 * @param workdir The path to a working directory 551 * @param update_gitlink Create/update gitlink in workdir and set config 552 * "core.worktree" (if workdir is not the parent of the .git directory) 553 * @return 0, or an error code 554 */ 555 GIT_EXTERN(int) git_repository_set_workdir( 556 git_repository *repo, const char *workdir, int update_gitlink); 557 558 /** 559 * Check if a repository is bare 560 * 561 * @param repo Repo to test 562 * @return 1 if the repository is bare, 0 otherwise. 563 */ 564 GIT_EXTERN(int) git_repository_is_bare(const git_repository *repo); 565 566 /** 567 * Check if a repository is a linked work tree 568 * 569 * @param repo Repo to test 570 * @return 1 if the repository is a linked work tree, 0 otherwise. 571 */ 572 GIT_EXTERN(int) git_repository_is_worktree(const git_repository *repo); 573 574 /** 575 * Get the configuration file for this repository. 576 * 577 * If a configuration file has not been set, the default 578 * config set for the repository will be returned, including 579 * global and system configurations (if they are available). 580 * 581 * The configuration file must be freed once it's no longer 582 * being used by the user. 583 * 584 * @param out Pointer to store the loaded configuration 585 * @param repo A repository object 586 * @return 0, or an error code 587 */ 588 GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo); 589 590 /** 591 * Get a snapshot of the repository's configuration 592 * 593 * Convenience function to take a snapshot from the repository's 594 * configuration. The contents of this snapshot will not change, 595 * even if the underlying config files are modified. 596 * 597 * The configuration file must be freed once it's no longer 598 * being used by the user. 599 * 600 * @param out Pointer to store the loaded configuration 601 * @param repo the repository 602 * @return 0, or an error code 603 */ 604 GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository *repo); 605 606 /** 607 * Get the Object Database for this repository. 608 * 609 * If a custom ODB has not been set, the default 610 * database for the repository will be returned (the one 611 * located in `.git/objects`). 612 * 613 * The ODB must be freed once it's no longer being used by 614 * the user. 615 * 616 * @param out Pointer to store the loaded ODB 617 * @param repo A repository object 618 * @return 0, or an error code 619 */ 620 GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo); 621 622 /** 623 * Get the Reference Database Backend for this repository. 624 * 625 * If a custom refsdb has not been set, the default database for 626 * the repository will be returned (the one that manipulates loose 627 * and packed references in the `.git` directory). 628 * 629 * The refdb must be freed once it's no longer being used by 630 * the user. 631 * 632 * @param out Pointer to store the loaded refdb 633 * @param repo A repository object 634 * @return 0, or an error code 635 */ 636 GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo); 637 638 /** 639 * Get the Index file for this repository. 640 * 641 * If a custom index has not been set, the default 642 * index for the repository will be returned (the one 643 * located in `.git/index`). 644 * 645 * The index must be freed once it's no longer being used by 646 * the user. 647 * 648 * @param out Pointer to store the loaded index 649 * @param repo A repository object 650 * @return 0, or an error code 651 */ 652 GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo); 653 654 /** 655 * Retrieve git's prepared message 656 * 657 * Operations such as git revert/cherry-pick/merge with the -n option 658 * stop just short of creating a commit with the changes and save 659 * their prepared message in .git/MERGE_MSG so the next git-commit 660 * execution can present it to the user for them to amend if they 661 * wish. 662 * 663 * Use this function to get the contents of this file. Don't forget to 664 * remove the file after you create the commit. 665 * 666 * @param out git_buf to write data into 667 * @param repo Repository to read prepared message from 668 * @return 0, GIT_ENOTFOUND if no message exists or an error code 669 */ 670 GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo); 671 672 /** 673 * Remove git's prepared message. 674 * 675 * Remove the message that `git_repository_message` retrieves. 676 */ 677 GIT_EXTERN(int) git_repository_message_remove(git_repository *repo); 678 679 /** 680 * Remove all the metadata associated with an ongoing command like merge, 681 * revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc. 682 * 683 * @param repo A repository object 684 * @return 0 on success, or error 685 */ 686 GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo); 687 688 /** 689 * Callback used to iterate over each FETCH_HEAD entry 690 * 691 * @see git_repository_fetchhead_foreach 692 * 693 * @param ref_name The reference name 694 * @param remote_url The remote URL 695 * @param oid The reference target OID 696 * @param is_merge Was the reference the result of a merge 697 * @param payload Payload passed to git_repository_fetchhead_foreach 698 * @return non-zero to terminate the iteration 699 */ 700 typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb)(const char *ref_name, 701 const char *remote_url, 702 const git_oid *oid, 703 unsigned int is_merge, 704 void *payload); 705 706 /** 707 * Invoke 'callback' for each entry in the given FETCH_HEAD file. 708 * 709 * Return a non-zero value from the callback to stop the loop. 710 * 711 * @param repo A repository object 712 * @param callback Callback function 713 * @param payload Pointer to callback data (optional) 714 * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if 715 * there is no FETCH_HEAD file, or other error code. 716 */ 717 GIT_EXTERN(int) git_repository_fetchhead_foreach( 718 git_repository *repo, 719 git_repository_fetchhead_foreach_cb callback, 720 void *payload); 721 722 /** 723 * Callback used to iterate over each MERGE_HEAD entry 724 * 725 * @see git_repository_mergehead_foreach 726 * 727 * @param oid The merge OID 728 * @param payload Payload passed to git_repository_mergehead_foreach 729 * @return non-zero to terminate the iteration 730 */ 731 typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb)(const git_oid *oid, 732 void *payload); 733 734 /** 735 * If a merge is in progress, invoke 'callback' for each commit ID in the 736 * MERGE_HEAD file. 737 * 738 * Return a non-zero value from the callback to stop the loop. 739 * 740 * @param repo A repository object 741 * @param callback Callback function 742 * @param payload Pointer to callback data (optional) 743 * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if 744 * there is no MERGE_HEAD file, or other error code. 745 */ 746 GIT_EXTERN(int) git_repository_mergehead_foreach( 747 git_repository *repo, 748 git_repository_mergehead_foreach_cb callback, 749 void *payload); 750 751 /** 752 * Calculate hash of file using repository filtering rules. 753 * 754 * If you simply want to calculate the hash of a file on disk with no filters, 755 * you can just use the `git_odb_hashfile()` API. However, if you want to 756 * hash a file in the repository and you want to apply filtering rules (e.g. 757 * crlf filters) before generating the SHA, then use this function. 758 * 759 * Note: if the repository has `core.safecrlf` set to fail and the 760 * filtering triggers that failure, then this function will return an 761 * error and not calculate the hash of the file. 762 * 763 * @param out Output value of calculated SHA 764 * @param repo Repository pointer 765 * @param path Path to file on disk whose contents should be hashed. If the 766 * repository is not NULL, this can be a relative path. 767 * @param type The object type to hash as (e.g. GIT_OBJECT_BLOB) 768 * @param as_path The path to use to look up filtering rules. If this is 769 * NULL, then the `path` parameter will be used instead. If 770 * this is passed as the empty string, then no filters will be 771 * applied when calculating the hash. 772 * @return 0 on success, or an error code 773 */ 774 GIT_EXTERN(int) git_repository_hashfile( 775 git_oid *out, 776 git_repository *repo, 777 const char *path, 778 git_object_t type, 779 const char *as_path); 780 781 /** 782 * Make the repository HEAD point to the specified reference. 783 * 784 * If the provided reference points to a Tree or a Blob, the HEAD is 785 * unaltered and -1 is returned. 786 * 787 * If the provided reference points to a branch, the HEAD will point 788 * to that branch, staying attached, or become attached if it isn't yet. 789 * If the branch doesn't exist yet, no error will be return. The HEAD 790 * will then be attached to an unborn branch. 791 * 792 * Otherwise, the HEAD will be detached and will directly point to 793 * the Commit. 794 * 795 * @param repo Repository pointer 796 * @param refname Canonical name of the reference the HEAD should point at 797 * @return 0 on success, or an error code 798 */ 799 GIT_EXTERN(int) git_repository_set_head( 800 git_repository* repo, 801 const char* refname); 802 803 /** 804 * Make the repository HEAD directly point to the Commit. 805 * 806 * If the provided committish cannot be found in the repository, the HEAD 807 * is unaltered and GIT_ENOTFOUND is returned. 808 * 809 * If the provided commitish cannot be peeled into a commit, the HEAD 810 * is unaltered and -1 is returned. 811 * 812 * Otherwise, the HEAD will eventually be detached and will directly point to 813 * the peeled Commit. 814 * 815 * @param repo Repository pointer 816 * @param commitish Object id of the Commit the HEAD should point to 817 * @return 0 on success, or an error code 818 */ 819 GIT_EXTERN(int) git_repository_set_head_detached( 820 git_repository* repo, 821 const git_oid* commitish); 822 823 /** 824 * Make the repository HEAD directly point to the Commit. 825 * 826 * This behaves like `git_repository_set_head_detached()` but takes an 827 * annotated commit, which lets you specify which extended sha syntax 828 * string was specified by a user, allowing for more exact reflog 829 * messages. 830 * 831 * See the documentation for `git_repository_set_head_detached()`. 832 * 833 * @see git_repository_set_head_detached 834 */ 835 GIT_EXTERN(int) git_repository_set_head_detached_from_annotated( 836 git_repository *repo, 837 const git_annotated_commit *commitish); 838 839 /** 840 * Detach the HEAD. 841 * 842 * If the HEAD is already detached and points to a Commit, 0 is returned. 843 * 844 * If the HEAD is already detached and points to a Tag, the HEAD is 845 * updated into making it point to the peeled Commit, and 0 is returned. 846 * 847 * If the HEAD is already detached and points to a non commitish, the HEAD is 848 * unaltered, and -1 is returned. 849 * 850 * Otherwise, the HEAD will be detached and point to the peeled Commit. 851 * 852 * @param repo Repository pointer 853 * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing 854 * branch or an error code 855 */ 856 GIT_EXTERN(int) git_repository_detach_head( 857 git_repository* repo); 858 859 /** 860 * Repository state 861 * 862 * These values represent possible states for the repository to be in, 863 * based on the current operation which is ongoing. 864 */ 865 typedef enum { 866 GIT_REPOSITORY_STATE_NONE, 867 GIT_REPOSITORY_STATE_MERGE, 868 GIT_REPOSITORY_STATE_REVERT, 869 GIT_REPOSITORY_STATE_REVERT_SEQUENCE, 870 GIT_REPOSITORY_STATE_CHERRYPICK, 871 GIT_REPOSITORY_STATE_CHERRYPICK_SEQUENCE, 872 GIT_REPOSITORY_STATE_BISECT, 873 GIT_REPOSITORY_STATE_REBASE, 874 GIT_REPOSITORY_STATE_REBASE_INTERACTIVE, 875 GIT_REPOSITORY_STATE_REBASE_MERGE, 876 GIT_REPOSITORY_STATE_APPLY_MAILBOX, 877 GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE, 878 } git_repository_state_t; 879 880 /** 881 * Determines the status of a git repository - ie, whether an operation 882 * (merge, cherry-pick, etc) is in progress. 883 * 884 * @param repo Repository pointer 885 * @return The state of the repository 886 */ 887 GIT_EXTERN(int) git_repository_state(git_repository *repo); 888 889 /** 890 * Sets the active namespace for this Git Repository 891 * 892 * This namespace affects all reference operations for the repo. 893 * See `man gitnamespaces` 894 * 895 * @param repo The repo 896 * @param nmspace The namespace. This should not include the refs 897 * folder, e.g. to namespace all references under `refs/namespaces/foo/`, 898 * use `foo` as the namespace. 899 * @return 0 on success, -1 on error 900 */ 901 GIT_EXTERN(int) git_repository_set_namespace(git_repository *repo, const char *nmspace); 902 903 /** 904 * Get the currently active namespace for this repository 905 * 906 * @param repo The repo 907 * @return the active namespace, or NULL if there isn't one 908 */ 909 GIT_EXTERN(const char *) git_repository_get_namespace(git_repository *repo); 910 911 912 /** 913 * Determine if the repository was a shallow clone 914 * 915 * @param repo The repository 916 * @return 1 if shallow, zero if not 917 */ 918 GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo); 919 920 /** 921 * Retrieve the configured identity to use for reflogs 922 * 923 * The memory is owned by the repository and must not be freed by the 924 * user. 925 * 926 * @param name where to store the pointer to the name 927 * @param email where to store the pointer to the email 928 * @param repo the repository 929 */ 930 GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo); 931 932 /** 933 * Set the identity to be used for writing reflogs 934 * 935 * If both are set, this name and email will be used to write to the 936 * reflog. Pass NULL to unset. When unset, the identity will be taken 937 * from the repository's configuration. 938 * 939 * @param repo the repository to configure 940 * @param name the name to use for the reflog entries 941 * @param email the email to use for the reflog entries 942 */ 943 GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email); 944 945 /** @} */ 946 GIT_END_DECL 947 #endif 948