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