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 /* @} */