[PATCH v3 7/7] documentation: format-patch: clarify requirements for patch-ids to match

From: Jerry Zhang via GitGitGadget <gitgitgadget@gmail.com>
Date: Oct 14, 2022, 08:56 UTC
Message-ID: <69440797f302729d59f19c0994916e193c9dbf58.1665737804.git.gitgitgadget@gmail.com>
In-Reply-To: <pull.1359.v3.git.1665737804.gitgitgadget@gmail.com>

From: Jerry Zhang <Jerry@skydio.com>

The documentation for format-patch advertises that the ids it generates for prerequisite patches are the same as piping the patch into "git patch-id". Clarify here that this is only true if the patch was generated with -U3, and for binary patches, with --full-index.

Note that the actual equivalence isn't currently tested. Aside from a few cases fixed in this patch series, I've seen some uncommon situations where "git diff" and the internal diff api actually generate equally valid diffs of the same length, but with lines reordered, which results in different patch-ids.

Signed-off-by: Jerry Zhang <Jerry@skydio.com>
---
 Documentation/git-format-patch.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index dfcc7da4c21..566d4b486dd 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -668,8 +668,8 @@ of 'base commit' in topological order before the patches can be applied.
 The 'base commit' is shown as "base-commit: " followed by the 40-hex of
 the commit object name.  A 'prerequisite patch' is shown as
 "prerequisite-patch-id: " followed by the 40-hex 'patch id', which can
-be obtained by passing the patch through the `git patch-id --stable`
-command.
+be obtained by passing the patch (generated with -U3 --full-index) through
+the `git patch-id --stable` command.
 
 Imagine that on top of the public commit P, you applied well-known
 patches X, Y and Z from somebody else, and then built your three-patch

-- 
gitgitgadget