threads / patch / 55379
Subject: [PATCH 0/2] Diff format documentation for git-format-patch
Bagas Sanjayagit-format-patch generates diff, but the documentation for its format is missing, so add it.
Bagas Sanjaya (2): git-format-patch: Include diff-generate-patch documentation git-format-patch: Document format for binary patch
Documentation/git-format-patch.txt | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+)
-- 2.25.1
Bagas Sanjaya[PATCH 1/2] git-format-patch: Include diff-generate-patch documentation
diff-generate-patch explains format of generated patch for text files.
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> --- Documentation/git-format-patch.txt | 7 +++++++ 1 file changed, 7 insertions(+)
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 3e49bf2210..247033f8fc 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -718,6 +718,13 @@ use it only when you know the recipient uses Git to apply your patch. $ git format-patch -3 ------------ +GENERATED DIFF FORMAT +--------------------- +git-format-patch emits diff in generated patches. For text files, the +diff format is described as below: + +include::diff-generate-patch.txt[] + SEE ALSO -------- linkgit:git-am[1], linkgit:git-send-email[1]
-- 2.25.1
Junio C HamanoRe: [PATCH 1/2] git-format-patch: Include diff-generate-patch documentation
Bagas Sanjaya <bagasdotme@gmail.com> writes:
> diff-generate-patch explains format of generated patch for text files.
That is true, but that does not justify this change. In other words, the sentence does not explain why is it a good idea to describe the itty bitty details of what is in the format-patch output (which is more for the consumption of somebody other than the user who is running the format-patch command).
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> > --- > Documentation/git-format-patch.txt | 7 +++++++ > 1 file changed, 7 insertions(+) > > diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt > index 3e49bf2210..247033f8fc 100644 > --- a/Documentation/git-format-patch.txt > +++ b/Documentation/git-format-patch.txt > @@ -718,6 +718,13 @@ use it only when you know the recipient uses Git to apply your patch. > $ git format-patch -3 > ------------ > > +GENERATED DIFF FORMAT > +--------------------- > +git-format-patch emits diff in generated patches. For text files, the > +diff format is described as below: > + > +include::diff-generate-patch.txt[] > +
I suspect that, rather than adding a new section, it would be a better change to extend what the first parapgraph of the Description says.
The current text says something called "patch" is prepared one for each commit, it is suitable for e-mail submission, and "am" is the command to use it, but does not say what that "patch" really is. The description in the page also refers to "three-dash" line, but that is totally unclear unless the reader is given a more detailed overview of what the "patch" the first paragraph refers to (and diff-generate-patch.txt will not be the place to talk about it).
In other words, something like this one.
----- >8 ----- ----- >8 ----- ----- >8 ----- ----- >8 ----- ----- >8 ----- From: Junio C Hamano <gitster@pobox.com> Date: Wed, 24 Mar 2021 10:35:40 -0700 Subject: [PATCH] format-patch: give an overview of what a "patch" message is
The text says something called a "patch" is prepared one for each commit, it is suitable for e-mail submission, and "am" is the command to use it, but does not say what the "patch" really is. The description in the page also refers to "three-dash" line, but that is totally unclear unless the reader is given a more detailed overview of what the "patch" the first paragraph refers to.
Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-format-patch.txt | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 3e49bf2210..3db0e036d8 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -36,11 +36,28 @@ SYNOPSIS DESCRIPTION ----------- -Prepare each commit with its patch in -one file per commit, formatted to resemble UNIX mailbox format. +Prepare each commit with its "patch" in +one "message" per commit, formatted to resemble a UNIX mailbox. The output of this command is convenient for e-mail submission or for use with 'git am'. +A "message" generated by the command consists of three parts: + +* A brief metadata header that begins with `From <commit>` + with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs + like "file(1)" to recognize that the file is an output from this + command, fields that record the author identity, the author date, + and the title of the change (taken from the first paragraph of the + commit log message). + +* The second and subsequent paragraphs of the commit log message. + +* The "patch", which is the "diff -p --stat" output (see + linkgit:git-diff[1]) between the commit and its parent. + +The log message and the patch is separated by a line with a +three-dash line. + There are two ways to specify which commits to operate on. 1. A single commit, <since>, specifies that the commits leading
-- 2.31.0-464-gadc53f61d7
Bagas Sanjaya[PATCH 2/2] git-format-patch: Document format for binary patch
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
Junio C HamanoRe: [PATCH 2/2] git-format-patch: Document format for binary patch
Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 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:
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/;
> + 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.
> +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.
Bagas SanjayaRe: [PATCH 2/2] git-format-patch: Document format for binary patch
On 25/03/21 00.53, Junio C Hamano wrote:
> 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. >
Hmmm...
I write this patch from "naive" observation of git format-patch's behavior when given binary files in the commit.
Perhaps someone which is more familiar in base85 {en,de}coder and binary patch in general can write better documentation than what I send here.
-- An old man doll... just what I always wanted! - Clara
Junio C HamanoRe: [PATCH 2/2] git-format-patch: Document format for binary patch
Bagas Sanjaya <bagasdotme@gmail.com> writes:
> On 25/03/21 00.53, Junio C Hamano wrote:
>> 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.
>>
> Hmmm...
>
> I write this patch from "naive" observation of git format-patch's
> behavior when given binary files in the commit.
>
> Perhaps someone which is more familiar in base85 {en,de}coder and binary
> patch in general can write better documentation than what I send here.I do not mind reviewing an update to an existing document or a new document in Documentation/technical/ somewhere, if somebody is motivated enough to write the details to a degree that would allow reimplementation of the encoder and the decoder. I just do not think it belongs to the end-user-facing document of "format-patch", whose target is users of the "format-patch" command, not reimplementors of the command.