index: Refactor add/replace methods

Removed the optional `replace` argument, we now have 4 add methods:

	`git_index_add`: add or update from path
	`git_index_add2`: add or update from struct
	`git_index_append`: add without replacing from path
	`git_index_append2`: add without replacing from struct

Yes, this breaks the bindings.

1 files changed, 50 insertions, 10 deletions

diff --git a/include/git2/index.h b/include/git2/index.h
index adc4cb435..98a17a18c 100644
--- a/include/git2/index.h
+++ b/include/git2/index.h
@@ -182,7 +182,12 @@ GIT_EXTERN(int) git_index_write(git_index *index);
 GIT_EXTERN(int) git_index_find(git_index *index, const char *path);
 
 /**
- * Add or update an index entry from a file in disk.
+ * Add or update an index entry from a file in disk
+ *
+ * The file `path` must be relative to the repository's
+ * working folder and must be readable.
+ *
+ * This method will fail in bare index instances.
  *
  * @param index an existing index object
  * @param path filename to add
@@ -192,27 +197,62 @@ GIT_EXTERN(int) git_index_find(git_index *index, const char *path);
 GIT_EXTERN(int) git_index_add(git_index *index, const char *path, int stage);
 
 /**
- * Remove an entry from the index 
+ * Add or update an index entry from an in-memory struct
+ *
+ * A full copy (including the 'path' string) of the given
+ * 'source_entry' will be inserted on the index.
  *
  * @param index an existing index object
- * @param position position of the entry to remove
+ * @param source_entry new entry object
  * @return 0 on success, otherwise an error code
  */
-GIT_EXTERN(int) git_index_remove(git_index *index, int position);
+GIT_EXTERN(int) git_index_add2(git_index *index, const git_index_entry *source_entry);
 
 /**
- * Insert an entry into the index.
+ * Add (append) an index entry from a file in disk
+ *
+ * A new entry will always be inserted into the index;
+ * if the index already contains an entry for such
+ * path, the old entry will **not** be replaced.
+ *
+ * The file `path` must be relative to the repository's
+ * working folder and must be readable.
+ *
+ * This method will fail in bare index instances.
+ *
+ * @param index an existing index object
+ * @param path filename to add
+ * @param stage stage for the entry
+ * @return 0 on success, otherwise an error code
+ */
+GIT_EXTERN(int) git_index_append(git_index *index, const char *path, int stage);
+
+/**
+ * Add (append) an index entry from an in-memory struct
+ *
+ * A new entry will always be inserted into the index;
+ * if the index already contains an entry for the path
+ * in the `entry` struct, the old entry will **not** be
+ * replaced.
+ *
  * A full copy (including the 'path' string) of the given
- * 'source_entry' will be inserted on the index; if the
- * replace flag is not set and the index already contains
- * an entry for the same path, the entry will be updated.
+ * 'source_entry' will be inserted on the index.
  *
  * @param index an existing index object
  * @param source_entry new entry object
- * @param replace if set, existing entries will be replaced
  * @return 0 on success, otherwise an error code
  */
-GIT_EXTERN(int) git_index_insert(git_index *index, const git_index_entry *source_entry, int replace);
+GIT_EXTERN(int) git_index_apppend2(git_index *index, const git_index_entry *source_entry);
+
+/**
+ * Remove an entry from the index 
+ *
+ * @param index an existing index object
+ * @param position position of the entry to remove
+ * @return 0 on success, otherwise an error code
+ */
+GIT_EXTERN(int) git_index_remove(git_index *index, int position);
+
 
 /**
  * Get a pointer to one of the entries in the index