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.

1 files changed, 12 insertions, 5 deletions

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