checkout: better document the `baseline_index` opt

1 files changed, 9 insertions, 1 deletions

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 */