index: Change the memory management for repo indexes

The `git_repository_index` call now returns a brand new index that must
be manually free'd.

2 files changed, 21 insertions, 18 deletions

diff --git a/include/git2/index.h b/include/git2/index.h
index 57401a94c..45900d08d 100644
--- a/include/git2/index.h
+++ b/include/git2/index.h
@@ -109,29 +109,24 @@ typedef struct git_index_entry_unmerged {
 } git_index_entry_unmerged;
 
 /**
- * Create a new Git index object as a memory representation
+ * Create a new bare Git index object as a memory representation
  * of the Git index file in 'index_path', without a repository
  * to back it.
  *
- * Since there is no ODB behind this index, any Index methods
- * which rely on the ODB (e.g. index_add) will fail with the
- * GIT_EBAREINDEX error code.
+ * Since there is no ODB or working directory behind this index,
+ * any Index methods which rely on these (e.g. index_add) will
+ * fail with the GIT_EBAREINDEX error code.
  *
- * @param index the pointer for the new index
- * @param index_path the path to the index file in disk
- * @return 0 on success; error code otherwise
- */
-GIT_EXTERN(int) git_index_open_bare(git_index **index, const char *index_path);
-
-/**
- * Open the Index inside the git repository pointed
- * by 'repo'.
+ * If you need to access the index of an actual repository,
+ * use the `git_repository_index` wrapper.
+ *
+ * The index must be freed once it's no longer in use.
  *
  * @param index the pointer for the new index
- * @param repo the git repo which owns the index
+ * @param index_path the path to the index file in disk
  * @return 0 on success; error code otherwise
  */
-GIT_EXTERN(int) git_index_open_inrepo(git_index **index, git_repository *repo);
+GIT_EXTERN(int) git_index_open(git_index **index, const char *index_path);
 
 /**
  * Clear the contents (all the entries) of an index object.
diff --git a/include/git2/repository.h b/include/git2/repository.h
index c47fcfc9a..0d67ff8cc 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -141,10 +141,18 @@ GIT_EXTERN(int) git_repository_open3(git_repository **repository,
 GIT_EXTERN(git_odb *) git_repository_database(git_repository *repo);
 
 /**
- * Get the Index file of a Git repository
+ * Open the Index file of a Git repository
  *
- * This is a cheap operation; the index is only opened on the first call,
- * and subsequent calls only retrieve the previous pointer.
+ * This returns a new and unique `git_index` object representing the
+ * active index for the repository.
+ *
+ * This method may be called more than once (e.g. on different threads).
+ *
+ * Each returned `git_index` object is independent and suffers no race
+ * conditions: synchronization is done at the FS level.
+ *
+ * Each returned `git_index` object must be manually freed by the user,
+ * using `git_index_free`.
  *
  * @param index Pointer where to store the index
  * @param repo a repository object