[PATCH] improve doc heading for git-bisect

[PATCH] improve doc heading for git-bisect

[Robert Anderson]

>From 7af03a835b7311c501f2147e25f428642fc3acb7 Mon Sep 17 00:00:00 2001
From: Robert W. Anderson <rwa000@gmail.com>
Date: Fri, 6 Jun 2008 23:53:37 -0700
Subject: [PATCH] improve doc heading for git-bisect

Improve awkward heading in git-bisect documentation.

Signed-off-by: Robert W. Anderson <rwa000@gmail.com>
---
 Documentation/git-bisect.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index 37c7acb..3ea2527 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -129,8 +129,8 @@ $ git bisect replay that-file
 if you find later you made a mistake telling good/bad about a
 revision.
 
-Avoiding to test a commit
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Changing the revision to test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If in a middle of bisect session, you know what the bisect suggested
 to try next is not a good one to test (e.g. the change the commit
-- 
1.5.4.3

Re: [PATCH] improve doc heading for git-bisect

[Jakub Narebski]

rwa000@gmail.com (Robert Anderson) writes:

> From 7af03a835b7311c501f2147e25f428642fc3acb7 Mon Sep 17 00:00:00 2001

FYI this line is not necessary, and should be removed from
git-format-patch output when pasting it to your MUA.

> From: Robert W. Anderson <rwa000@gmail.com>
> Date: Fri, 6 Jun 2008 23:53:37 -0700
> Subject: [PATCH] improve doc heading for git-bisect

FYI the above isn't strictly necessary: if you have 'From:' header set
correctly you can simply set subject of email, and put in body the
rest of commit message and patch only, without extra mail-like
headers.

> Improve awkward heading in git-bisect documentation.
[...]
> -Avoiding to test a commit
> -~~~~~~~~~~~~~~~~~~~~~~~~~
> +Changing the revision to test
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
>  If in a middle of bisect session, you know what the bisect suggested
>  to try next is not a good one to test (e.g. the change the commit

It is, I guess, better, but is it the best heading?  What we want to
describe here is how to deal when bisect stops on commit which cannot
be tested (e.g. project does not compile).

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: [PATCH] improve doc heading for git-bisect

[Robert Anderson]

On Sat, Jun 7, 2008 at 2:22 AM, Jakub Narebski <jnareb@gmail.com> wrote:
> rwa000@gmail.com (Robert Anderson) writes:
>
>> From 7af03a835b7311c501f2147e25f428642fc3acb7 Mon Sep 17 00:00:00 2001
>
> FYI this line is not necessary, and should be removed from
> git-format-patch output when pasting it to your MUA.

Err, then shouldn't it be removed from format-patch, rather than
deleted manually every time format-patch is used?

>> From: Robert W. Anderson <rwa000@gmail.com>
>> Date: Fri, 6 Jun 2008 23:53:37 -0700
>> Subject: [PATCH] improve doc heading for git-bisect
>
> FYI the above isn't strictly necessary: if you have 'From:' header set
> correctly you can simply set subject of email, and put in body the
> rest of commit message and patch only, without extra mail-like
> headers.

Then remove them from format-patch, IMO.

>> Improve awkward heading in git-bisect documentation.
> [...]
>> -Avoiding to test a commit
>> -~~~~~~~~~~~~~~~~~~~~~~~~~
>> +Changing the revision to test
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>
>>  If in a middle of bisect session, you know what the bisect suggested
>>  to try next is not a good one to test (e.g. the change the commit
>
> It is, I guess, better, but is it the best heading?  What we want to
> describe here is how to deal when bisect stops on commit which cannot
> be tested (e.g. project does not compile).

I disagree. The situation you want to use this is more general than
that.  Maybe you could test it, but doing so would be a waste of time
because the commit is a trivial comment change.  In general, this
simply what you need to know when you want to change the revision
under test.

Bob

Re: [PATCH] improve doc heading for git-bisect

[Jakub Narebski]

On Sat, 7 Jun 2008, Robert Anderson wrote:
> On Sat, Jun 7, 2008 at 2:22 AM, Jakub Narebski <jnareb@gmail.com> wrote:
>> rwa000@gmail.com (Robert Anderson) writes:
>>
>>> From 7af03a835b7311c501f2147e25f428642fc3acb7 Mon Sep 17 00:00:00 2001
>>
>> FYI this line is not necessary, and should be removed from
>> git-format-patch output when pasting it to your MUA.
> 
> Err, then shouldn't it be removed from format-patch, rather than
> deleted manually every time format-patch is used?

It is needed, I think, for git-format-patch output to be in mbox format,
so you can just send it (for example using git-send-email), or make
your MUA open it.

If you copy'n'paste, or equivalently use "insert file", into body of
your message, this is not necessary and should be removed.

>>> From: Robert W. Anderson <rwa000@gmail.com>
>>> Date: Fri, 6 Jun 2008 23:53:37 -0700
>>> Subject: [PATCH] improve doc heading for git-bisect
>>
>> FYI the above isn't strictly necessary: if you have 'From:' header set
>> correctly you can simply set subject of email, and put in body the
>> rest of commit message and patch only, without extra mail-like
>> headers.
> 
> Then remove them from format-patch, IMO.

Well, the "Subject:" is neede to copy it to the email subject line
in your MUA.  If from differs from the account you send email from,
it should also be set or left in the body of message.

Besides, there are two conventions of sending patches to git mailing
list, used in slightly different circumstances.

1. Put "Subject:" in the email subject line, remove all headers,
   put comments to patch (those which do not belong in commit message
   itself, for example how the patch differs from previously sent
   version, etc.) between "---" and diffstat.

2. In the case when patch is response to longer thread, or the message
   body is much longer than commit message, you have the comments to
   patch or further part of discussion at beginning, then some kind
   of marker e.g. "-- >8 --" (scissors), but NOT "---" to mark beginning
   of commit, then commit message, including From: and Subject: lines.

In short: this information is sometimes needed.

>>> Improve awkward heading in git-bisect documentation.
>> [...]
>>> -Avoiding to test a commit
>>> -~~~~~~~~~~~~~~~~~~~~~~~~~
>>> +Changing the revision to test
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>
>>>  If in a middle of bisect session, you know what the bisect suggested
>>>  to try next is not a good one to test (e.g. the change the commit
>>
>> It is, I guess, better, but is it the best heading?  What we want to
>> describe here is how to deal when bisect stops on commit which cannot
>> be tested (e.g. project does not compile).
> 
> I disagree. The situation you want to use this is more general than
> that.  Maybe you could test it, but doing so would be a waste of time
> because the commit is a trivial comment change.  In general, this
> simply what you need to know when you want to change the revision
> under test.

Well, I don't have better idea on how to write short but precise header,
and your change is certainly better...

-- 
Jakub Narebski
Poland

Re: [PATCH] improve doc heading for git-bisect

[Junio C Hamano]

"Robert Anderson" <rwa000@gmail.com> writes:

> Err, then shouldn't it be removed from format-patch, rather than
> deleted manually every time format-patch is used?
> ...
> Then remove them from format-patch, IMO.

Everything Jakub said about the presentation is correct, and please take
hints by looking at patch postings by long timers on this list.

The output from the command is designed so that it _can_ be pasted into a
MUA edit buffer, but that's not the sole purpose.  It needs to resemble
mbox format for use of send-email, so when you paste into a context that
does not need some parts, it is your responsibility and common courtesy
for readers to remove them.

>>> Improve awkward heading in git-bisect documentation.
>> [...]
>>> -Avoiding to test a commit
>>> -~~~~~~~~~~~~~~~~~~~~~~~~~
>>> +Changing the revision to test
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>
>>>  If in a middle of bisect session, you know what the bisect suggested
>>>  to try next is not a good one to test (e.g. the change the commit
>>
>> It is, I guess, better, but is it the best heading?  What we want to
>> describe here is how to deal when bisect stops on commit which cannot
>> be tested (e.g. project does not compile).
>
> I disagree. The situation you want to use this is more general than
> that.  Maybe you could test it, but doing so would be a waste of time
> because the commit is a trivial comment change.  In general, this
> simply what you need to know when you want to change the revision
> under test.

I agree with your reasoning.  Being able to test a different commit than
the suggested one is a useful feature of bisect, and we would want to help
readers by mentioning, as widely as possible, in what situations this mode
of operation that is described in the section is applicable.

Before your change, the title describes "One very typical situation in
which you may want to do what we teach in this section" (i.e. "I do not
want to test this commit"), the first paragraph describes the situation a
bit further, and then the remainder gives how.

After your change, the title describes "What we teach you how to do in
this section", the first paragraph of the section describes "Why you may
want to do such a thing".

A title is only one line.  It cannot afford to be too verbose.  People,
when they have problems, tend to skim documentation to see if there is
something applicable to their situation.  At least "Avoiding to test a
commit" should have worded "Avoiding to test the suggested commit" to draw
attention better from people in such a situation, and I agree with you
that "Changing the revision to test", "Testing a different revision",
etc. would work much better for that purpose.

But at the same time, I think the first paragraph "Why you may want to do
such a thing" should be strenghtened to cover wider scenario without going
to verbose, especially now the title has become even more bland --- it now
tells "what you would do" without hinting "why you might want to" anymore.
It currently talks only about what you said in your response "you could,
but you do not want to as you know it is a waste of time", and no other
scenarios you hinted in your response by saying "more general than that".

Making the first paragraph richer would help the readers who spotted the
(now better reworded) title to decide that the section indeed applies to
their situation.

Also, I think the section that follows this part should be part of this
section.  Either you reset to a specific commit, or you use "bisect skip"
to pick another one for you.  Both are solutions to the same problem.

Re: [PATCH] improve doc heading for git-bisect

[Jeff King]

On Sat, Jun 07, 2008 at 09:06:19AM -0700, Robert Anderson wrote:

> > FYI this line is not necessary, and should be removed from
> > git-format-patch output when pasting it to your MUA.
> 
> Err, then shouldn't it be removed from format-patch, rather than
> deleted manually every time format-patch is used?

As others have pointed out, the usual way for using format-patch is to
create an mbox that you then pull into your MUA (e.g., I do "git
format-patch --stdout origin >mbox; mutt -f mbox").

However, sometimes it is desirable to cut and paste, either because it
is inconvenient to bring the message into your MUA this way, or if you
are just putting a commit into an email you have already started
writing.

I was going to suggest a "--paste" option for format-patch which would
produce a nicer output for cutting and pasting, but it is trivial to do
with an alias:

  git config --global \
    alias.pastepatch \
    'format-patch --pretty=format:%s%n%n%b'

(actually, this loses the author information versus using the
--pretty=email format, but if you are just sending your own work, it is
fine).

It is essentially the same as "git log --stat -p" except that the commit
message is indented properly, and the revision arguments are interpreted
as format-patch does.

-Peff

Re: [PATCH] improve doc heading for git-bisect

[Johannes Schindelin]

Hi,

On Sun, 8 Jun 2008, Jeff King wrote:

> On Sat, Jun 07, 2008 at 09:06:19AM -0700, Robert Anderson wrote:
> 
> > > FYI this line is not necessary, and should be removed from
> > > git-format-patch output when pasting it to your MUA.
> > 
> > Err, then shouldn't it be removed from format-patch, rather than
> > deleted manually every time format-patch is used?
> 
> As others have pointed out, the usual way for using format-patch is to
> create an mbox that you then pull into your MUA (e.g., I do "git
> format-patch --stdout origin >mbox; mutt -f mbox").
> 
> However, sometimes it is desirable to cut and paste, either because it
> is inconvenient to bring the message into your MUA this way, or if you
> are just putting a commit into an email you have already started
> writing.
> 
> I was going to suggest a "--paste" option for format-patch which would
> produce a nicer output for cutting and pasting,

You still have to move the subject line where it belongs, so I think the 
value of --paste is limited.  You do have to pay attention anyway (for 
example when imitating how other people do it), so I think the current 
state should be fine.

Ciao,
Dscho

Re: [PATCH] improve doc heading for git-bisect

[Jeff King]

On Sun, Jun 08, 2008 at 04:01:48PM +0100, Johannes Schindelin wrote:

> > I was going to suggest a "--paste" option for format-patch which would
> > produce a nicer output for cutting and pasting,
> 
> You still have to move the subject line where it belongs, so I think the 
> value of --paste is limited.  You do have to pay attention anyway (for 
> example when imitating how other people do it), so I think the current 
> state should be fine.

Not necessarily. I often end up posting patches like:

How about this?

-- >8 --
subject

body

---
diffstat

patch

but the --pretty=format recipe I provided works just fine for that.

-Peff