[PATCH 0/3] git-am documentation

[PATCH 0/3] git-am documentation

[Stephen Boyd]

The first two are minor grammatical fixes. I'm interested in what
people think about patch 3.

Stephen Boyd (3):
  git-am.txt: add an 'a', say what 'it' is, simplify a sentence
  git-am.txt: Use date instead of time or timestamp
  git-am.txt: reword extra headers in message body

 Documentation/git-am.txt |   24 ++++++++++++------------
 1 files changed, 12 insertions(+), 12 deletions(-)

[PATCH 1/3] git-am.txt: add an 'a', say what 'it' is, simplify a sentence

[Stephen Boyd]

It's nice to know that 'it' is git-am or the subject line. Whitespace
implies characters so just remove characters.

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/git-am.txt |   12 ++++++------
 1 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 1e71dd5..715531b 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -32,7 +32,7 @@ OPTIONS
 
 -s::
 --signoff::
-	Add `Signed-off-by:` line to the commit message, using
+	Add a `Signed-off-by:` line to the commit message, using
 	the committer identity of yourself.
 
 -k::
@@ -118,8 +118,8 @@ The commit author name is taken from the "From: " line of the
 message, and commit author time is taken from the "Date: " line
 of the message.  The "Subject: " line is used as the title of
 the commit, after stripping common prefix "[PATCH <anything>]".
-It is supposed to describe what the commit is about concisely as
-a one line text.
+The "Subject: " line is supposed to concisely describe what the
+commit is about in one line of text.
 
 The body of the message (the rest of the message after the blank line
 that terminates the RFC2822 headers) can begin with "Subject: " and
@@ -128,8 +128,8 @@ to override the values of these fields.
 
 The commit message is formed by the title taken from the
 "Subject: ", a blank line and the body of the message up to
-where the patch begins.  Excess whitespace characters at the end of the
-lines are automatically stripped.
+where the patch begins.  Excess whitespace at the end of each
+line is automatically stripped.
 
 The patch is expected to be inline, directly following the
 message.  Any line that is of the form:
@@ -141,7 +141,7 @@ message.  Any line that is of the form:
 is taken as the beginning of a patch, and the commit log message
 is terminated before the first occurrence of such a line.
 
-When initially invoking it, you give it the names of the mailboxes
+When initially invoking 'git-am', you give it the names of the mailboxes
 to process.  Upon seeing the first patch that does not apply, it
 aborts in the middle.  You can recover from this in one of two ways:
 
-- 
1.6.2.3

[PATCH 2/3] git-am.txt: Use date instead of time or timestamp

[Stephen Boyd]

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/git-am.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 715531b..c141261 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -85,7 +85,7 @@ default.   You can use `--no-utf8` to override this.
 	By default the command records the date from the e-mail
 	message as the commit author date, and uses the time of
 	commit creation as the committer date. This allows the
-	user to lie about author timestamp by using the same
+	user to lie about the author date by using the same
 	timestamp as the committer date.
 
 --skip::
@@ -115,7 +115,7 @@ DISCUSSION
 ----------
 
 The commit author name is taken from the "From: " line of the
-message, and commit author time is taken from the "Date: " line
+message, and commit author date is taken from the "Date: " line
 of the message.  The "Subject: " line is used as the title of
 the commit, after stripping common prefix "[PATCH <anything>]".
 The "Subject: " line is supposed to concisely describe what the
-- 
1.6.2.3

[PATCH 3/3] git-am.txt: reword extra headers in message body

[Stephen Boyd]

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/git-am.txt |    8 ++++----
 1 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index c141261..95e6089 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -121,10 +121,10 @@ the commit, after stripping common prefix "[PATCH <anything>]".
 The "Subject: " line is supposed to concisely describe what the
 commit is about in one line of text.
 
-The body of the message (the rest of the message after the blank line
-that terminates the RFC2822 headers) can begin with "Subject: " and
-"From: " lines that are different from those of the mail header,
-to override the values of these fields.
+"From: " and "Subject: " lines starting the body (the rest of the
+message after the blank line terminating the RFC2822 headers)
+override the respective commit author name and title values taken
+from the headers.
 
 The commit message is formed by the title taken from the
 "Subject: ", a blank line and the body of the message up to
-- 
1.6.2.3

Re: [PATCH 2/3] git-am.txt: Use date instead of time or timestamp

[Jeff King]

On Sun, May 03, 2009 at 11:46:57PM -0700, Stephen Boyd wrote:

> diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
> index 715531b..c141261 100644
> --- a/Documentation/git-am.txt
> +++ b/Documentation/git-am.txt
> @@ -85,7 +85,7 @@ default.   You can use `--no-utf8` to override this.
>  	By default the command records the date from the e-mail
>  	message as the commit author date, and uses the time of
>  	commit creation as the committer date. This allows the
> -	user to lie about author timestamp by using the same
> +	user to lie about the author date by using the same
>  	timestamp as the committer date.

But you leave the "timestamp" in the next context line?

The other two patches in the series look fine to me, though.

-Peff

Re: [PATCH 2/3] git-am.txt: Use date instead of time or timestamp

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Sun, May 03, 2009 at 11:46:57PM -0700, Stephen Boyd wrote:
>
>> diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
>> index 715531b..c141261 100644
>> --- a/Documentation/git-am.txt
>> +++ b/Documentation/git-am.txt
>> @@ -85,7 +85,7 @@ default.   You can use `--no-utf8` to override this.
>>  	By default the command records the date from the e-mail
>>  	message as the commit author date, and uses the time of
>>  	commit creation as the committer date. This allows the
>> -	user to lie about author timestamp by using the same
>> +	user to lie about the author date by using the same
>>  	timestamp as the committer date.
>
> But you leave the "timestamp" in the next context line?
>
> The other two patches in the series look fine to me, though.

Likewise.  Perhaps "using the same value as the committer date" sounds
better?

Re: [PATCH 2/3] git-am.txt: Use date instead of time or timestamp

[Jeff King]

On Mon, May 04, 2009 at 12:23:52AM -0700, Junio C Hamano wrote:

> >>  	commit creation as the committer date. This allows the
> >> -	user to lie about author timestamp by using the same
> >> +	user to lie about the author date by using the same
> >>  	timestamp as the committer date.
> >
> > But you leave the "timestamp" in the next context line?
> >
> > The other two patches in the series look fine to me, though.
> 
> Likewise.  Perhaps "using the same value as the committer date" sounds
> better?

Much better IMHO.

-Peff

Re: [PATCH 1/3] git-am.txt: add an 'a', say what 'it' is, simplify a sentence

[Michael J Gruber]

Stephen Boyd venit, vidit, dixit 04.05.2009 08:46:
> It's nice to know that 'it' is git-am or the subject line. Whitespace
> implies characters so just remove characters.
> 
> Signed-off-by: Stephen Boyd <bebarino@gmail.com>
> ---
>  Documentation/git-am.txt |   12 ++++++------
>  1 files changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
> index 1e71dd5..715531b 100644
> --- a/Documentation/git-am.txt
> +++ b/Documentation/git-am.txt
> @@ -32,7 +32,7 @@ OPTIONS
>  
>  -s::
>  --signoff::
> -	Add `Signed-off-by:` line to the commit message, using
> +	Add a `Signed-off-by:` line to the commit message, using
>  	the committer identity of yourself.
>  
>  -k::
> @@ -118,8 +118,8 @@ The commit author name is taken from the "From: " line of the
>  message, and commit author time is taken from the "Date: " line
>  of the message.  The "Subject: " line is used as the title of
>  the commit, after stripping common prefix "[PATCH <anything>]".
> -It is supposed to describe what the commit is about concisely as
> -a one line text.
> +The "Subject: " line is supposed to concisely describe what the
> +commit is about in one line of text.
>  
>  The body of the message (the rest of the message after the blank line
>  that terminates the RFC2822 headers) can begin with "Subject: " and
> @@ -128,8 +128,8 @@ to override the values of these fields.
>  
>  The commit message is formed by the title taken from the
>  "Subject: ", a blank line and the body of the message up to
> -where the patch begins.  Excess whitespace characters at the end of the
> -lines are automatically stripped.
> +where the patch begins.  Excess whitespace at the end of each
> +line is automatically stripped.
>  
>  The patch is expected to be inline, directly following the
>  message.  Any line that is of the form:
> @@ -141,7 +141,7 @@ message.  Any line that is of the form:
>  is taken as the beginning of a patch, and the commit log message
>  is terminated before the first occurrence of such a line.
>  
> -When initially invoking it, you give it the names of the mailboxes
> +When initially invoking 'git-am', you give it the names of the mailboxes

We try to spell git commands in the form 'git am' these days. Also, `git
am` should be the quoting for commands, although we don't have a style
guide and things are not consistent anyways.

>  to process.  Upon seeing the first patch that does not apply, it
>  aborts in the middle.  You can recover from this in one of two ways:
>