From: Stefan Sperling <stsp@stsp.name>
Subject: rework got patch -c docs
To: gameoftrees@openbsd.org
Date: Fri, 29 Jul 2022 14:07:06 +0200

This rephrases and expands got patch -c documentation.
I hope this makes it easier to understand how this feature should
be used and what the benefits and tradeoffs are for the user.

ok?

diff 78368643b1a7e297cd29cca32debb6514d206df1 bd9843cb92479a9a74a7578dfcf5e155e2f3360d
commit - 78368643b1a7e297cd29cca32debb6514d206df1
commit + bd9843cb92479a9a74a7578dfcf5e155e2f3360d
blob - fb5fa0ee9c49ef907bcaaf33aed748fe236e9d6a
blob + 119947954209ae33b3144c11757b93ae8a30a06a
--- got/got.1
+++ got/got.1
@@ -1402,17 +1402,38 @@ The options for
 are as follows:
 .Bl -tag -width Ds
 .It Fl c Ar commit
-Use files found in in the specified
+Attempt to locate files within the specified
 .Ar commit
-as a merge base for 3-way merges, overriding the meta-data in
+for use as a merge-base for 3-way merges.
+Ideally, the specified
+.Ar commit
+should contain versions of files which the changes contained in the
 .Ar patchfile
-.Pq if any .
-In case no merge-base is available for a file
-.Cm got patch
-will attempt to apply the changes without doing a 3-way merge.
-If
+were based on.
+Files will be located by path, relative to the repository root.
+If the
 .Fl p
-is used, the paths are stripped before being looked up.
+option is used then leading path components will be stripped
+before paths are looked up in the repository.
+.Pp
+If the
+.Fl c
+option is not used then
+.Cm got patch
+will attempt to locate merge-bases via object IDs found in
+.Ar patchfile
+meta-data, such as produced by
+.Cm got diff
+or
+.Xr git-diff 1 .
+Use of the
+.Fl c
+option is only recommended in the absence of such meta-data.
+.Pp
+In case no merge-base is available for a file, changes will be applied
+without doing a 3-way merge.
+Changes which do not apply cleanly may then be rejected entirely, rather
+than producing merge conflicts in the patched target file.
 .It Fl n
 Do not make any modifications to the work tree.
 This can be used to check whether a patch would apply without issues.