Make diff and status perform soft index reload

This changes `git_index_read` to have two modes - a hard index
reload that always resets the index to match the on-disk data
(which was the old behavior) and a soft index reload that uses
the timestamp / file size information and only replaces the index
data if the file on disk has been modified.

This then updates the git_status code to do a soft reload unless
the new GIT_STATUS_OPT_NO_REFRESH flag is passed in.

This also changes the behavior of the git_diff functions that use
the index so that when an index is not explicitly passed in (i.e.
when the functions call git_repository_index for you), they will
also do a soft reload for you.

This intentionally breaks the file signature of git_index_read
because there has been some confusion about the behavior previously
and it seems like all existing uses of the API should probably be
examined to select the desired behavior.

3 files changed, 24 insertions, 5 deletions

diff --git a/include/git2/diff.h b/include/git2/diff.h
index 5d360bedb..ac2d4b1e7 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -607,6 +607,10 @@ GIT_EXTERN(int) git_diff_tree_to_tree(
  * The tree you pass will be used for the "old_file" side of the delta, and
  * the index will be used for the "new_file" side of the delta.
  *
+ * If you pass NULL for the index, then the existing index of the `repo`
+ * will be used.  In this case, the index will be refreshed from disk
+ * (if it has changed) before the diff is generated.
+ *
  * @param diff Output pointer to a git_diff pointer to be allocated.
  * @param repo The repository containing the tree and index.
  * @param old_tree A git_tree object to diff from, or NULL for empty tree.
@@ -631,6 +635,10 @@ GIT_EXTERN(int) git_diff_tree_to_index(
  * The index will be used for the "old_file" side of the delta, and the
  * working directory will be used for the "new_file" side of the delta.
  *
+ * If you pass NULL for the index, then the existing index of the `repo`
+ * will be used.  In this case, the index will be refreshed from disk
+ * (if it has changed) before the diff is generated.
+ *
  * @param diff Output pointer to a git_diff pointer to be allocated.
  * @param repo The repository.
  * @param index The index to diff from; repo index used if NULL.
diff --git a/include/git2/index.h b/include/git2/index.h
index 8064a62ff..7de106624 100644
--- a/include/git2/index.h
+++ b/include/git2/index.h
@@ -222,16 +222,23 @@ GIT_EXTERN(unsigned int) git_index_caps(const git_index *index);
 GIT_EXTERN(int) git_index_set_caps(git_index *index, unsigned int caps);
 
 /**
- * Update the contents of an existing index object in memory
- * by reading from the hard disk.
+ * Update the contents of an existing index object in memory by reading
+ * from the hard disk.
  *
- * If the file doesn't exist on the filesystem, the index
- * will be cleared from its current content.
+ * Pass 0 for `only_if_changed` to perform a "hard" read that discards
+ * in-memory changes and always reloads the on-disk index data.  If there
+ * is no on-disk version, the index will be cleared.
+ *
+ * Pass non-zero for `only_if_changed` to perform a "soft" read that only
+ * reloads the index data if it has changed since the last time it was
+ * loaded.  In-memory index data will be untouched.  Be aware: if there
+ * are changes on disk, unwritten in-memory changes will be discarded.
  *
  * @param index an existing index object
+ * @param only_if_changed only read if on-disk file is newer than last read
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_index_read(git_index *index);
+GIT_EXTERN(int) git_index_read(git_index *index, int only_if_changed);
 
 /**
  * Write an existing index object from memory back to disk
diff --git a/include/git2/status.h b/include/git2/status.h
index aa934d96b..4ec3432df 100644
--- a/include/git2/status.h
+++ b/include/git2/status.h
@@ -118,6 +118,9 @@ typedef enum {
  *   case-insensitive order
  * - GIT_STATUS_OPT_RENAMES_FROM_REWRITES indicates that rename detection
  *   should include rewritten files
+ * - GIT_STATUS_OPT_NO_REFRESH bypasses the default status behavior of
+ *   doing a "soft" index reload (i.e. reloading the index data if the
+ *   file on disk has been modified outside libgit2).
  *
  * Calling `git_status_foreach()` is like calling the extended version
  * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED,
@@ -137,6 +140,7 @@ typedef enum {
 	GIT_STATUS_OPT_SORT_CASE_SENSITIVELY    = (1u << 9),
 	GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY  = (1u << 10),
 	GIT_STATUS_OPT_RENAMES_FROM_REWRITES    = (1u << 11),
+	GIT_STATUS_OPT_NO_REFRESH               = (1u << 12),
 } git_status_opt_t;
 
 #define GIT_STATUS_OPT_DEFAULTS \