threads / discuss / 10562

Where man git-format-patch sends me?

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

## tl;dr

5 messages between Nov 1, 2007 and Nov 2, 2007.

replies: 4people: 3as markdown or json

Sergei Organov· Nov 1, 2007, 13:58 UTC · lore

$ 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.

Johannes Schindelin· Nov 1, 2007, 14:38 UTC · re: Sergei Organov · lore

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

Hi,

On Thu, 1 Nov 2007, Sergei Organov wrote:

Show 6 quoted lines

> $ 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

Sergei Organov· Nov 1, 2007, 15:47 UTC · re: Johannes Schindelin · lore

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

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

Show 13 quoted lines

> 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.

Wincent Colaiuta· Nov 2, 2007, 10:03 UTC · re: Sergei Organov · lore

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

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

Show 31 quoted lines

> 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

Sergei Organov· Nov 2, 2007, 11:25 UTC · re: Wincent Colaiuta · lore

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

Wincent Colaiuta <win@wincent.com> writes:

Show 35 quoted lines

> 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.