Where man git-format-patch sends me?

Where man git-format-patch sends me?

[Sergei Organov]

$ man git-format-patch
[...]
OPTIONS
       -p     Generate patch (see section on generating patches)

       -u     Synonym for "-p".
[...]
$

1. Saying "-p generates patch" suggests that without -p git-format-patch
   will generate something else. It's rather confusing.

2. Where is this "section on generating patches"? I thought it could be
   in man git-diff, but it is not.

-- 
Sergei.

Re: Where man git-format-patch sends me?

[Johannes Schindelin]

Hi,

On Thu, 1 Nov 2007, Sergei Organov wrote:

> $ man git-format-patch
> [...]
> OPTIONS
>        -p     Generate patch (see section on generating patches)
> 
>        -u     Synonym for "-p".

As you can easily see from Documentation/git-format-patch.txt, this part 
is generated from the file Documentation/diff-options.txt.

Hth,
Dscho

Re: Where man git-format-patch sends me?

[Sergei Organov]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Hi,
>
> On Thu, 1 Nov 2007, Sergei Organov wrote:
>
>> $ man git-format-patch
>> [...]
>> OPTIONS
>>        -p     Generate patch (see section on generating patches)
>> 
>>        -u     Synonym for "-p".
>
> As you can easily see from Documentation/git-format-patch.txt, this part 
> is generated from the file Documentation/diff-options.txt.

Sorry, I did saw that, but it doesn't change anything.

1. As a user reading man git-format-patch, where do I find this "section
   on generating patches"? In another man-page? In the html
   documentation? On the moon?

2. I can't find "section on generating patches" in the man git-diff
   either, and I did say this in the part of my original message you've
   snipped.

So the main question remains: could you please point me to the exact
place in 'Documentation/' directory where this "section on generating
patches" resides?

-- 
Sergei.

Re: Where man git-format-patch sends me?

[Wincent Colaiuta]

El 1/11/2007, a las 16:47, Sergei Organov escribió:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>
>> Hi,
>>
>> On Thu, 1 Nov 2007, Sergei Organov wrote:
>>
>>> $ man git-format-patch
>>> [...]
>>> OPTIONS
>>>       -p     Generate patch (see section on generating patches)
>>>
>>>       -u     Synonym for "-p".
>>
>> As you can easily see from Documentation/git-format-patch.txt, this  
>> part
>> is generated from the file Documentation/diff-options.txt.
>
> Sorry, I did saw that, but it doesn't change anything.
>
> 1. As a user reading man git-format-patch, where do I find this  
> "section
>   on generating patches"? In another man-page? In the html
>   documentation? On the moon?
>
> 2. I can't find "section on generating patches" in the man git-diff
>   either, and I did say this in the part of my original message you've
>   snipped.
>
> So the main question remains: could you please point me to the exact
> place in 'Documentation/' directory where this "section on generating
> patches" resides?

I believe the section in question is in Documentation/diff-format.txt

But you've basically found a documentation bug. Someone invoking "man  
git-format-patch" shouldn't be expected to have to grep the source  
tree in order to find out where the referenced documentation is.  
Especially given that he/she may not even have the source.

Cheers,
Wincent

Re: Where man git-format-patch sends me?

[Sergei Organov]

Wincent Colaiuta <win@wincent.com> writes:

> El 1/11/2007, a las 16:47, Sergei Organov escribió:
>
>> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>>
>>> Hi,
>>>
>>> On Thu, 1 Nov 2007, Sergei Organov wrote:
>>>
>>>> $ man git-format-patch
>>>> [...]
>>>> OPTIONS
>>>>       -p     Generate patch (see section on generating patches)
>>>>
>>>>       -u     Synonym for "-p".
>>>
>>> As you can easily see from Documentation/git-format-patch.txt, this  
>>> part
>>> is generated from the file Documentation/diff-options.txt.
>>
>> Sorry, I did saw that, but it doesn't change anything.
>>
>> 1. As a user reading man git-format-patch, where do I find this  
>> "section
>>   on generating patches"? In another man-page? In the html
>>   documentation? On the moon?
>>
>> 2. I can't find "section on generating patches" in the man git-diff
>>   either, and I did say this in the part of my original message you've
>>   snipped.
>>
>> So the main question remains: could you please point me to the exact
>> place in 'Documentation/' directory where this "section on generating
>> patches" resides?
>
> I believe the section in question is in Documentation/diff-format.txt

Ah, thank you! Now, diff-format.txt is included by
git-diff-index/git-diff-files/git-diff-tree, but not by git-diff and
git-format-patch. Do you think it is the right thing for the latter two
to include diff-format as well?

-- 
Sergei.