[PATCH 2/2] git-format-patch: Document format for binary patch

From: Bagas Sanjaya <bagasdotme@gmail.com>
To: git@vger.kernel.org
Cc: gitster@pobox.com, Bagas Sanjaya <bagasdotme@gmail.com>
Subject: [PATCH 2/2] git-format-patch: Document format for binary patch
Date: Wed, 24 Mar 2021 19:30:27 +0700	[thread overview]
Message-ID: <20210324123027.29460-3-bagasdotme@gmail.com> (raw)
In-Reply-To: <20210324123027.29460-1-bagasdotme@gmail.com>

Document binary file patch formats that are different from text file
patch.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/git-format-patch.txt | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 247033f8fc..8de172b1f4 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -725,6 +725,28 @@ diff format is described as below:
 
 include::diff-generate-patch.txt[]
 
+Binary Files
+~~~~~~~~~~~~
+For binary files, the diff format have some differences compared to text
+files:
+
+1. Object hashes in index header line (`index <hash>..<hash> <mode>`)
+   are always given in full form, as binary patch is designed to be
+   applied only to an exact copy of original file. This is to ensure
+   that such patch don't apply to file with similar name but different
+   hash.
+
+2. There are additional extended header lines specific to binary files:
+
+        GIT binary patch
+        delta <bytes>
+        literal <bytes>
+
+3. The diff body can be either delta or full (literal) content,
+   whichever is the smallest size. It is encoded with base85 algorithm,
+   and emitted in 64 characters each line. All but the last line in
+   the body are prefixed with `z`.
+
 SEE ALSO
 --------
 linkgit:git-am[1], linkgit:git-send-email[1]
-- 
2.25.1

