Some doc and examples/diff.c changes

I was playing with "git diff-index" and wanted to be able to
emulate that behavior a little more closely with the diff example.

Also, I wanted to play with running `git_diff_tree_to_workdir`
directly even though core Git doesn't exactly have the equivalent,
so I added a command line option for that and tweaked some other
things in the example code.

This changes a minor output thing in that the "raw" print helper
function will no longer add ellipses (...) if the OID is not
actually abbreviated.

1 files changed, 11 insertions, 18 deletions

diff --git a/include/git2/diff.h b/include/git2/diff.h
index a0cfbc918..c8e1ad143 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -725,24 +725,17 @@ GIT_EXTERN(int) git_diff_index_to_workdir(
  * The tree you provide will be used for the "old_file" side of the delta,
  * and the working directory will be used for the "new_file" side.
  *
- * Please note: this is *NOT* the same as `git diff <treeish>`.  Running
- * `git diff HEAD` or the like actually uses information from the index,
- * along with the tree and working directory info.
- *
- * This function returns strictly the differences between the tree and the
- * files contained in the working directory, regardless of the state of
- * files in the index.  It may come as a surprise, but there is no direct
- * equivalent in core git.
- *
- * To emulate `git diff <tree>`, use `git_diff_tree_to_workdir_with_index`
- * (or `git_diff_tree_to_index` and `git_diff_index_to_workdir`, then call
- * `git_diff_merge` on the results).  That will yield a `git_diff` that
- * matches the git output.
- *
- * If this seems confusing, take the case of a file with a staged deletion
- * where the file has then been put back into the working dir and modified.
- * The tree-to-workdir diff for that file is 'modified', but core git would
- * show status 'deleted' since there is a pending deletion in the index.
+ * This is not the same as `git diff <treeish>` or `git diff-index
+ * <treeish>`.  Those commands use information from the index, whereas this
+ * function strictly returns the differences between the tree and the files
+ * in the working directory, regardless of the state of the index.  Use
+ * `git_diff_tree_to_workdir_with_index` to emulate those commands.
+ *
+ * To see difference between this and `git_diff_tree_to_workdir_with_index`,
+ * consider the example of a staged file deletion where the file has then
+ * been put back into the working dir and further modified.  The
+ * tree-to-workdir diff for that file is 'modified', but `git diff` would
+ * show status 'deleted' since there is a staged delete.
  *
  * @param diff A pointer to a git_diff pointer that will be allocated.
  * @param repo The repository containing the tree.