{"thread":{"id":"18483","subject":"[PATCH] Documentation: git-format-patch.txt rewordings and cleanups","startedAt":"2009-03-23T10:21:23Z","lastAt":"2009-03-25T07:26:42Z","messageCount":7,"participants":["Stephen Boyd","J. Bruce Fields","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"109027","messageId":"1237803683-14939-1-git-send-email-bebarino@gmail.com","threadId":"18483","inReplyTo":null,"subject":"[PATCH] Documentation: git-format-patch.txt rewordings and cleanups","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2009-03-23T10:21:23Z","receivedAt":"2009-03-23T10:21:23Z","isPatch":true,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"Clarify --no-binary description using some words from the original\ncommit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix and\n--thread descriptions. Add --thread style option to synopsis. Clarify\nrenaming patches example.\n\nSigned-off-by: Stephen Boyd <bebarino@gmail.com>\n---\nIs the synopsis getting too heavy? Maybe it should be changed to:\n\n    git format-patch [<options>] [<common diff options>] [<revision range>]\n\n Documentation/git-format-patch.txt |   34 +++++++++++++++++-----------------\n 1 files changed, 17 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex c2eb5fa..f31098b 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -9,9 +9,9 @@ git-format-patch - Prepare patches for e-mail submission\n SYNOPSIS\n --------\n [verse]\n-'git format-patch' [-k] [-o <dir> | --stdout] [--thread]\n+'git format-patch' [-k] [-o <dir> | --stdout] [--thread[=<style>]]\n \t\t   [--attach[=<boundary>] | --inline[=<boundary>] |\n-\t\t     [--no-attach]]\n+\t\t    --no-attach]\n \t\t   [-s | --signoff] [<common diff options>]\n \t\t   [-n | --numbered | -N | --no-numbered]\n \t\t   [--start-number <n>] [--numbered-files]\n@@ -132,9 +132,9 @@ include::diff-options.txt[]\n \tthe Message-Id header to reference.\n +\n The optional <style> argument can be either `shallow` or `deep`.\n-'Shallow' threading makes every mail a reply to the head of the\n+'shallow' threading makes every mail a reply to the head of the\n series, where the head is chosen from the cover letter, the\n-`\\--in-reply-to`, and the first patch mail, in this order.  'Deep'\n+`\\--in-reply-to`, and the first patch mail, in this order.  'deep'\n threading makes every mail a reply to the previous one.  If not\n specified, defaults to the 'format.thread' configuration, or `shallow`\n if that is not set.\n@@ -169,24 +169,24 @@ if that is not set.\n --suffix=.<sfx>::\n \tInstead of using `.patch` as the suffix for generated\n \tfilenames, use specified suffix.  A common alternative is\n-\t`--suffix=.txt`.\n+\t`--suffix=.txt`.  Leaving this empty will remove the `.patch`\n+\tsuffix.\n +\n-Note that you would need to include the leading dot `.` if you\n-want a filename like `0001-description-of-my-change.patch`, and\n-the first letter does not have to be a dot.  Leaving it empty would\n-not add any suffix.\n+Note the first letter is not required to be a dot, you will need to\n+include the leading dot `.` if you want a filename like\n+`0001-description-of-my-change.patch`.\n \n --no-binary::\n-\tDon't output contents of changes in binary files, just take note\n-\tthat they differ.  Note that this disable the patch to be properly\n-\tapplied.  By default the contents of changes in those files are\n-\tencoded in the patch.\n+\tDo not output contents of changes in binary files, instead\n+\tdisplay a notice that those files changed.  Patches generated\n+\tusing this option cannot be applied properly, but they are\n+\tstill useful for code review.\n \n CONFIGURATION\n -------------\n You can specify extra mail header lines to be added to each message\n-in the repository configuration, new defaults for the subject prefix\n-and file suffix, control attachements, and number patches when outputting\n+in the repository configuration, defaults for the subject prefix\n+and file suffix, configure attachments, and number patches when outputting\n more than one.\n \n ------------\n@@ -234,8 +234,8 @@ $ git format-patch -M -B origin\n +\n Additionally, it detects and handles renames and complete rewrites\n intelligently to produce a renaming patch.  A renaming patch reduces\n-the amount of text output, and generally makes it easier to review it.\n-Note that the \"patch\" program does not understand renaming patches, so\n+the amount of text output, and generally makes it easier to review.\n+Note that non-git \"patch\" programs won't understand renaming patches, so\n use it only when you know the recipient uses git to apply your patch.\n \n * Extract three topmost commits from the current branch and format them\n-- \n1.6.2\n"},{"id":"109252","messageId":"20090324220913.GN19389@fieldses.org","threadId":"18483","inReplyTo":"1237803683-14939-1-git-send-email-bebarino@gmail.com","subject":"Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2009-03-24T22:09:13Z","receivedAt":"2009-03-24T22:09:13Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Mon, Mar 23, 2009 at 03:21:23AM -0700, Stephen Boyd wrote:\n> Clarify --no-binary description using some words from the original\n> commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix and\n> --thread descriptions. Add --thread style option to synopsis. Clarify\n> renaming patches example.\n> \n> Signed-off-by: Stephen Boyd <bebarino@gmail.com>\n> ---\n> Is the synopsis getting too heavy? Maybe it should be changed to:\n> \n>     git format-patch [<options>] [<common diff options>] [<revision range>]\n> \n>  Documentation/git-format-patch.txt |   34 +++++++++++++++++-----------------\n>  1 files changed, 17 insertions(+), 17 deletions(-)\n> \n> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\n> index c2eb5fa..f31098b 100644\n> --- a/Documentation/git-format-patch.txt\n> +++ b/Documentation/git-format-patch.txt\n> @@ -9,9 +9,9 @@ git-format-patch - Prepare patches for e-mail submission\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git format-patch' [-k] [-o <dir> | --stdout] [--thread]\n> +'git format-patch' [-k] [-o <dir> | --stdout] [--thread[=<style>]]\n>  \t\t   [--attach[=<boundary>] | --inline[=<boundary>] |\n> -\t\t     [--no-attach]]\n> +\t\t    --no-attach]\n>  \t\t   [-s | --signoff] [<common diff options>]\n>  \t\t   [-n | --numbered | -N | --no-numbered]\n>  \t\t   [--start-number <n>] [--numbered-files]\n> @@ -132,9 +132,9 @@ include::diff-options.txt[]\n>  \tthe Message-Id header to reference.\n>  +\n>  The optional <style> argument can be either `shallow` or `deep`.\n> -'Shallow' threading makes every mail a reply to the head of the\n> +'shallow' threading makes every mail a reply to the head of the\n>  series, where the head is chosen from the cover letter, the\n> -`\\--in-reply-to`, and the first patch mail, in this order.  'Deep'\n> +`\\--in-reply-to`, and the first patch mail, in this order.  'deep'\n>  threading makes every mail a reply to the previous one.  If not\n>  specified, defaults to the 'format.thread' configuration, or `shallow`\n>  if that is not set.\n> @@ -169,24 +169,24 @@ if that is not set.\n>  --suffix=.<sfx>::\n>  \tInstead of using `.patch` as the suffix for generated\n>  \tfilenames, use specified suffix.  A common alternative is\n> -\t`--suffix=.txt`.\n> +\t`--suffix=.txt`.  Leaving this empty will remove the `.patch`\n> +\tsuffix.\n>  +\n> -Note that you would need to include the leading dot `.` if you\n> -want a filename like `0001-description-of-my-change.patch`, and\n> -the first letter does not have to be a dot.  Leaving it empty would\n> -not add any suffix.\n> +Note the first letter is not required to be a dot, you will need to\n> +include the leading dot `.` if you want a filename like\n> +`0001-description-of-my-change.patch`.\n\nThat's a comma-splice, trivially fixed by changing \"dot, you\" to \"dot;\nyou\".\n\nBetter?: \"Note that the leading dot isn't actually required if you don't\nwant a dot between the patch name and the suffix.\"\n\n(Though personally I'd strike the whole sentence, since a) probably\nnobody cares, and b) the 1 in a million person that does actually want\nto do this can figure it out easily enough on their own with a quick\ntest.)\n\n--b.\n\n>  \n>  --no-binary::\n> -\tDon't output contents of changes in binary files, just take note\n> -\tthat they differ.  Note that this disable the patch to be properly\n> -\tapplied.  By default the contents of changes in those files are\n> -\tencoded in the patch.\n> +\tDo not output contents of changes in binary files, instead\n> +\tdisplay a notice that those files changed.  Patches generated\n> +\tusing this option cannot be applied properly, but they are\n> +\tstill useful for code review.\n>  \n>  CONFIGURATION\n>  -------------\n>  You can specify extra mail header lines to be added to each message\n> -in the repository configuration, new defaults for the subject prefix\n> -and file suffix, control attachements, and number patches when outputting\n> +in the repository configuration, defaults for the subject prefix\n> +and file suffix, configure attachments, and number patches when outputting\n>  more than one.\n>  \n>  ------------\n> @@ -234,8 +234,8 @@ $ git format-patch -M -B origin\n>  +\n>  Additionally, it detects and handles renames and complete rewrites\n>  intelligently to produce a renaming patch.  A renaming patch reduces\n> -the amount of text output, and generally makes it easier to review it.\n> -Note that the \"patch\" program does not understand renaming patches, so\n> +the amount of text output, and generally makes it easier to review.\n> +Note that non-git \"patch\" programs won't understand renaming patches, so\n>  use it only when you know the recipient uses git to apply your patch.\n>  \n>  * Extract three topmost commits from the current branch and format them\n> -- \n> 1.6.2\n> \n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at  http://vger.kernel.org/majordomo-info.html\n"},{"id":"109268","messageId":"780e0a6b0903241636j4749daf3xddb6e4c200c00820@mail.gmail.com","threadId":"18483","inReplyTo":"20090324220913.GN19389@fieldses.org","subject":"Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2009-03-24T23:36:15Z","receivedAt":"2009-03-24T23:36:15Z","isPatch":true,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"On Tue, Mar 24, 2009 at 3:09 PM, J. Bruce Fields <bfields@fieldses.org> wrote:\n> On Mon, Mar 23, 2009 at 03:21:23AM -0700, Stephen Boyd wrote:\n>>  +\n>> -Note that you would need to include the leading dot `.` if you\n>> -want a filename like `0001-description-of-my-change.patch`, and\n>> -the first letter does not have to be a dot.  Leaving it empty would\n>> -not add any suffix.\n>> +Note the first letter is not required to be a dot, you will need to\n>> +include the leading dot `.` if you want a filename like\n>> +`0001-description-of-my-change.patch`.\n>\n> That's a comma-splice, trivially fixed by changing \"dot, you\" to \"dot;\n> you\".\n>\n> Better?: \"Note that the leading dot isn't actually required if you don't\n> want a dot between the patch name and the suffix.\"\n>\n> (Though personally I'd strike the whole sentence, since a) probably\n> nobody cares, and b) the 1 in a million person that does actually want\n> to do this can figure it out easily enough on their own with a quick\n> test.)\n>\n> --b.\n>\n\nI don't think documentation is meant to point the user to trial and\nerror. Even if the error is fairly harmless. Although you could be\nright that nobody cares.\n\nHow about a sentence with no negation?\n\n\"Note that the leading dot is required if you want a dot between the\npatch name and the suffix.\"\n"},{"id":"109270","messageId":"20090324235331.GC19389@fieldses.org","threadId":"18483","inReplyTo":"780e0a6b0903241636j4749daf3xddb6e4c200c00820@mail.gmail.com","subject":"Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2009-03-24T23:53:31Z","receivedAt":"2009-03-24T23:53:31Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Tue, Mar 24, 2009 at 04:36:15PM -0700, Stephen Boyd wrote:\n> On Tue, Mar 24, 2009 at 3:09 PM, J. Bruce Fields <bfields@fieldses.org> wrote:\n> > On Mon, Mar 23, 2009 at 03:21:23AM -0700, Stephen Boyd wrote:\n> >>  +\n> >> -Note that you would need to include the leading dot `.` if you\n> >> -want a filename like `0001-description-of-my-change.patch`, and\n> >> -the first letter does not have to be a dot.  Leaving it empty would\n> >> -not add any suffix.\n> >> +Note the first letter is not required to be a dot, you will need to\n> >> +include the leading dot `.` if you want a filename like\n> >> +`0001-description-of-my-change.patch`.\n> >\n> > That's a comma-splice, trivially fixed by changing \"dot, you\" to \"dot;\n> > you\".\n> >\n> > Better?: \"Note that the leading dot isn't actually required if you don't\n> > want a dot between the patch name and the suffix.\"\n> >\n> > (Though personally I'd strike the whole sentence, since a) probably\n> > nobody cares, and b) the 1 in a million person that does actually want\n> > to do this can figure it out easily enough on their own with a quick\n> > test.)\n> >\n> > --b.\n> >\n> \n> I don't think documentation is meant to point the user to trial and\n> error. Even if the error is fairly harmless. Although you could be\n> right that nobody cares.\n> \n> How about a sentence with no negation?\n> \n> \"Note that the leading dot is required if you want a dot between the\n> patch name and the suffix.\"\n\nSure!\n\n--b.\n"},{"id":"109271","messageId":"7vskl2tr00.fsf@gitster.siamese.dyndns.org","threadId":"18483","inReplyTo":"780e0a6b0903241636j4749daf3xddb6e4c200c00820@mail.gmail.com","subject":"Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-03-24T23:55:59Z","receivedAt":"2009-03-24T23:55:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stephen Boyd <bebarino@gmail.com> writes:\n\n> How about a sentence with no negation?\n>\n> \"Note that the leading dot is required if you want a dot between the\n> patch name and the suffix.\"\n\nHow about a sentence that does not sound requirement but freedom?\n\n\"The leading character does not have to be a dot; for example, you\ncan use --suffix=-patch to get 0001-description-of-my-change-patch\".\n"},{"id":"109318","messageId":"780e0a6b0903242321q252c4b44k3909bd79003ded6b@mail.gmail.com","threadId":"18483","inReplyTo":"7vskl2tr00.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2009-03-25T06:21:22Z","receivedAt":"2009-03-25T06:21:22Z","isPatch":true,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"On Tue, Mar 24, 2009 at 4:55 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> Stephen Boyd <bebarino@gmail.com> writes:\n>\n>> How about a sentence with no negation?\n>>\n>> \"Note that the leading dot is required if you want a dot between the\n>> patch name and the suffix.\"\n>\n> How about a sentence that does not sound requirement but freedom?\n>\n> \"The leading character does not have to be a dot; for example, you\n> can use --suffix=-patch to get 0001-description-of-my-change-patch\".\n\nLooks even better. Do we still want to start off by saying \"Note that the...\" ?\n"},{"id":"109326","messageId":"7vhc1i83m5.fsf@gitster.siamese.dyndns.org","threadId":"18483","inReplyTo":"780e0a6b0903242321q252c4b44k3909bd79003ded6b@mail.gmail.com","subject":"Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-03-25T07:26:42Z","receivedAt":"2009-03-25T07:26:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stephen Boyd <bebarino@gmail.com> writes:\n\n> On Tue, Mar 24, 2009 at 4:55 PM, Junio C Hamano <gitster@pobox.com> wrote:\n>> Stephen Boyd <bebarino@gmail.com> writes:\n>>\n>>> How about a sentence with no negation?\n>>>\n>>> \"Note that the leading dot is required if you want a dot between the\n>>> patch name and the suffix.\"\n>>\n>> How about a sentence that does not sound requirement but freedom?\n>>\n>> \"The leading character does not have to be a dot; for example, you\n>> can use --suffix=-patch to get 0001-description-of-my-change-patch\".\n>\n> Looks even better. Do we still want to start off by saying \"Note that the...\" ?\n\nPerhaps; I wasn't paying much attention to the whole sentence, but was\nprimarily interested about giving the description less negative\nconnotation.\n"}]}