checkout: better document the `baseline_index` opt

2 files changed, 12 insertions, 1 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3657906d6..d8bea9e15 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,9 @@ v0.22 + 1
 * On Mac OS X, we now use SecureTransport to provide the cryptographic
 support for HTTPS connections insead of OpenSSL.
 
+* Checkout can now accept an index for the baseline computations via the
+  `baseline_index` member.
+
 ### API additions
 
 * The `git_merge_options` gained a `file_flags` member.
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index 58f190719..6cf9ed8bd 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -272,7 +272,15 @@ typedef struct git_checkout_options {
 	 */
 	git_strarray paths;
 
-	git_tree *baseline; /**< expected content of workdir, defaults to HEAD */
+	/** The expected content of the working directory; defaults to HEAD.
+	 *  If the working directory does not match this baseline information,
+	 *  that will produce a checkout conflict.
+	 */
+	git_tree *baseline;
+
+	/** Like `baseline` above, though expressed as an index.  This
+	 *  option overrides `baseline`.
+	 */
 	git_index *baseline_index; /**< expected content of workdir, expressed as an index. */
 
 	const char *target_directory; /**< alternative checkout path to workdir */