Add Repository#refreshIndex

`Repository#refreshIndex` will return an `Index` object back that has the latest data loaded off of disk. This removes the need for the `Repository#index` then `Index#read(1)` pattern that was being used which seemed to have some weird timing issues that could have wrong data loaded into the returned index. Calling this function also clears the `Index` that's cached in the `Repository` object.
2a5062389a292293552680be8f79f0fb2f053808
commit 2a5062389a292293552680be8f79f0fb2f053808
diff --git a/examples/add-and-commit.js b/examples/add-and-commit.js
@@ -35,11 +35,10 @@ nodegit.Repository.open(path.resolve(__dirname, "../.git"))
   );
 })
 .then(function() {
-  return repo.openIndex();
+  return repo.refreshIndex();
 })
 .then(function(indexResult) {
   index = indexResult;
-  return index.read(1);
 })
 .then(function() {
   // this file is in the root of the directory and doesn't need a full path

diff --git a/examples/create-new-repo.js b/examples/create-new-repo.js
@@ -20,11 +20,10 @@ fse.ensureDir(path.resolve(__dirname, repoDir))
   return fse.writeFile(path.join(repository.workdir(), fileName), fileContent);
 })
 .then(function(){
-  return repository.openIndex();
+  return repository.refreshIndex();
 })
 .then(function(idx) {
   index = idx;
-  return index.read(1);
 })
 .then(function() {
   return index.addByPath(fileName);

diff --git a/examples/details-for-tree-entry.js b/examples/details-for-tree-entry.js
@@ -13,7 +13,7 @@ nodegit.Repository.open(path.resolve(__dirname, "../.git"))
 
       // Tree entry doesn't have any data associated with the actual entry
       // To get that we need to get the index entry that this points to
-      return repo.openIndex().then(function(index) {
+      return repo.refreshIndex().then(function(index) {
         var indexEntry = index.getByPath(treeEntry.path());
 
         // With the index entry we can now view the details for the tree entry

diff --git a/examples/general.js b/examples/general.js
@@ -319,7 +319,7 @@ nodegit.Repository.open(path.resolve(__dirname, "../.git"))
 
     // The [index file API][gi] allows you to read, traverse, update and write
     // the Git index file (sometimes thought of as the staging area).
-    return repo.openIndex();
+    return repo.refreshIndex();
   })
 
   .then(function(index) {

diff --git a/examples/index-add-and-remove.js b/examples/index-add-and-remove.js
@@ -5,7 +5,7 @@ var fse = promisify(require("fs-extra"));
 
 nodegit.Repository.open(path.resolve(__dirname, "../.git"))
   .then(function(repo) {
-    return repo.openIndex()
+    return repo.refreshIndex()
     .then(function(index) {
       var fileContent = {
         newFile1: "this has some content",

diff --git a/examples/merge-cleanly.js b/examples/merge-cleanly.js
@@ -43,10 +43,9 @@ fse.remove(path.resolve(__dirname, repoDir))
 
 // Load up the repository index and make our initial commit to HEAD
 .then(function() {
-  return repository.openIndex();
+  return repository.refreshIndex();
 })
 .then(function(index) {
-  index.read(1);
   index.addByPath(ourFileName);
   index.write();
 
@@ -79,10 +78,9 @@ fse.remove(path.resolve(__dirname, repoDir))
   );
 })
 .then(function() {
-  return repository.openIndex();
+  return repository.refreshIndex();
 })
 .then(function(index) {
-  index.read(1);
   index.addByPath(theirFileName);
   index.write();
 

diff --git a/examples/merge-with-conflicts.js b/examples/merge-with-conflicts.js
@@ -49,10 +49,9 @@ fse.remove(path.resolve(__dirname, repoDir))
 
 // Load up the repository index and make our initial commit to HEAD
 .then(function() {
-  return repository.openIndex();
+  return repository.refreshIndex();
 })
 .then(function(index) {
-  index.read(1);
   index.addByPath(fileName);
   index.write();
 
@@ -94,9 +93,8 @@ fse.remove(path.resolve(__dirname, repoDir))
   );
 })
 .then(function() {
-  return repository.openIndex()
+  return repository.refreshIndex()
     .then(function(index) {
-      index.read(1);
       index.addByPath(fileName);
       index.write();
 
@@ -122,8 +120,7 @@ fse.remove(path.resolve(__dirname, repoDir))
   );
 })
 .then(function() {
-  return repository.openIndex().then(function(index) {
-    index.read(1);
+  return repository.refreshIndex().then(function(index) {
     index.addByPath(fileName);
     index.write();
 
@@ -173,9 +170,8 @@ fse.remove(path.resolve(__dirname, repoDir))
 // we need to get a new index as the other one isnt backed to
 // the repository in the usual fashion, and just behaves weirdly
 .then(function() {
-  return repository.openIndex().then(function(index) {
+  return repository.refreshIndex().then(function(index) {
 
-    index.read(1);
     index.addByPath(fileName);
     index.write();
 

diff --git a/examples/push.js b/examples/push.js
@@ -30,10 +30,9 @@ fse.remove(path.resolve(__dirname, repoDir))
 
 // Load up the repository index and make our initial commit to HEAD
 .then(function() {
-  return repository.openIndex();
+  return repository.refreshIndex();
 })
 .then(function(index) {
-  index.read(1);
   index.addByPath(fileName);
   index.write();
 

diff --git a/examples/remove-and-commit.js b/examples/remove-and-commit.js
@@ -17,11 +17,10 @@ var _oid;
 nodegit.Repository.open(path.resolve(__dirname, "../.git"))
   .then(function(repo) {
     _repository = repo;
-    return repo.openIndex();
+    return repo.refreshIndex();
   })
   .then(function(index){
     _index = index;
-    return _index.read();
   })
   .then(function() {
     //remove the file from the index...

diff --git a/generate/input/descriptor.json b/generate/input/descriptor.json
@@ -1833,7 +1833,11 @@
           }
         },
         "git_repository_set_index": {
-          "ignore": true
+          "args": {
+            "index": {
+              "isOptional": true
+            }
+          }
         },
         "git_repository_set_odb": {
           "ignore": true

diff --git a/lib/repository.js b/lib/repository.js
@@ -23,6 +23,27 @@ Object.defineProperty(Repository.prototype, "openIndex", {
   enumerable: false,
   value: Repository.prototype.index
 });
+/**
+ * Grabs a fresh copy of the index from the repository. Invalidates
+ * all previously grabbed indexes
+ *
+ * @async
+ * @return {Index}
+ */
+Repository.prototype.refreshIndex = function(callback) {
+  var repo = this;
+
+  repo.setIndex(); // clear the index
+
+  return repo.index()
+    .then(function(index) {
+      if (typeof callback === "function") {
+        callback(null, index);
+      }
+
+      return index;
+    }, callback);
+};
 
 /**
  * Creates a branch with the passed in name pointing to the commit
@@ -521,10 +542,9 @@ Repository.prototype.createCommitOnHead = function(
   var index;
   var repo = this;
 
-  return repo.openIndex()
+  return repo.refreshIndex()
     .then(function(index_) {
       index = index_;
-      index.read(1);
       if (!filesToAdd) { filesToAdd = []; }
       filesToAdd.forEach(function(filePath) {
         index.addByPath(filePath);
@@ -907,7 +927,7 @@ function performRebase(repository, rebase, signature, beforeNextFn) {
   function getPromise() {
     return rebase.next()
       .then(function() {
-        return repository.openIndex()
+        return repository.refreshIndex()
           .then(function(index) {
             if (index.hasConflicts()) {
               throw index;
@@ -1033,7 +1053,7 @@ Repository.prototype.continueRebase = function(signature, beforeNextFn) {
 
   signature = signature || repo.defaultSignature();
 
-  return repo.openIndex()
+  return repo.refreshIndex()
     .then(function(index) {
       if (index.hasConflicts()) {
         throw index;
@@ -1241,11 +1261,10 @@ Repository.prototype.stageFilemode = function(filePath, stageNew) {
 
   return fse.remove(indexLock)
     .then(function() {
-      return repo.openIndex();
+      return repo.refreshIndex();
     })
     .then(function(indexResult) {
       index = indexResult;
-      return index.read(1);
     })
     .then(function() {
       return diffPromise;
@@ -1449,10 +1468,9 @@ Repository.prototype.stageLines =
       });
     };
 
-  return repo.openIndex()
+  return repo.refreshIndex()
     .then(function(indexResult) {
       index = indexResult;
-      return index.read(1);
     })
     .then(function() {
       return diffPromise();

diff --git a/test/tests/checkout.js b/test/tests/checkout.js
@@ -126,9 +126,8 @@ describe("Checkout", function() {
     .then(function(branch) {
       fse.writeFileSync(packageJsonPath, "\n");
 
-      return test.repository.openIndex()
+      return test.repository.refreshIndex()
         .then(function(index) {
-          index.read(1);
           index.addByPath(packageJsonName);
           index.write();
 

diff --git a/test/tests/commit.js b/test/tests/commit.js
@@ -55,11 +55,10 @@ describe("Commit", function() {
 
     return fse.writeFile(path.join(repo.workdir(), fileName), fileContent)
     .then(function() {
-      return repo.openIndex();
+      return repo.refreshIndex();
     })
     .then(function(indexResult) {
       index = indexResult;
-      return index.read(1);
     })
     .then(function() {
       return index.addByPath(fileName);
@@ -162,11 +161,10 @@ describe("Commit", function() {
       return fse.writeFile(path.join(repo.workdir(), fileName), fileContent);
     })
     .then(function() {
-      return repo.openIndex();
+      return repo.refreshIndex();
     })
     .then(function(indexResult) {
       index = indexResult;
-      return index.read(1);
     })
     .then(function() {
       return index.addByPath(fileName);
@@ -242,11 +240,10 @@ describe("Commit", function() {
       return fse.writeFile(path.join(repo.workdir(), fileName), fileContent);
     })
     .then(function() {
-      return repo.openIndex();
+      return repo.refreshIndex();
     })
     .then(function(indexResult) {
       index = indexResult;
-      return index.read(1);
     })
     .then(function() {
       return index.addByPath(fileName);
@@ -290,11 +287,10 @@ describe("Commit", function() {
       );
     })
     .then(function() {
-      return repo.openIndex();
+      return repo.refreshIndex();
     })
     .then(function(indexResult) {
       index = indexResult;
-      return index.read(1);
     })
     .then(function() {
       return index.addByPath(newFileName);

diff --git a/test/tests/diff.js b/test/tests/diff.js
@@ -27,7 +27,7 @@ describe("Diff", function() {
     return Repository.open(reposPath).then(function(repository) {
       test.repository = repository;
 
-      return repository.openIndex();
+      return repository.refreshIndex();
     })
     .then(function(index) {
       test.index = index;
@@ -307,7 +307,7 @@ describe("Diff", function() {
     return Repository.open(reposPath).then(function(repository) {
       test.repository = repository;
 
-      return repository.openIndex();
+      return repository.refreshIndex();
     })
     .then(function(index) {
       test.index = index;

diff --git a/test/tests/index.js b/test/tests/index.js
@@ -22,7 +22,7 @@ describe("Index", function() {
     return Repository.open(reposPath)
       .then(function(repo) {
         test.repository = repo;
-        return repo.openIndex();
+        return repo.refreshIndex();
       })
       .then(function(index) {
         test.index = index;
@@ -342,7 +342,7 @@ describe("Index", function() {
         return RepoUtils.addFileToIndex(repo, fileName);
       })
       .then(function() {
-        return repo.openIndex();
+        return repo.index();
       })
       .then(function(index) {
         assert.ok(!index.hasConflicts());
@@ -353,7 +353,7 @@ describe("Index", function() {
         );
       })
       .then(function() {
-        return repo.openIndex();
+        return repo.index();
       })
       .then(function(index) {
         assert(index.hasConflicts());