Re: [PATCH 2/2] git-format-patch: Document format for binary patch
From: Junio C Hamano <hidden>
Date: 2021-03-24 17:54:30
Bagas Sanjaya [off-list ref] writes:
quoted hunk
Document binary file patch formats that are different from text file patch. Signed-off-by: Bagas Sanjaya <redacted> --- 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:
I do not think this is specific to 'format-patch'. If we need to describe 'git diff --binary', it should be done there, so that readers of "git diff --help" would also be able to learn the format.
+1. Object hashes in index header line (`index <hash>..<hash> <mode>`)
s/Object hash/Object name/;
quoted hunk
+ 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.
... with similar but different object name. cf. Documentation/glossary-contents.txt tells you what "object name" is.
quoted hunk
+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`.
I do not think this is all that useful; it clutters the description for a reader who is not interested in reimplementing an encoder or a decoder from the document. And it is way too insufficient for a reader who wants to reimplement an encoder or a decoder. For example, - It does not say anything about what the delta is and how it is computed. - The 'z' is redundant; the more important is to say that the first byte signals how many bytes are on that line and it is a mere artifact that we cram up to 52 bytes on a line. - It does not say anything about how the binary patch ensures that it is reversible (i.e. can be given to "git apply -R"). Thanks.