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 a zero-based position in the index if found; GIT_ENOTFOUND otherwise
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 with valid value in at_pos; an error code otherwise
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