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