{"thread":{"id":"55379","subject":"[PATCH 0/2] Diff format documentation for git-format-patch","startedAt":"2021-03-24T12:31:19Z","lastAt":"2021-03-25T18:26:37Z","messageCount":7,"participants":["Bagas Sanjaya","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"420111","messageId":"20210324123027.29460-1-bagasdotme@gmail.com","threadId":"55379","inReplyTo":null,"subject":"[PATCH 0/2] Diff format documentation for git-format-patch","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-03-24T12:30:25Z","receivedAt":"2021-03-24T12:31:19Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"git-format-patch generates diff, but the documentation for its\nformat is missing, so add it.\n\nBagas Sanjaya (2):\n git-format-patch: Include diff-generate-patch documentation\n git-format-patch: Document format for binary patch\n\n Documentation/git-format-patch.txt | 29 +++++++++++++++++++++++++++++\n 1 file changed, 29 insertions(+)\n\n-- \n2.25.1\n\n"},{"id":"420112","messageId":"20210324123027.29460-2-bagasdotme@gmail.com","threadId":"55379","inReplyTo":"20210324123027.29460-1-bagasdotme@gmail.com","subject":"[PATCH 1/2] git-format-patch: Include diff-generate-patch documentation","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-03-24T12:30:26Z","receivedAt":"2021-03-24T12:31:53Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"diff-generate-patch explains format of generated patch for text files.\n\nSigned-off-by: Bagas Sanjaya \n---\n Documentation/git-format-patch.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 3e49bf2210..247033f8fc 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -718,6 +718,13 @@ use it only when you know the recipient uses Git to apply your patch.\n $ git format-patch -3\n ------------\n \n+GENERATED DIFF FORMAT\n+---------------------\n+git-format-patch emits diff in generated patches. For text files, the\n+diff format is described as below:\n+\n+include::diff-generate-patch.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-am[1], linkgit:git-send-email[1]\n-- \n2.25.1\n\n"},{"id":"420113","messageId":"20210324123027.29460-3-bagasdotme@gmail.com","threadId":"55379","inReplyTo":"20210324123027.29460-1-bagasdotme@gmail.com","subject":"[PATCH 2/2] git-format-patch: Document format for binary patch","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-03-24T12:30:27Z","receivedAt":"2021-03-24T12:31:53Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Document binary file patch formats that are different from text file\npatch.\n\nSigned-off-by: Bagas Sanjaya \n---\n Documentation/git-format-patch.txt | 22 ++++++++++++++++++++++\n 1 file changed, 22 insertions(+)\n\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 247033f8fc..8de172b1f4 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -725,6 +725,28 @@ diff format is described as below:\n \n include::diff-generate-patch.txt[]\n \n+Binary Files\n+~~~~~~~~~~~~\n+For binary files, the diff format have some differences compared to text\n+files:\n+\n+1. Object hashes in index header line (`index .. `)\n+ are always given in full form, as binary patch is designed to be\n+ applied only to an exact copy of original file. This is to ensure\n+ that such patch don't apply to file with similar name but different\n+ hash.\n+\n+2. There are additional extended header lines specific to binary files:\n+\n+ GIT binary patch\n+ delta \n+ literal \n+\n+3. The diff body can be either delta or full (literal) content,\n+ whichever is the smallest size. It is encoded with base85 algorithm,\n+ and emitted in 64 characters each line. All but the last line in\n+ the body are prefixed with `z`.\n+\n SEE ALSO\n --------\n linkgit:git-am[1], linkgit:git-send-email[1]\n-- \n2.25.1\n\n"},{"id":"420121","messageId":"xmqqeeg4zbyz.fsf@gitster.g","threadId":"55379","inReplyTo":"20210324123027.29460-2-bagasdotme@gmail.com","subject":"Re: [PATCH 1/2] git-format-patch: Include diff-generate-patch documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-24T17:40:52Z","receivedAt":"2021-03-24T17:41:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> diff-generate-patch explains format of generated patch for text files.\n\nThat is true, but that does not justify this change. In other\nwords, the sentence does not explain why is it a good idea to\ndescribe the itty bitty details of what is in the format-patch\noutput (which is more for the consumption of somebody other than the\nuser who is running the format-patch command).\n\n> Signed-off-by: Bagas Sanjaya \n> ---\n> Documentation/git-format-patch.txt | 7 +++++++\n> 1 file changed, 7 insertions(+)\n>\n> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\n> index 3e49bf2210..247033f8fc 100644\n> --- a/Documentation/git-format-patch.txt\n> +++ b/Documentation/git-format-patch.txt\n> @@ -718,6 +718,13 @@ use it only when you know the recipient uses Git to apply your patch.\n> $ git format-patch -3\n> ------------\n> \n> +GENERATED DIFF FORMAT\n> +---------------------\n> +git-format-patch emits diff in generated patches. For text files, the\n> +diff format is described as below:\n> +\n> +include::diff-generate-patch.txt[]\n> +\n\nI suspect that, rather than adding a new section, it would be a\nbetter change to extend what the first parapgraph of the Description\nsays.\n\nThe current text says something called \"patch\" is prepared one for\neach commit, it is suitable for e-mail submission, and \"am\" is the\ncommand to use it, but does not say what that \"patch\" really is.\nThe description in the page also refers to \"three-dash\" line, but\nthat is totally unclear unless the reader is given a more detailed\noverview of what the \"patch\" the first paragraph refers to (and\ndiff-generate-patch.txt will not be the place to talk about it).\n\nIn other words, something like this one.\n\n----- >8 ----- ----- >8 ----- ----- >8 ----- ----- >8 ----- ----- >8 -----\nFrom: Junio C Hamano \nDate: Wed, 24 Mar 2021 10:35:40 -0700\nSubject: [PATCH] format-patch: give an overview of what a \"patch\" message is\n\nThe text says something called a \"patch\" is prepared one for each\ncommit, it is suitable for e-mail submission, and \"am\" is the\ncommand to use it, but does not say what the \"patch\" really is. The\ndescription in the page also refers to \"three-dash\" line, but that\nis totally unclear unless the reader is given a more detailed\noverview of what the \"patch\" the first paragraph refers to.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-format-patch.txt | 21 +++++++++++++++++++--\n 1 file changed, 19 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 3e49bf2210..3db0e036d8 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -36,11 +36,28 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Prepare each commit with its patch in\n-one file per commit, formatted to resemble UNIX mailbox format.\n+Prepare each commit with its \"patch\" in\n+one \"message\" per commit, formatted to resemble a UNIX mailbox.\n The output of this command is convenient for e-mail submission or\n for use with 'git am'.\n \n+A \"message\" generated by the command consists of three parts:\n+\n+* A brief metadata header that begins with `From `\n+ with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs\n+ like \"file(1)\" to recognize that the file is an output from this\n+ command, fields that record the author identity, the author date,\n+ and the title of the change (taken from the first paragraph of the\n+ commit log message).\n+\n+* The second and subsequent paragraphs of the commit log message.\n+\n+* The \"patch\", which is the \"diff -p --stat\" output (see\n+ linkgit:git-diff[1]) between the commit and its parent.\n+\n+The log message and the patch is separated by a line with a\n+three-dash line.\n+\n There are two ways to specify which commits to operate on.\n \n 1. A single commit, , specifies that the commits leading\n-- \n2.31.0-464-gadc53f61d7\n\n"},{"id":"420123","messageId":"xmqqa6qszbdv.fsf@gitster.g","threadId":"55379","inReplyTo":"20210324123027.29460-3-bagasdotme@gmail.com","subject":"Re: [PATCH 2/2] git-format-patch: Document format for binary patch","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-24T17:53:32Z","receivedAt":"2021-03-24T17:54:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> Document binary file patch formats that are different from text file\n> patch.\n>\n> Signed-off-by: Bagas Sanjaya \n> ---\n> Documentation/git-format-patch.txt | 22 ++++++++++++++++++++++\n> 1 file changed, 22 insertions(+)\n>\n> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\n> index 247033f8fc..8de172b1f4 100644\n> --- a/Documentation/git-format-patch.txt\n> +++ b/Documentation/git-format-patch.txt\n> @@ -725,6 +725,28 @@ diff format is described as below:\n> \n> include::diff-generate-patch.txt[]\n> \n> +Binary Files\n> +~~~~~~~~~~~~\n> +For binary files, the diff format have some differences compared to text\n> +files:\n\nI do not think this is specific to 'format-patch'. If we need to\ndescribe 'git diff --binary', it should be done there, so that\nreaders of \"git diff --help\" would also be able to learn the format.\n\n> +1. Object hashes in index header line (`index .. `)\n\ns/Object hash/Object name/;\n\n> + are always given in full form, as binary patch is designed to be\n> + applied only to an exact copy of original file. This is to ensure\n> + that such patch don't apply to file with similar name but different\n> + hash.\n\n... with similar but different object name.\n\ncf. Documentation/glossary-contents.txt tells you what \"object name\" is.\n\n> +2. There are additional extended header lines specific to binary files:\n> +\n> + GIT binary patch\n> + delta \n> + literal \n> +\n> +3. The diff body can be either delta or full (literal) content,\n> + whichever is the smallest size. It is encoded with base85 algorithm,\n> + and emitted in 64 characters each line. All but the last line in\n> + the body are prefixed with `z`.\n\nI do not think this is all that useful; it clutters the description\nfor a reader who is not interested in reimplementing an encoder or a\ndecoder from the document.\n\nAnd it is way too insufficient for a reader who wants to reimplement\nan encoder or a decoder. For example,\n\n - It does not say anything about what the delta is and how it is\n computed.\n\n - The 'z' is redundant; the more important is to say that the first\n byte signals how many bytes are on that line and it is a mere\n artifact that we cram up to 52 bytes on a line.\n\n - It does not say anything about how the binary patch ensures that\n it is reversible (i.e. can be given to \"git apply -R\").\n\nThanks.\n"},{"id":"420177","messageId":"678c0fa9-8ae5-f8ae-b93a-3d68c7c11c8f@gmail.com","threadId":"55379","inReplyTo":"xmqqa6qszbdv.fsf@gitster.g","subject":"Re: [PATCH 2/2] git-format-patch: Document format for binary patch","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-03-25T06:22:37Z","receivedAt":"2021-03-25T06:23:45Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 25/03/21 00.53, Junio C Hamano wrote:\n> I do not think this is all that useful; it clutters the description\n> for a reader who is not interested in reimplementing an encoder or a\n> decoder from the document.\n> \n> And it is way too insufficient for a reader who wants to reimplement\n> an encoder or a decoder. For example,\n> \n> - It does not say anything about what the delta is and how it is\n> computed.\n> \n> - The 'z' is redundant; the more important is to say that the first\n> byte signals how many bytes are on that line and it is a mere\n> artifact that we cram up to 52 bytes on a line.\n> \n> - It does not say anything about how the binary patch ensures that\n> it is reversible (i.e. can be given to \"git apply -R\").\n> \n> Thanks.\n> \nHmmm...\n\nI write this patch from \"naive\" observation of git format-patch's\nbehavior when given binary files in the commit.\n\nPerhaps someone which is more familiar in base85 {en,de}coder and binary\npatch in general can write better documentation than what I send here.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"420198","messageId":"xmqqft0jw0nn.fsf@gitster.g","threadId":"55379","inReplyTo":"678c0fa9-8ae5-f8ae-b93a-3d68c7c11c8f@gmail.com","subject":"Re: [PATCH 2/2] git-format-patch: Document format for binary patch","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-25T18:25:48Z","receivedAt":"2021-03-25T18:26:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> On 25/03/21 00.53, Junio C Hamano wrote:\n>> I do not think this is all that useful; it clutters the description\n>> for a reader who is not interested in reimplementing an encoder or a\n>> decoder from the document.\n>> And it is way too insufficient for a reader who wants to reimplement\n>> an encoder or a decoder. For example,\n>> - It does not say anything about what the delta is and how it is\n>> computed.\n>> - The 'z' is redundant; the more important is to say that the\n>> first\n>> byte signals how many bytes are on that line and it is a mere\n>> artifact that we cram up to 52 bytes on a line.\n>> - It does not say anything about how the binary patch ensures that\n>> it is reversible (i.e. can be given to \"git apply -R\").\n>> Thanks.\n>> \n> Hmmm...\n>\n> I write this patch from \"naive\" observation of git format-patch's\n> behavior when given binary files in the commit.\n>\n> Perhaps someone which is more familiar in base85 {en,de}coder and binary\n> patch in general can write better documentation than what I send here.\n\nI do not mind reviewing an update to an existing document or a new\ndocument in Documentation/technical/ somewhere, if somebody is\nmotivated enough to write the details to a degree that would allow\nreimplementation of the encoder and the decoder. I just do not think\nit belongs to the end-user-facing document of \"format-patch\", whose\ntarget is users of the \"format-patch\" command, not reimplementors of\nthe command.\n\n\n"}]}