From: Stephen Boyd <hidden> Date: 2016-06-15 22:46:38
I've tried to order these from least to most controversial.
The first 3 are small fixups. The fourth patch is a quoting fixup. The
fifth patch is a patch I sent a few weeks ago which flew under the radar.
The last 3 patches are some updates to the config.txt documentation.
I've split them up into seperate patches so they can easily be left out
if not wanted.
Stephen Boyd (8):
config.txt: remove pointer to SubmittingPatches
config.txt: add missing format.{subjectprefix,cc,attach} variables
Documentation: use lowercase for shallow and deep threading
git-show-branch.txt: cleanup example description
git-format-patch.txt: general rewordings and cleanups
config.txt: add missing 'the's and make words plural
config.txt: clarify sentences in the configuration and syntax sections
config.txt: Make configuration paragraph more consistent
Documentation/config.txt | 68 +++++++++++++++++++++--------------
Documentation/git-format-patch.txt | 42 +++++++++++-----------
Documentation/git-show-branch.txt | 7 ++--
3 files changed, 66 insertions(+), 51 deletions(-)
From: Stephen Boyd <hidden> Date: 2016-06-15 22:46:38
SubmittingPatches exists in the git source documentation for developers
of git and is not included in the man/html page distributions.
Signed-off-by: Stephen Boyd <redacted>
---
Documentation/config.txt | 1 -
1 files changed, 0 insertions(+), 1 deletions(-)
@@ -743,7 +743,6 @@ format.signoff:: format-patch by default. *Note:* Adding the Signed-off-by: line to a patch should be a conscious act and means that you certify you have the rights to submit this work under the same open source license.- Please see the 'SubmittingPatches' document for further discussion. gc.aggressiveWindow:: The window size parameter used in the delta compression
@@ -707,6 +707,13 @@ fetch.unpackLimit:: especially on slow filesystems. If not set, the value of `transfer.unpackLimit` is used instead.+format.attach::+ Enable multipart/mixed attachments as the default for+ 'format-patch'. The value can also be a double quoted string+ which will enable attachments as the default and set the+ value as the boundary. See the --attach option in+ linkgit:git-format-patch[1].+ format.numbered:: A boolean which can enable or disable sequence numbers in patch subjects. It defaults to "auto" which enables it only if there
@@ -718,6 +725,14 @@ format.headers:: Additional email headers to include in a patch to be submitted by mail. See linkgit:git-format-patch[1].+format.cc::+ Additional "Cc:" headers to include in a patch to be submitted+ by mail. See the --cc option in linkgit:git-format-patch[1].++format.subjectprefix::+ The default for format-patch is to output files with the '[PATCH]'+ subject prefix. Use this variable to change that prefix.+ format.suffix:: The default for format-patch is to output files with the suffix `.patch`. Use this variable to change that suffix (make sure to
From: Stephen Boyd <hidden> Date: 2016-06-15 22:46:38
Even when a sentence is started with 'shallow' or 'deep' use the
lowercase version to maintain consistency.
Signed-off-by: Stephen Boyd <redacted>
---
Documentation/config.txt | 4 ++--
Documentation/git-format-patch.txt | 4 ++--
2 files changed, 4 insertions(+), 4 deletions(-)
@@ -745,11 +745,11 @@ format.pretty:: format.thread:: The default threading style for 'git-format-patch'. Can be- either a boolean value, `shallow` or `deep`. 'Shallow'+ either a boolean value, `shallow` or `deep`. `shallow` threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the `\--in-reply-to`, and the first patch mail, in this order.- 'Deep' threading makes every mail a reply to the previous one.+ `deep` threading makes every mail a reply to the previous one. A true boolean value is the same as `shallow`, and a false value disables threading.
@@ -128,9 +128,9 @@ include::diff-options.txt[] the Message-Id header to reference. + The optional <style> argument can be either `shallow` or `deep`.-'Shallow' threading makes every mail a reply to the head of the+'shallow' threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the-`\--in-reply-to`, and the first patch mail, in this order. 'Deep'+`\--in-reply-to`, and the first patch mail, in this order. 'deep' threading makes every mail a reply to the previous one. If not specified, defaults to the 'format.thread' configuration, or `shallow` if that is not set.
From: Stephen Boyd <hidden> Date: 2016-06-15 22:46:38
Add a missing quote and properly escape the ' character so docs don't
look odd. Add 'the' to make some sentences more gramatically correct.
Signed-off-by: Stephen Boyd <redacted>
---
Documentation/git-show-branch.txt | 7 ++++---
1 files changed, 4 insertions(+), 3 deletions(-)
@@ -148,9 +148,10 @@ $ git show-branch master fixes mhf ------------------------------------------------ These three branches all forked from a common commit, [master],-whose commit message is "Add 'git show-branch'. "fixes" branch-adds one commit 'Introduce "reset type"'. "mhf" branch has many-other commits. The current branch is "master".+whose commit message is "Add \'git show-branch\'". The "fixes"+branch adds one commit "Introduce "reset type" flag to "git reset"".+The "mhf" branch adds many other commits. The current branch+is "master". EXAMPLE
@@ -8,9 +8,9 @@ is used to store the information for that repository, and fallback values for the `.git/config` file. The file `/etc/gitconfig` can be used to store system-wide defaults.-They can be used by both the git plumbing-and the porcelains. The variables are divided into sections, where-in the fully qualified variable name the variable itself is the last+The configuration variables are used by both the git plumbing+and the porcelains. The variables are divided into sections, wherein+the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last dot. The variable names are case-insensitive and only alphanumeric characters are allowed. Some variables may appear multiple times.
@@ -38,9 +38,9 @@ in the section header, like in the example below: ---------Subsection names can contain any character except newline (doublequote-`"` and backslash have to be escaped as `\"` and `\\`,-respectively) and are case sensitive. Section headers cannot span multiple+Subsection names are case sensitive and can contain any characters except+newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`,+respectively). Section headers cannot span multiple lines. Variables may belong directly to a section or to a given subsection. You can have `[section]` if you have `[section "subsection"]`, but you don't need to.
From: Stephen Boyd <hidden> Date: 2016-06-15 22:46:38
Clarify --no-binary description using some words from the original
commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix
description. Add --thread style option to synopsis and reorganize it a
bit. Clarify renaming patches example and the configuration paragraph.
Signed-off-by: Stephen Boyd <redacted>
---
Documentation/git-format-patch.txt | 38 ++++++++++++++++++------------------
1 files changed, 19 insertions(+), 19 deletions(-)
@@ -170,18 +171,17 @@ if that is not set. --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is- `--suffix=.txt`.+ `--suffix=.txt`. Leaving this empty will remove the `.patch`+ suffix. +-Note that you would need to include the leading dot `.` if you-want a filename like `0001-description-of-my-change.patch`, and-the first letter does not have to be a dot. Leaving it empty would-not add any suffix.+Note the leading character does not have to be a dot; for example, you+can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. --no-binary::- Don't output contents of changes in binary files, just take note- that they differ. Note that this disable the patch to be properly- applied. By default the contents of changes in those files are- encoded in the patch.+ Do not output contents of changes in binary files, instead+ display a notice that those files changed. Patches generated+ using this option cannot be applied properly, but they are+ still useful for code review. --root:: Treat the revision argument as a <revision range>, even if it
@@ -192,10 +192,10 @@ not add any suffix. CONFIGURATION --------------You can specify extra mail header lines to be added to each message-in the repository configuration, new defaults for the subject prefix-and file suffix, control attachments, and number patches when outputting-more than one.+You can specify extra mail header lines to be added to each message,+defaults for the subject prefix and file suffix, number patches when+outputting more than one patch, add "Cc:" headers, configure attachments,+and signoff patches with configuration variables. ------------ [format]
@@ -243,8 +243,8 @@ $ git format-patch -M -B origin + Additionally, it detects and handles renames and complete rewrites intelligently to produce a renaming patch. A renaming patch reduces-the amount of text output, and generally makes it easier to review it.-Note that the "patch" program does not understand renaming patches, so+the amount of text output, and generally makes it easier to review.+Note that non-git "patch" programs won't understand renaming patches, so use it only when you know the recipient uses git to apply your patch. * Extract three topmost commits from the current branch and format them
From: Stephen Boyd <hidden> Date: 2016-06-15 22:46:38
By renaming 'information' to 'configuration' we capture more clearly
what a configuration file holds.
Signed-off-by: Stephen Boyd <redacted>
---
Documentation/config.txt | 6 +++---
1 files changed, 3 insertions(+), 3 deletions(-)
@@ -3,10 +3,10 @@ CONFIGURATION FILE The git configuration file contains a number of variables that affect the git command's behavior. The `.git/config` file in each repository-is used to store the information for that repository, and-`$HOME/.gitconfig` is used to store per user information as+is used to store the configuration for that repository, and+`$HOME/.gitconfig` is used to store a per-user configuration as fallback values for the `.git/config` file. The file `/etc/gitconfig`-can be used to store system-wide defaults.+can be used to store a system-wide default configuration. The configuration variables are used by both the git plumbing and the porcelains. The variables are divided into sections, wherein
@@ -2,10 +2,10 @@ CONFIGURATION FILE ------------------ The git configuration file contains a number of variables that affect-the git command's behavior. `.git/config` file for each repository+the git command's behavior. The `.git/config` file in each repository is used to store the information for that repository, and-`$HOME/.gitconfig` is used to store per user information to give-fallback values for `.git/config` file. The file `/etc/gitconfig`+`$HOME/.gitconfig` is used to store per user information as+fallback values for the `.git/config` file. The file `/etc/gitconfig` can be used to store system-wide defaults. They can be used by both the git plumbing
@@ -26,28 +26,28 @@ The file consists of sections and variables. A section begins with the name of the section in square brackets and continues until the next section begins. Section names are not case sensitive. Only alphanumeric characters, `-` and `.` are allowed in section names. Each variable-must belong to some section, which means that there must be section-header before first setting of a variable.+must belong to some section, which means that there must be a section+header before the first setting of a variable. Sections can be further divided into subsections. To begin a subsection put its name in double quotes, separated by space from the section name,-in the section header, like in example below:+in the section header, like in the example below: -------- [section "subsection"] ---------Subsection names can contain any characters except newline (doublequote+Subsection names can contain any character except newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`,-respectively) and are case sensitive. Section header cannot span multiple+respectively) and are case sensitive. Section headers cannot span multiple lines. Variables may belong directly to a section or to a given subsection. You can have `[section]` if you have `[section "subsection"]`, but you don't need to.-There is also (case insensitive) alternative `[section.subsection]` syntax.-In this syntax subsection names follow the same restrictions as for section-name.+There is also a case insensitive alternative `[section.subsection]` syntax.+In this syntax, subsection names follow the same restrictions as for section+names. All the other lines are recognized as setting variables, in the form 'name = value'. If there is no equal sign on the line, the entire line
@@ -66,10 +66,10 @@ converting value to the canonical form using '--bool' type specifier; 'git-config' will ensure that the output is "true" or "false". String values may be entirely or partially enclosed in double quotes.-You need to enclose variable value in double quotes if you want to-preserve leading or trailing whitespace, or if variable value contains-beginning of comment characters (if it contains '#' or ';').-Double quote `"` and backslash `\` characters in variable value must+You need to enclose variable values in double quotes if you want to+preserve leading or trailing whitespace, or if the variable value contains+comment characters (i.e. it contains '#' or ';').+Double quote `"` and backslash `\` characters in variable values must be escaped: use `\"` for `"` and `\\` for `\`. The following escape sequences (beside `\"` and `\\`) are recognized:
@@ -77,10 +77,10 @@ The following escape sequences (beside `\"` and `\\`) are recognized: and `\b` for backspace (BS). No other char escape sequence, nor octal char sequences are valid.-Variable value ending in a `\` is continued on the next line in the+Variable values ending in a `\` are continued on the next line in the customary UNIX fashion.-Some variables may require special value format.+Some variables may require a special value format. Example ~~~~~~~
From: Michael J Gruber <hidden> Date: 2016-06-15 22:46:38
Stephen Boyd venit, vidit, dixit 23.04.2009 11:37:
quoted hunk
SubmittingPatches exists in the git source documentation for developers
of git and is not included in the man/html page distributions.
Signed-off-by: Stephen Boyd <redacted>
---
Documentation/config.txt | 1 -
1 files changed, 0 insertions(+), 1 deletions(-)
@@ -743,7 +743,6 @@ format.signoff:: format-patch by default. *Note:* Adding the Signed-off-by: line to a patch should be a conscious act and means that you certify you have the rights to submit this work under the same open source license.- Please see the 'SubmittingPatches' document for further discussion.
Shouldn't we point to the source then? We're not talking about links
here, only references in the sense of referring to further reading.
gc.aggressiveWindow::
The window size parameter used in the delta compression
From: Michael J Gruber <hidden> Date: 2016-06-15 22:46:38
Stephen Boyd venit, vidit, dixit 23.04.2009 11:37:
quoted hunk
Clarify --no-binary description using some words from the original
commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix
description. Add --thread style option to synopsis and reorganize it a
bit. Clarify renaming patches example and the configuration paragraph.
Signed-off-by: Stephen Boyd <redacted>
---
Documentation/git-format-patch.txt | 38 ++++++++++++++++++------------------
1 files changed, 19 insertions(+), 19 deletions(-)
@@ -170,18 +171,17 @@ if that is not set. --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is- `--suffix=.txt`.+ `--suffix=.txt`. Leaving this empty will remove the `.patch`+ suffix. +
Those asciidoc constructs in diff make me always wonder "Huh? A merge
diff -cc?"... It's fine, of course.
-Note that you would need to include the leading dot `.` if you
-want a filename like `0001-description-of-my-change.patch`, and
-the first letter does not have to be a dot. Leaving it empty would
-not add any suffix.
+Note the leading character does not have to be a dot; for example, you
Maybe "Note that the" sounds and reads better.
quoted hunk
+can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
--no-binary::
- Don't output contents of changes in binary files, just take note
- that they differ. Note that this disable the patch to be properly
- applied. By default the contents of changes in those files are
- encoded in the patch.
+ Do not output contents of changes in binary files, instead
+ display a notice that those files changed. Patches generated
+ using this option cannot be applied properly, but they are
+ still useful for code review.
--root::
Treat the revision argument as a <revision range>, even if it
@@ -192,10 +192,10 @@ not add any suffix. CONFIGURATION --------------You can specify extra mail header lines to be added to each message-in the repository configuration, new defaults for the subject prefix-and file suffix, control attachments, and number patches when outputting-more than one.+You can specify extra mail header lines to be added to each message,+defaults for the subject prefix and file suffix, number patches when+outputting more than one patch, add "Cc:" headers, configure attachments,+and signoff patches with configuration variables.
"sign off"
quoted hunk
------------
[format]
@@ -243,8 +243,8 @@ $ git format-patch -M -B origin + Additionally, it detects and handles renames and complete rewrites intelligently to produce a renaming patch. A renaming patch reduces-the amount of text output, and generally makes it easier to review it.-Note that the "patch" program does not understand renaming patches, so+the amount of text output, and generally makes it easier to review.+Note that non-git "patch" programs won't understand renaming patches, so use it only when you know the recipient uses git to apply your patch. * Extract three topmost commits from the current branch and format them
Looks nice overall, especially the ones I'm not replying to ;)
Michael
From: Stephen Boyd <hidden> Date: 2016-06-15 22:46:39
Michael J Gruber wrote:
Stephen Boyd venit, vidit, dixit 23.04.2009 11:37:
quoted
SubmittingPatches exists in the git source documentation for developers
of git and is not included in the man/html page distributions.
Signed-off-by: Stephen Boyd <redacted>
---
Documentation/config.txt | 1 -
1 files changed, 0 insertions(+), 1 deletions(-)
@@ -743,7 +743,6 @@ format.signoff:: format-patch by default. *Note:* Adding the Signed-off-by: line to a patch should be a conscious act and means that you certify you have the rights to submit this work under the same open source license.- Please see the 'SubmittingPatches' document for further discussion.
Shouldn't we point to the source then? We're not talking about links
here, only references in the sense of referring to further reading.
I was thinking that a user isn't going to download the source for git so
they can read the SubmittingPatches document. Although, it's possible
they downloaded the tarball and built from source so they would have the
file.
Now I'm starting to dislike this whole paragraph because git isn't used
exclusively for open source software. Seems like others agree with a
little searching of gmane[1]
I think Andreas Ericsson's version with Jeff King's updates would be good.
Junio, I would say drop this patch.
[1] http://thread.gmane.org/gmane.comp.version-control.git/115299
From: Stephen Boyd <hidden> Date: 2016-06-15 22:46:39
Clarify --no-binary description using some words from the original
commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix
description. Add --thread style option to synopsis and reorganize it a
bit. Clarify renaming patches example and the configuration paragraph.
Signed-off-by: Stephen Boyd <redacted>
---
Fix some issues brought up by Michael J Gruber
Documentation/git-format-patch.txt | 38 ++++++++++++++++++------------------
1 files changed, 19 insertions(+), 19 deletions(-)
@@ -170,18 +171,17 @@ if that is not set. --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is- `--suffix=.txt`.+ `--suffix=.txt`. Leaving this empty will remove the `.patch`+ suffix. +-Note that you would need to include the leading dot `.` if you-want a filename like `0001-description-of-my-change.patch`, and-the first letter does not have to be a dot. Leaving it empty would-not add any suffix.+Note that the leading character does not have to be a dot; for example,+you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. --no-binary::- Don't output contents of changes in binary files, just take note- that they differ. Note that this disable the patch to be properly- applied. By default the contents of changes in those files are- encoded in the patch.+ Do not output contents of changes in binary files, instead+ display a notice that those files changed. Patches generated+ using this option cannot be applied properly, but they are+ still useful for code review. --root:: Treat the revision argument as a <revision range>, even if it
@@ -192,10 +192,10 @@ not add any suffix. CONFIGURATION --------------You can specify extra mail header lines to be added to each message-in the repository configuration, new defaults for the subject prefix-and file suffix, control attachments, and number patches when outputting-more than one.+You can specify extra mail header lines to be added to each message,+defaults for the subject prefix and file suffix, number patches when+outputting more than one patch, add "Cc:" headers, configure attachments,+and sign off patches with configuration variables. ------------ [format]
@@ -243,8 +243,8 @@ $ git format-patch -M -B origin + Additionally, it detects and handles renames and complete rewrites intelligently to produce a renaming patch. A renaming patch reduces-the amount of text output, and generally makes it easier to review it.-Note that the "patch" program does not understand renaming patches, so+the amount of text output, and generally makes it easier to review.+Note that non-git "patch" programs won't understand renaming patches, so use it only when you know the recipient uses git to apply your patch. * Extract three topmost commits from the current branch and format them