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_index_h__ 8 #define INCLUDE_git_index_h__ 9 10 #include "common.h" 11 #include "indexer.h" 12 #include "types.h" 13 #include "oid.h" 14 #include "strarray.h" 15 16 /** 17 * @file git2/index.h 18 * @brief Git index parsing and manipulation routines 19 * @defgroup git_index Git index parsing and manipulation routines 20 * @ingroup Git 21 * @{ 22 */ 23 GIT_BEGIN_DECL 24 25 /** Time structure used in a git index entry */ 26 typedef struct { 27 int32_t seconds; 28 /* nsec should not be stored as time_t compatible */ 29 uint32_t nanoseconds; 30 } git_index_time; 31 32 /** 33 * In-memory representation of a file entry in the index. 34 * 35 * This is a public structure that represents a file entry in the index. 36 * The meaning of the fields corresponds to core Git's documentation (in 37 * "Documentation/technical/index-format.txt"). 38 * 39 * The `flags` field consists of a number of bit fields which can be 40 * accessed via the first set of `GIT_IDXENTRY_...` bitmasks below. These 41 * flags are all read from and persisted to disk. 42 * 43 * The `flags_extended` field also has a number of bit fields which can be 44 * accessed via the later `GIT_IDXENTRY_...` bitmasks below. Some of 45 * these flags are read from and written to disk, but some are set aside 46 * for in-memory only reference. 47 * 48 * Note that the time and size fields are truncated to 32 bits. This 49 * is enough to detect changes, which is enough for the index to 50 * function as a cache, but it should not be taken as an authoritative 51 * source for that data. 52 */ 53 typedef struct git_index_entry { 54 git_index_time ctime; 55 git_index_time mtime; 56 57 uint32_t dev; 58 uint32_t ino; 59 uint32_t mode; 60 uint32_t uid; 61 uint32_t gid; 62 uint32_t file_size; 63 64 git_oid id; 65 66 uint16_t flags; 67 uint16_t flags_extended; 68 69 const char *path; 70 } git_index_entry; 71 72 /** 73 * Bitmasks for on-disk fields of `git_index_entry`'s `flags` 74 * 75 * These bitmasks match the four fields in the `git_index_entry` `flags` 76 * value both in memory and on disk. You can use them to interpret the 77 * data in the `flags`. 78 */ 79 #define GIT_IDXENTRY_NAMEMASK (0x0fff) 80 #define GIT_IDXENTRY_STAGEMASK (0x3000) 81 #define GIT_IDXENTRY_STAGESHIFT 12 82 83 /** 84 * Flags for index entries 85 */ 86 typedef enum { 87 GIT_IDXENTRY_EXTENDED = (0x4000), 88 GIT_IDXENTRY_VALID = (0x8000), 89 } git_indxentry_flag_t; 90 91 #define GIT_IDXENTRY_STAGE(E) \ 92 (((E)->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT) 93 94 #define GIT_IDXENTRY_STAGE_SET(E,S) do { \ 95 (E)->flags = ((E)->flags & ~GIT_IDXENTRY_STAGEMASK) | \ 96 (((S) & 0x03) << GIT_IDXENTRY_STAGESHIFT); } while (0) 97 98 /** 99 * Bitmasks for on-disk fields of `git_index_entry`'s `flags_extended` 100 * 101 * In memory, the `flags_extended` fields are divided into two parts: the 102 * fields that are read from and written to disk, and other fields that 103 * in-memory only and used by libgit2. Only the flags in 104 * `GIT_IDXENTRY_EXTENDED_FLAGS` will get saved on-disk. 105 * 106 * Thee first three bitmasks match the three fields in the 107 * `git_index_entry` `flags_extended` value that belong on disk. You 108 * can use them to interpret the data in the `flags_extended`. 109 * 110 * The rest of the bitmasks match the other fields in the `git_index_entry` 111 * `flags_extended` value that are only used in-memory by libgit2. 112 * You can use them to interpret the data in the `flags_extended`. 113 * 114 */ 115 typedef enum { 116 117 GIT_IDXENTRY_INTENT_TO_ADD = (1 << 13), 118 GIT_IDXENTRY_SKIP_WORKTREE = (1 << 14), 119 /** Reserved for future extension */ 120 GIT_IDXENTRY_EXTENDED2 = (1 << 15), 121 122 GIT_IDXENTRY_EXTENDED_FLAGS = (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE), 123 GIT_IDXENTRY_UPDATE = (1 << 0), 124 GIT_IDXENTRY_REMOVE = (1 << 1), 125 GIT_IDXENTRY_UPTODATE = (1 << 2), 126 GIT_IDXENTRY_ADDED = (1 << 3), 127 128 GIT_IDXENTRY_HASHED = (1 << 4), 129 GIT_IDXENTRY_UNHASHED = (1 << 5), 130 GIT_IDXENTRY_WT_REMOVE = (1 << 6), /**< remove in work directory */ 131 GIT_IDXENTRY_CONFLICTED = (1 << 7), 132 133 GIT_IDXENTRY_UNPACKED = (1 << 8), 134 GIT_IDXENTRY_NEW_SKIP_WORKTREE = (1 << 9), 135 } git_idxentry_extended_flag_t; 136 137 /** Capabilities of system that affect index actions. */ 138 typedef enum { 139 GIT_INDEXCAP_IGNORE_CASE = 1, 140 GIT_INDEXCAP_NO_FILEMODE = 2, 141 GIT_INDEXCAP_NO_SYMLINKS = 4, 142 GIT_INDEXCAP_FROM_OWNER = -1, 143 } git_indexcap_t; 144 145 /** Callback for APIs that add/remove/update files matching pathspec */ 146 typedef int (*git_index_matched_path_cb)( 147 const char *path, const char *matched_pathspec, void *payload); 148 149 /** Flags for APIs that add files matching pathspec */ 150 typedef enum { 151 GIT_INDEX_ADD_DEFAULT = 0, 152 GIT_INDEX_ADD_FORCE = (1u << 0), 153 GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH = (1u << 1), 154 GIT_INDEX_ADD_CHECK_PATHSPEC = (1u << 2), 155 } git_index_add_option_t; 156 157 typedef enum { 158 /** 159 * Match any index stage. 160 * 161 * Some index APIs take a stage to match; pass this value to match 162 * any entry matching the path regardless of stage. 163 */ 164 GIT_INDEX_STAGE_ANY = -1, 165 166 /** A normal staged file in the index. */ 167 GIT_INDEX_STAGE_NORMAL = 0, 168 169 /** The ancestor side of a conflict. */ 170 GIT_INDEX_STAGE_ANCESTOR = 1, 171 172 /** The "ours" side of a conflict. */ 173 GIT_INDEX_STAGE_OURS = 2, 174 175 /** The "theirs" side of a conflict. */ 176 GIT_INDEX_STAGE_THEIRS = 3, 177 } git_index_stage_t; 178 179 /** @name Index File Functions 180 * 181 * These functions work on the index file itself. 182 */ 183 /**@{*/ 184 185 /** 186 * Create a new bare Git index object as a memory representation 187 * of the Git index file in 'index_path', without a repository 188 * to back it. 189 * 190 * Since there is no ODB or working directory behind this index, 191 * any Index methods which rely on these (e.g. index_add_bypath) 192 * will fail with the GIT_ERROR error code. 193 * 194 * If you need to access the index of an actual repository, 195 * use the `git_repository_index` wrapper. 196 * 197 * The index must be freed once it's no longer in use. 198 * 199 * @param out the pointer for the new index 200 * @param index_path the path to the index file in disk 201 * @return 0 or an error code 202 */ 203 GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path); 204 205 /** 206 * Create an in-memory index object. 207 * 208 * This index object cannot be read/written to the filesystem, 209 * but may be used to perform in-memory index operations. 210 * 211 * The index must be freed once it's no longer in use. 212 * 213 * @param out the pointer for the new index 214 * @return 0 or an error code 215 */ 216 GIT_EXTERN(int) git_index_new(git_index **out); 217 218 /** 219 * Free an existing index object. 220 * 221 * @param index an existing index object 222 */ 223 GIT_EXTERN(void) git_index_free(git_index *index); 224 225 /** 226 * Get the repository this index relates to 227 * 228 * @param index The index 229 * @return A pointer to the repository 230 */ 231 GIT_EXTERN(git_repository *) git_index_owner(const git_index *index); 232 233 /** 234 * Read index capabilities flags. 235 * 236 * @param index An existing index object 237 * @return A combination of GIT_INDEXCAP values 238 */ 239 GIT_EXTERN(int) git_index_caps(const git_index *index); 240 241 /** 242 * Set index capabilities flags. 243 * 244 * If you pass `GIT_INDEXCAP_FROM_OWNER` for the caps, then the 245 * capabilities will be read from the config of the owner object, 246 * looking at `core.ignorecase`, `core.filemode`, `core.symlinks`. 247 * 248 * @param index An existing index object 249 * @param caps A combination of GIT_INDEXCAP values 250 * @return 0 on success, -1 on failure 251 */ 252 GIT_EXTERN(int) git_index_set_caps(git_index *index, int caps); 253 254 /** 255 * Get index on-disk version. 256 * 257 * Valid return values are 2, 3, or 4. If 3 is returned, an index 258 * with version 2 may be written instead, if the extension data in 259 * version 3 is not necessary. 260 * 261 * @param index An existing index object 262 * @return the index version 263 */ 264 GIT_EXTERN(unsigned int) git_index_version(git_index *index); 265 266 /** 267 * Set index on-disk version. 268 * 269 * Valid values are 2, 3, or 4. If 2 is given, git_index_write may 270 * write an index with version 3 instead, if necessary to accurately 271 * represent the index. 272 * 273 * @param index An existing index object 274 * @param version The new version number 275 * @return 0 on success, -1 on failure 276 */ 277 GIT_EXTERN(int) git_index_set_version(git_index *index, unsigned int version); 278 279 /** 280 * Update the contents of an existing index object in memory by reading 281 * from the hard disk. 282 * 283 * If `force` is true, this performs a "hard" read that discards in-memory 284 * changes and always reloads the on-disk index data. If there is no 285 * on-disk version, the index will be cleared. 286 * 287 * If `force` is false, this does a "soft" read that reloads the index 288 * data from disk only if it has changed since the last time it was 289 * loaded. Purely in-memory index data will be untouched. Be aware: if 290 * there are changes on disk, unwritten in-memory changes are discarded. 291 * 292 * @param index an existing index object 293 * @param force if true, always reload, vs. only read if file has changed 294 * @return 0 or an error code 295 */ 296 GIT_EXTERN(int) git_index_read(git_index *index, int force); 297 298 /** 299 * Write an existing index object from memory back to disk 300 * using an atomic file lock. 301 * 302 * @param index an existing index object 303 * @return 0 or an error code 304 */ 305 GIT_EXTERN(int) git_index_write(git_index *index); 306 307 /** 308 * Get the full path to the index file on disk. 309 * 310 * @param index an existing index object 311 * @return path to index file or NULL for in-memory index 312 */ 313 GIT_EXTERN(const char *) git_index_path(const git_index *index); 314 315 /** 316 * Get the checksum of the index 317 * 318 * This checksum is the SHA-1 hash over the index file (except the 319 * last 20 bytes which are the checksum itself). In cases where the 320 * index does not exist on-disk, it will be zeroed out. 321 * 322 * @param index an existing index object 323 * @return a pointer to the checksum of the index 324 */ 325 GIT_EXTERN(const git_oid *) git_index_checksum(git_index *index); 326 327 /** 328 * Read a tree into the index file with stats 329 * 330 * The current index contents will be replaced by the specified tree. 331 * 332 * @param index an existing index object 333 * @param tree tree to read 334 * @return 0 or an error code 335 */ 336 GIT_EXTERN(int) git_index_read_tree(git_index *index, const git_tree *tree); 337 338 /** 339 * Write the index as a tree 340 * 341 * This method will scan the index and write a representation 342 * of its current state back to disk; it recursively creates 343 * tree objects for each of the subtrees stored in the index, 344 * but only returns the OID of the root tree. This is the OID 345 * that can be used e.g. to create a commit. 346 * 347 * The index instance cannot be bare, and needs to be associated 348 * to an existing repository. 349 * 350 * The index must not contain any file in conflict. 351 * 352 * @param out Pointer where to store the OID of the written tree 353 * @param index Index to write 354 * @return 0 on success, GIT_EUNMERGED when the index is not clean 355 * or an error code 356 */ 357 GIT_EXTERN(int) git_index_write_tree(git_oid *out, git_index *index); 358 359 /** 360 * Write the index as a tree to the given repository 361 * 362 * This method will do the same as `git_index_write_tree`, but 363 * letting the user choose the repository where the tree will 364 * be written. 365 * 366 * The index must not contain any file in conflict. 367 * 368 * @param out Pointer where to store OID of the the written tree 369 * @param index Index to write 370 * @param repo Repository where to write the tree 371 * @return 0 on success, GIT_EUNMERGED when the index is not clean 372 * or an error code 373 */ 374 GIT_EXTERN(int) git_index_write_tree_to(git_oid *out, git_index *index, git_repository *repo); 375 376 /**@}*/ 377 378 /** @name Raw Index Entry Functions 379 * 380 * These functions work on index entries, and allow for raw manipulation 381 * of the entries. 382 */ 383 /**@{*/ 384 385 /* Index entry manipulation */ 386 387 /** 388 * Get the count of entries currently in the index 389 * 390 * @param index an existing index object 391 * @return integer of count of current entries 392 */ 393 GIT_EXTERN(size_t) git_index_entrycount(const git_index *index); 394 395 /** 396 * Clear the contents (all the entries) of an index object. 397 * 398 * This clears the index object in memory; changes must be explicitly 399 * written to disk for them to take effect persistently. 400 * 401 * @param index an existing index object 402 * @return 0 on success, error code < 0 on failure 403 */ 404 GIT_EXTERN(int) git_index_clear(git_index *index); 405 406 /** 407 * Get a pointer to one of the entries in the index 408 * 409 * The entry is not modifiable and should not be freed. Because the 410 * `git_index_entry` struct is a publicly defined struct, you should 411 * be able to make your own permanent copy of the data if necessary. 412 * 413 * @param index an existing index object 414 * @param n the position of the entry 415 * @return a pointer to the entry; NULL if out of bounds 416 */ 417 GIT_EXTERN(const git_index_entry *) git_index_get_byindex( 418 git_index *index, size_t n); 419 420 /** 421 * Get a pointer to one of the entries in the index 422 * 423 * The entry is not modifiable and should not be freed. Because the 424 * `git_index_entry` struct is a publicly defined struct, you should 425 * be able to make your own permanent copy of the data if necessary. 426 * 427 * @param index an existing index object 428 * @param path path to search 429 * @param stage stage to search 430 * @return a pointer to the entry; NULL if it was not found 431 */ 432 GIT_EXTERN(const git_index_entry *) git_index_get_bypath( 433 git_index *index, const char *path, int stage); 434 435 /** 436 * Remove an entry from the index 437 * 438 * @param index an existing index object 439 * @param path path to search 440 * @param stage stage to search 441 * @return 0 or an error code 442 */ 443 GIT_EXTERN(int) git_index_remove(git_index *index, const char *path, int stage); 444 445 /** 446 * Remove all entries from the index under a given directory 447 * 448 * @param index an existing index object 449 * @param dir container directory path 450 * @param stage stage to search 451 * @return 0 or an error code 452 */ 453 GIT_EXTERN(int) git_index_remove_directory( 454 git_index *index, const char *dir, int stage); 455 456 /** 457 * Add or update an index entry from an in-memory struct 458 * 459 * If a previous index entry exists that has the same path and stage 460 * as the given 'source_entry', it will be replaced. Otherwise, the 461 * 'source_entry' will be added. 462 * 463 * A full copy (including the 'path' string) of the given 464 * 'source_entry' will be inserted on the index. 465 * 466 * @param index an existing index object 467 * @param source_entry new entry object 468 * @return 0 or an error code 469 */ 470 GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_entry); 471 472 /** 473 * Return the stage number from a git index entry 474 * 475 * This entry is calculated from the entry's flag attribute like this: 476 * 477 * (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT 478 * 479 * @param entry The entry 480 * @return the stage number 481 */ 482 GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry); 483 484 /** 485 * Return whether the given index entry is a conflict (has a high stage 486 * entry). This is simply shorthand for `git_index_entry_stage > 0`. 487 * 488 * @param entry The entry 489 * @return 1 if the entry is a conflict entry, 0 otherwise 490 */ 491 GIT_EXTERN(int) git_index_entry_is_conflict(const git_index_entry *entry); 492 493 /**@}*/ 494 495 /** @name Workdir Index Entry Functions 496 * 497 * These functions work on index entries specifically in the working 498 * directory (ie, stage 0). 499 */ 500 /**@{*/ 501 502 /** 503 * Add or update an index entry from a file on disk 504 * 505 * The file `path` must be relative to the repository's 506 * working folder and must be readable. 507 * 508 * This method will fail in bare index instances. 509 * 510 * This forces the file to be added to the index, not looking 511 * at gitignore rules. Those rules can be evaluated through 512 * the git_status APIs (in status.h) before calling this. 513 * 514 * If this file currently is the result of a merge conflict, this 515 * file will no longer be marked as conflicting. The data about 516 * the conflict will be moved to the "resolve undo" (REUC) section. 517 * 518 * @param index an existing index object 519 * @param path filename to add 520 * @return 0 or an error code 521 */ 522 GIT_EXTERN(int) git_index_add_bypath(git_index *index, const char *path); 523 524 /** 525 * Add or update an index entry from a buffer in memory 526 * 527 * This method will create a blob in the repository that owns the 528 * index and then add the index entry to the index. The `path` of the 529 * entry represents the position of the blob relative to the 530 * repository's root folder. 531 * 532 * If a previous index entry exists that has the same path as the 533 * given 'entry', it will be replaced. Otherwise, the 'entry' will be 534 * added. The `id` and the `file_size` of the 'entry' are updated with the 535 * real value of the blob. 536 * 537 * This forces the file to be added to the index, not looking 538 * at gitignore rules. Those rules can be evaluated through 539 * the git_status APIs (in status.h) before calling this. 540 * 541 * If this file currently is the result of a merge conflict, this 542 * file will no longer be marked as conflicting. The data about 543 * the conflict will be moved to the "resolve undo" (REUC) section. 544 * 545 * @param index an existing index object 546 * @param entry filename to add 547 * @param buffer data to be written into the blob 548 * @param len length of the data 549 * @return 0 or an error code 550 */ 551 GIT_EXTERN(int) git_index_add_frombuffer( 552 git_index *index, 553 const git_index_entry *entry, 554 const void *buffer, size_t len); 555 556 /** 557 * Remove an index entry corresponding to a file on disk 558 * 559 * The file `path` must be relative to the repository's 560 * working folder. It may exist. 561 * 562 * If this file currently is the result of a merge conflict, this 563 * file will no longer be marked as conflicting. The data about 564 * the conflict will be moved to the "resolve undo" (REUC) section. 565 * 566 * @param index an existing index object 567 * @param path filename to remove 568 * @return 0 or an error code 569 */ 570 GIT_EXTERN(int) git_index_remove_bypath(git_index *index, const char *path); 571 572 /** 573 * Add or update index entries matching files in the working directory. 574 * 575 * This method will fail in bare index instances. 576 * 577 * The `pathspec` is a list of file names or shell glob patterns that will 578 * be matched against files in the repository's working directory. Each 579 * file that matches will be added to the index (either updating an 580 * existing entry or adding a new entry). You can disable glob expansion 581 * and force exact matching with the `GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH` 582 * flag. 583 * 584 * Files that are ignored will be skipped (unlike `git_index_add_bypath`). 585 * If a file is already tracked in the index, then it *will* be updated 586 * even if it is ignored. Pass the `GIT_INDEX_ADD_FORCE` flag to skip 587 * the checking of ignore rules. 588 * 589 * To emulate `git add -A` and generate an error if the pathspec contains 590 * the exact path of an ignored file (when not using FORCE), add the 591 * `GIT_INDEX_ADD_CHECK_PATHSPEC` flag. This checks that each entry 592 * in the `pathspec` that is an exact match to a filename on disk is 593 * either not ignored or already in the index. If this check fails, the 594 * function will return GIT_EINVALIDSPEC. 595 * 596 * To emulate `git add -A` with the "dry-run" option, just use a callback 597 * function that always returns a positive value. See below for details. 598 * 599 * If any files are currently the result of a merge conflict, those files 600 * will no longer be marked as conflicting. The data about the conflicts 601 * will be moved to the "resolve undo" (REUC) section. 602 * 603 * If you provide a callback function, it will be invoked on each matching 604 * item in the working directory immediately *before* it is added to / 605 * updated in the index. Returning zero will add the item to the index, 606 * greater than zero will skip the item, and less than zero will abort the 607 * scan and return that value to the caller. 608 * 609 * @param index an existing index object 610 * @param pathspec array of path patterns 611 * @param flags combination of git_index_add_option_t flags 612 * @param callback notification callback for each added/updated path (also 613 * gets index of matching pathspec entry); can be NULL; 614 * return 0 to add, >0 to skip, <0 to abort scan. 615 * @param payload payload passed through to callback function 616 * @return 0 on success, negative callback return value, or error code 617 */ 618 GIT_EXTERN(int) git_index_add_all( 619 git_index *index, 620 const git_strarray *pathspec, 621 unsigned int flags, 622 git_index_matched_path_cb callback, 623 void *payload); 624 625 /** 626 * Remove all matching index entries. 627 * 628 * If you provide a callback function, it will be invoked on each matching 629 * item in the index immediately *before* it is removed. Return 0 to 630 * remove the item, > 0 to skip the item, and < 0 to abort the scan. 631 * 632 * @param index An existing index object 633 * @param pathspec array of path patterns 634 * @param callback notification callback for each removed path (also 635 * gets index of matching pathspec entry); can be NULL; 636 * return 0 to add, >0 to skip, <0 to abort scan. 637 * @param payload payload passed through to callback function 638 * @return 0 on success, negative callback return value, or error code 639 */ 640 GIT_EXTERN(int) git_index_remove_all( 641 git_index *index, 642 const git_strarray *pathspec, 643 git_index_matched_path_cb callback, 644 void *payload); 645 646 /** 647 * Update all index entries to match the working directory 648 * 649 * This method will fail in bare index instances. 650 * 651 * This scans the existing index entries and synchronizes them with the 652 * working directory, deleting them if the corresponding working directory 653 * file no longer exists otherwise updating the information (including 654 * adding the latest version of file to the ODB if needed). 655 * 656 * If you provide a callback function, it will be invoked on each matching 657 * item in the index immediately *before* it is updated (either refreshed 658 * or removed depending on working directory state). Return 0 to proceed 659 * with updating the item, > 0 to skip the item, and < 0 to abort the scan. 660 * 661 * @param index An existing index object 662 * @param pathspec array of path patterns 663 * @param callback notification callback for each updated path (also 664 * gets index of matching pathspec entry); can be NULL; 665 * return 0 to add, >0 to skip, <0 to abort scan. 666 * @param payload payload passed through to callback function 667 * @return 0 on success, negative callback return value, or error code 668 */ 669 GIT_EXTERN(int) git_index_update_all( 670 git_index *index, 671 const git_strarray *pathspec, 672 git_index_matched_path_cb callback, 673 void *payload); 674 675 /** 676 * Find the first position of any entries which point to given 677 * path in the Git index. 678 * 679 * @param at_pos the address to which the position of the index entry is written (optional) 680 * @param index an existing index object 681 * @param path path to search 682 * @return a zero-based position in the index if found; GIT_ENOTFOUND otherwise 683 */ 684 GIT_EXTERN(int) git_index_find(size_t *at_pos, git_index *index, const char *path); 685 686 /** 687 * Find the first position of any entries matching a prefix. To find the first position 688 * of a path inside a given folder, suffix the prefix with a '/'. 689 * 690 * @param at_pos the address to which the position of the index entry is written (optional) 691 * @param index an existing index object 692 * @param prefix the prefix to search for 693 * @return 0 with valid value in at_pos; an error code otherwise 694 */ 695 GIT_EXTERN(int) git_index_find_prefix(size_t *at_pos, git_index *index, const char *prefix); 696 697 /**@}*/ 698 699 /** @name Conflict Index Entry Functions 700 * 701 * These functions work on conflict index entries specifically (ie, stages 1-3) 702 */ 703 /**@{*/ 704 705 /** 706 * Add or update index entries to represent a conflict. Any staged 707 * entries that exist at the given paths will be removed. 708 * 709 * The entries are the entries from the tree included in the merge. Any 710 * entry may be null to indicate that that file was not present in the 711 * trees during the merge. For example, ancestor_entry may be NULL to 712 * indicate that a file was added in both branches and must be resolved. 713 * 714 * @param index an existing index object 715 * @param ancestor_entry the entry data for the ancestor of the conflict 716 * @param our_entry the entry data for our side of the merge conflict 717 * @param their_entry the entry data for their side of the merge conflict 718 * @return 0 or an error code 719 */ 720 GIT_EXTERN(int) git_index_conflict_add( 721 git_index *index, 722 const git_index_entry *ancestor_entry, 723 const git_index_entry *our_entry, 724 const git_index_entry *their_entry); 725 726 /** 727 * Get the index entries that represent a conflict of a single file. 728 * 729 * The entries are not modifiable and should not be freed. Because the 730 * `git_index_entry` struct is a publicly defined struct, you should 731 * be able to make your own permanent copy of the data if necessary. 732 * 733 * @param ancestor_out Pointer to store the ancestor entry 734 * @param our_out Pointer to store the our entry 735 * @param their_out Pointer to store the their entry 736 * @param index an existing index object 737 * @param path path to search 738 * @return 0 or an error code 739 */ 740 GIT_EXTERN(int) git_index_conflict_get( 741 const git_index_entry **ancestor_out, 742 const git_index_entry **our_out, 743 const git_index_entry **their_out, 744 git_index *index, 745 const char *path); 746 747 /** 748 * Removes the index entries that represent a conflict of a single file. 749 * 750 * @param index an existing index object 751 * @param path path to remove conflicts for 752 * @return 0 or an error code 753 */ 754 GIT_EXTERN(int) git_index_conflict_remove(git_index *index, const char *path); 755 756 /** 757 * Remove all conflicts in the index (entries with a stage greater than 0). 758 * 759 * @param index an existing index object 760 * @return 0 or an error code 761 */ 762 GIT_EXTERN(int) git_index_conflict_cleanup(git_index *index); 763 764 /** 765 * Determine if the index contains entries representing file conflicts. 766 * 767 * @return 1 if at least one conflict is found, 0 otherwise. 768 */ 769 GIT_EXTERN(int) git_index_has_conflicts(const git_index *index); 770 771 /** 772 * Create an iterator for the conflicts in the index. 773 * 774 * The index must not be modified while iterating; the results are undefined. 775 * 776 * @param iterator_out The newly created conflict iterator 777 * @param index The index to scan 778 * @return 0 or an error code 779 */ 780 GIT_EXTERN(int) git_index_conflict_iterator_new( 781 git_index_conflict_iterator **iterator_out, 782 git_index *index); 783 784 /** 785 * Returns the current conflict (ancestor, ours and theirs entry) and 786 * advance the iterator internally to the next value. 787 * 788 * @param ancestor_out Pointer to store the ancestor side of the conflict 789 * @param our_out Pointer to store our side of the conflict 790 * @param their_out Pointer to store their side of the conflict 791 * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code 792 * (negative value) 793 */ 794 GIT_EXTERN(int) git_index_conflict_next( 795 const git_index_entry **ancestor_out, 796 const git_index_entry **our_out, 797 const git_index_entry **their_out, 798 git_index_conflict_iterator *iterator); 799 800 /** 801 * Frees a `git_index_conflict_iterator`. 802 * 803 * @param iterator pointer to the iterator 804 */ 805 GIT_EXTERN(void) git_index_conflict_iterator_free( 806 git_index_conflict_iterator *iterator); 807 808 /**@}*/ 809 810 /** @} */ 811 GIT_END_DECL 812 #endif 813