[4/5] merge-tree: improve docs for --stdin

Commit Message

Phillip Wood Feb. 16, 2025, 4:37 p.m. UTC

From: Phillip Wood <[e-mail]>

Add a section for --stdin in the list of options and document that it
implies -z so readers know how to parse the output. Also correct the
merge status documentation for --stdin as if the status is less than
zero "git merge-tree" dies before printing it.

Signed-off-by: Phillip Wood <[e-mail]>
---
 Documentation/git-merge-tree.txt | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

Comments

Elijah Newren Feb. 17, 2025, 8:26 p.m. UTC | #1

On Sun, Feb 16, 2025 at 8:37 AM Phillip Wood via GitGitGadget
<[e-mail]> wrote:
>
> From: Phillip Wood <[e-mail]>
>
> Add a section for --stdin in the list of options and document that it
> implies -z so readers know how to parse the output.

Makes sense.

> Also correct the
> merge status documentation for --stdin as if the status is less than
> zero "git merge-tree" dies before printing it.

This also makes sense, but...die'ing still has an exit status
associated with it right?

> Signed-off-by: Phillip Wood <[e-mail]>
> ---
>  Documentation/git-merge-tree.txt | 8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt
> index 0b6a8a19b1f..efb16b4f27d 100644
> --- a/Documentation/git-merge-tree.txt
> +++ b/Documentation/git-merge-tree.txt
> @@ -40,6 +40,11 @@ After the merge completes, a new toplevel tree object is created.  See
>  OPTIONS
>  -------
>
> +--stdin::
> +       Read the commits to merge from the standard input rather than
> +       the command-line. See <<INPUT,INPUT FORMAT>> below for more
> +       information.  Implies `-z`.
> +
>  -z::
>         Do not quote filenames in the <Conflicted file info> section,
>         and end each filename with a NUL character rather than
> @@ -116,8 +121,6 @@ This is an integer status followed by a NUL character.  The integer status is:
>
>       0: merge had conflicts
>       1: merge was clean
> -     <0: something prevented the merge from running (e.g. access to repository
> -        objects denied by filesystem)

Should this line be kept but replace "<0" with "128" (the exit status of die)?

>
>  [[OIDTLT]]
>  OID of toplevel tree
> @@ -235,6 +238,7 @@ with linkgit:git-merge[1]:
>    * any messages that would have been printed to stdout (the
>      <<IM,Informational messages>>)
>
> +[[INPUT]]
>  INPUT FORMAT
>  ------------
>  'git merge-tree --stdin' input format is fully text based. Each line
> --
> gitgitgadget

Phillip Wood Feb. 18, 2025, 10:02 a.m. UTC | #2

Hi Elijah

On 17/02/2025 20:26, Elijah Newren wrote:
> On Sun, Feb 16, 2025 at 8:37 AM Phillip Wood via GitGitGadget
> <[e-mail]> wrote:
>>
>> Also correct the
>> merge status documentation for --stdin as if the status is less than
>> zero "git merge-tree" dies before printing it.
> 
> This also makes sense, but...die'ing still has an exit status
> associated with it right?

It does, but that is documented in a separate section which says that if 
there is an error it exits with a code that isn't 0 or 1. The section 
I've altered is documenting what "git merge-tree --stdin" prints to 
stdout and if result.clean is less than zero then it dies it does not 
print anything to stdout.

Best Wishes

Phillip

>> Signed-off-by: Phillip Wood <[e-mail]>
>> ---
>>   Documentation/git-merge-tree.txt | 8 ++++++--
>>   1 file changed, 6 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt
>> index 0b6a8a19b1f..efb16b4f27d 100644
>> --- a/Documentation/git-merge-tree.txt
>> +++ b/Documentation/git-merge-tree.txt
>> @@ -40,6 +40,11 @@ After the merge completes, a new toplevel tree object is created.  See
>>   OPTIONS
>>   -------
>>
>> +--stdin::
>> +       Read the commits to merge from the standard input rather than
>> +       the command-line. See <<INPUT,INPUT FORMAT>> below for more
>> +       information.  Implies `-z`.
>> +
>>   -z::
>>          Do not quote filenames in the <Conflicted file info> section,
>>          and end each filename with a NUL character rather than
>> @@ -116,8 +121,6 @@ This is an integer status followed by a NUL character.  The integer status is:
>>
>>        0: merge had conflicts
>>        1: merge was clean
>> -     <0: something prevented the merge from running (e.g. access to repository
>> -        objects denied by filesystem)
> 
> Should this line be kept but replace "<0" with "128" (the exit status of die)?
> 
>>
>>   [[OIDTLT]]
>>   OID of toplevel tree
>> @@ -235,6 +238,7 @@ with linkgit:git-merge[1]:
>>     * any messages that would have been printed to stdout (the
>>       <<IM,Informational messages>>)
>>
>> +[[INPUT]]
>>   INPUT FORMAT
>>   ------------
>>   'git merge-tree --stdin' input format is fully text based. Each line
>> --
>> gitgitgadget
>

Elijah Newren Feb. 18, 2025, 3:56 p.m. UTC | #3

On Tue, Feb 18, 2025 at 2:02 AM Phillip Wood <[e-mail]> wrote:
>
> Hi Elijah
>
> On 17/02/2025 20:26, Elijah Newren wrote:
> > On Sun, Feb 16, 2025 at 8:37 AM Phillip Wood via GitGitGadget
> > <[e-mail]> wrote:
> >>
> >> Also correct the
> >> merge status documentation for --stdin as if the status is less than
> >> zero "git merge-tree" dies before printing it.
> >
> > This also makes sense, but...die'ing still has an exit status
> > associated with it right?
>
> It does, but that is documented in a separate section which says that if
> there is an error it exits with a code that isn't 0 or 1. The section
> I've altered is documenting what "git merge-tree --stdin" prints to
> stdout and if result.clean is less than zero then it dies it does not
> print anything to stdout.
>
> Best Wishes
>
> Phillip

Oh, right, so your patch is good then.  Thanks for pointing out what I missed.

Patch

diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt
index 0b6a8a19b1f..efb16b4f27d 100644
--- a/Documentation/git-merge-tree.txt
+++ b/Documentation/git-merge-tree.txt
@@ -40,6 +40,11 @@  After the merge completes, a new toplevel tree object is created.  See
 OPTIONS
 -------
 
+--stdin::
+	Read the commits to merge from the standard input rather than
+	the command-line. See <<INPUT,INPUT FORMAT>> below for more
+	information.  Implies `-z`.
+
 -z::
 	Do not quote filenames in the <Conflicted file info> section,
 	and end each filename with a NUL character rather than
@@ -116,8 +121,6 @@  This is an integer status followed by a NUL character.  The integer status is:
 
      0: merge had conflicts
      1: merge was clean
-     <0: something prevented the merge from running (e.g. access to repository
-	 objects denied by filesystem)
 
 [[OIDTLT]]
 OID of toplevel tree
@@ -235,6 +238,7 @@  with linkgit:git-merge[1]:
   * any messages that would have been printed to stdout (the
     <<IM,Informational messages>>)
 
+[[INPUT]]
 INPUT FORMAT
 ------------
 'git merge-tree --stdin' input format is fully text based. Each line