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 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. The `id` and the `file_size` of the 'entry' are updated with the 559 * real value of the blob. 560 * 561 * This forces the file to be added to the index, not looking 562 * at gitignore rules. Those rules can be evaluated through 563 * the git_status APIs (in status.h) before calling this. 564 * 565 * If this file currently is the result of a merge conflict, this 566 * file will no longer be marked as conflicting. The data about 567 * the conflict will be moved to the "resolve undo" (REUC) section. 568 * 569 * @param index an existing index object 570 * @param entry filename to add 571 * @param buffer data to be written into the blob 572 * @param len length of the data 573 * @return 0 or an error code 574 */ 575 GIT_EXTERN(int) git_index_add_from_buffer( 576 git_index *index, 577 const git_index_entry *entry, 578 const void *buffer, size_t len); 579 580 /** 581 * Remove an index entry corresponding to a file on disk 582 * 583 * The file `path` must be relative to the repository's 584 * working folder. It may exist. 585 * 586 * If this file currently is the result of a merge conflict, this 587 * file will no longer be marked as conflicting. The data about 588 * the conflict will be moved to the "resolve undo" (REUC) section. 589 * 590 * @param index an existing index object 591 * @param path filename to remove 592 * @return 0 or an error code 593 */ 594 GIT_EXTERN(int) git_index_remove_bypath(git_index *index, const char *path); 595 596 /** 597 * Add or update index entries matching files in the working directory. 598 * 599 * This method will fail in bare index instances. 600 * 601 * The `pathspec` is a list of file names or shell glob patterns that will 602 * be matched against files in the repository's working directory. Each 603 * file that matches will be added to the index (either updating an 604 * existing entry or adding a new entry). You can disable glob expansion 605 * and force exact matching with the `GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH` 606 * flag. 607 * 608 * Files that are ignored will be skipped (unlike `git_index_add_bypath`). 609 * If a file is already tracked in the index, then it *will* be updated 610 * even if it is ignored. Pass the `GIT_INDEX_ADD_FORCE` flag to skip 611 * the checking of ignore rules. 612 * 613 * To emulate `git add -A` and generate an error if the pathspec contains 614 * the exact path of an ignored file (when not using FORCE), add the 615 * `GIT_INDEX_ADD_CHECK_PATHSPEC` flag. This checks that each entry 616 * in the `pathspec` that is an exact match to a filename on disk is 617 * either not ignored or already in the index. If this check fails, the 618 * function will return GIT_EINVALIDSPEC. 619 * 620 * To emulate `git add -A` with the "dry-run" option, just use a callback 621 * function that always returns a positive value. See below for details. 622 * 623 * If any files are currently the result of a merge conflict, those files 624 * will no longer be marked as conflicting. The data about the conflicts 625 * will be moved to the "resolve undo" (REUC) section. 626 * 627 * If you provide a callback function, it will be invoked on each matching 628 * item in the working directory immediately *before* it is added to / 629 * updated in the index. Returning zero will add the item to the index, 630 * greater than zero will skip the item, and less than zero will abort the 631 * scan and return that value to the caller. 632 * 633 * @param index an existing index object 634 * @param pathspec array of path patterns 635 * @param flags combination of git_index_add_option_t flags 636 * @param callback notification callback for each added/updated path (also 637 * gets index of matching pathspec entry); can be NULL; 638 * return 0 to add, >0 to skip, <0 to abort scan. 639 * @param payload payload passed through to callback function 640 * @return 0 on success, negative callback return value, or error code 641 */ 642 GIT_EXTERN(int) git_index_add_all( 643 git_index *index, 644 const git_strarray *pathspec, 645 unsigned int flags, 646 git_index_matched_path_cb callback, 647 void *payload); 648 649 /** 650 * Remove all matching index entries. 651 * 652 * If you provide a callback function, it will be invoked on each matching 653 * item in the index immediately *before* it is removed. Return 0 to 654 * remove the item, > 0 to skip the item, and < 0 to abort the scan. 655 * 656 * @param index An existing index object 657 * @param pathspec array of path patterns 658 * @param callback notification callback for each removed path (also 659 * gets index of matching pathspec entry); can be NULL; 660 * return 0 to add, >0 to skip, <0 to abort scan. 661 * @param payload payload passed through to callback function 662 * @return 0 on success, negative callback return value, or error code 663 */ 664 GIT_EXTERN(int) git_index_remove_all( 665 git_index *index, 666 const git_strarray *pathspec, 667 git_index_matched_path_cb callback, 668 void *payload); 669 670 /** 671 * Update all index entries to match the working directory 672 * 673 * This method will fail in bare index instances. 674 * 675 * This scans the existing index entries and synchronizes them with the 676 * working directory, deleting them if the corresponding working directory 677 * file no longer exists otherwise updating the information (including 678 * adding the latest version of file to the ODB if needed). 679 * 680 * If you provide a callback function, it will be invoked on each matching 681 * item in the index immediately *before* it is updated (either refreshed 682 * or removed depending on working directory state). Return 0 to proceed 683 * with updating the item, > 0 to skip the item, and < 0 to abort the scan. 684 * 685 * @param index An existing index object 686 * @param pathspec array of path patterns 687 * @param callback notification callback for each updated path (also 688 * gets index of matching pathspec entry); can be NULL; 689 * return 0 to add, >0 to skip, <0 to abort scan. 690 * @param payload payload passed through to callback function 691 * @return 0 on success, negative callback return value, or error code 692 */ 693 GIT_EXTERN(int) git_index_update_all( 694 git_index *index, 695 const git_strarray *pathspec, 696 git_index_matched_path_cb callback, 697 void *payload); 698 699 /** 700 * Find the first position of any entries which point to given 701 * path in the Git index. 702 * 703 * @param at_pos the address to which the position of the index entry is written (optional) 704 * @param index an existing index object 705 * @param path path to search 706 * @return a zero-based position in the index if found; GIT_ENOTFOUND otherwise 707 */ 708 GIT_EXTERN(int) git_index_find(size_t *at_pos, git_index *index, const char *path); 709 710 /** 711 * Find the first position of any entries matching a prefix. To find the first position 712 * of a path inside a given folder, suffix the prefix with a '/'. 713 * 714 * @param at_pos the address to which the position of the index entry is written (optional) 715 * @param index an existing index object 716 * @param prefix the prefix to search for 717 * @return 0 with valid value in at_pos; an error code otherwise 718 */ 719 GIT_EXTERN(int) git_index_find_prefix(size_t *at_pos, git_index *index, const char *prefix); 720 721 /**@}*/ 722 723 /** @name Conflict Index Entry Functions 724 * 725 * These functions work on conflict index entries specifically (ie, stages 1-3) 726 */ 727 /**@{*/ 728 729 /** 730 * Add or update index entries to represent a conflict. Any staged 731 * entries that exist at the given paths will be removed. 732 * 733 * The entries are the entries from the tree included in the merge. Any 734 * entry may be null to indicate that that file was not present in the 735 * trees during the merge. For example, ancestor_entry may be NULL to 736 * indicate that a file was added in both branches and must be resolved. 737 * 738 * @param index an existing index object 739 * @param ancestor_entry the entry data for the ancestor of the conflict 740 * @param our_entry the entry data for our side of the merge conflict 741 * @param their_entry the entry data for their side of the merge conflict 742 * @return 0 or an error code 743 */ 744 GIT_EXTERN(int) git_index_conflict_add( 745 git_index *index, 746 const git_index_entry *ancestor_entry, 747 const git_index_entry *our_entry, 748 const git_index_entry *their_entry); 749 750 /** 751 * Get the index entries that represent a conflict of a single file. 752 * 753 * The entries are not modifiable and should not be freed. Because the 754 * `git_index_entry` struct is a publicly defined struct, you should 755 * be able to make your own permanent copy of the data if necessary. 756 * 757 * @param ancestor_out Pointer to store the ancestor entry 758 * @param our_out Pointer to store the our entry 759 * @param their_out Pointer to store the their entry 760 * @param index an existing index object 761 * @param path path to search 762 * @return 0 or an error code 763 */ 764 GIT_EXTERN(int) git_index_conflict_get( 765 const git_index_entry **ancestor_out, 766 const git_index_entry **our_out, 767 const git_index_entry **their_out, 768 git_index *index, 769 const char *path); 770 771 /** 772 * Removes the index entries that represent a conflict of a single file. 773 * 774 * @param index an existing index object 775 * @param path path to remove conflicts for 776 * @return 0 or an error code 777 */ 778 GIT_EXTERN(int) git_index_conflict_remove(git_index *index, const char *path); 779 780 /** 781 * Remove all conflicts in the index (entries with a stage greater than 0). 782 * 783 * @param index an existing index object 784 * @return 0 or an error code 785 */ 786 GIT_EXTERN(int) git_index_conflict_cleanup(git_index *index); 787 788 /** 789 * Determine if the index contains entries representing file conflicts. 790 * 791 * @return 1 if at least one conflict is found, 0 otherwise. 792 */ 793 GIT_EXTERN(int) git_index_has_conflicts(const git_index *index); 794 795 /** 796 * Create an iterator for the conflicts in the index. 797 * 798 * The index must not be modified while iterating; the results are undefined. 799 * 800 * @param iterator_out The newly created conflict iterator 801 * @param index The index to scan 802 * @return 0 or an error code 803 */ 804 GIT_EXTERN(int) git_index_conflict_iterator_new( 805 git_index_conflict_iterator **iterator_out, 806 git_index *index); 807 808 /** 809 * Returns the current conflict (ancestor, ours and theirs entry) and 810 * advance the iterator internally to the next value. 811 * 812 * @param ancestor_out Pointer to store the ancestor side of the conflict 813 * @param our_out Pointer to store our side of the conflict 814 * @param their_out Pointer to store their side of the conflict 815 * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code 816 * (negative value) 817 */ 818 GIT_EXTERN(int) git_index_conflict_next( 819 const git_index_entry **ancestor_out, 820 const git_index_entry **our_out, 821 const git_index_entry **their_out, 822 git_index_conflict_iterator *iterator); 823 824 /** 825 * Frees a `git_index_conflict_iterator`. 826 * 827 * @param iterator pointer to the iterator 828 */ 829 GIT_EXTERN(void) git_index_conflict_iterator_free( 830 git_index_conflict_iterator *iterator); 831 832 /** @} */ 833 GIT_END_DECL 834 #endif 835