[v2,0/2] doc: merge-tree: improve the script example

Commit Message

Kristoffer Haugsbakk Oct. 8, 2024, 7:06 p.m. UTC

§ Changes since v1

Patches:

• v1 1: v2 1: use a file instead of `-mMerge` for the commit message
• v1 2: dropped (lower-case variables)
• v1 3: v2 2: no changes

Kristoffer Haugsbakk (2):
  doc: merge-tree: provide a commit message
  doc: merge-tree: use || directly

 Documentation/git-merge-tree.txt | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

Interdiff against v1:
Range-diff against v1:
1:  6b05526c327 < -:  ----------- doc: merge-tree: provide a commit message
2:  7d4deaee6c4 ! 1:  b1ca5cae768 doc: merge-tree: use lower-case variables
    @@ Metadata
     Author: Kristoffer Haugsbakk <[e-mail]>
     
      ## Commit message ##
    -    doc: merge-tree: use lower-case variables
    +    doc: merge-tree: provide a commit message
     
    -    This is easier to read.
    +    Provide a commit message in the example command.
    +
    +    The command will hang since it is waiting for a commit message on
    +    stdin.  Which is usable but not straightforward enough since this is
    +    example code.
     
         Signed-off-by: Kristoffer Haugsbakk <[e-mail]>
     
    +
    + ## Notes (series) ##
    +    Unlike on some other manuals you probably won’t end up running these
    +    commands directly to test things out.  But you might end up copying and
    +    modifying it when playing around with the command.
    +
      ## Documentation/git-merge-tree.txt ##
    -@@ Documentation/git-merge-tree.txt: linkgit:git-commit-tree[1], linkgit:git-write-tree[1],
    - linkgit:git-update-ref[1], and linkgit:git-mktag[1].  Thus, it can be
    - used as a part of a series of steps such as:
    +@@ Documentation/git-merge-tree.txt: used as a part of a series of steps such as:
      
    --       NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2)
    -+       newtree=$(git merge-tree --write-tree $branch1 $branch2)
    +        NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2)
             test $? -eq 0 || die "There were conflicts..."
    --       NEWCOMMIT=$(git commit-tree $NEWTREE -mMerge -p $BRANCH1 -p $BRANCH2)
    --       git update-ref $BRANCH1 $NEWCOMMIT
    -+       newcommit=$(git commit-tree $newtree -mMerge -p $branch1 -p $branch2)
    -+       git update-ref $branch1 $newcommit
    - 
    --Note that when the exit status is non-zero, `NEWTREE` in this sequence
    -+Note that when the exit status is non-zero, `newtree` in this sequence
    - will contain a lot more output than just a tree.
    +-       NEWCOMMIT=$(git commit-tree $NEWTREE -p $BRANCH1 -p $BRANCH2)
    ++       NEWCOMMIT=$(git commit-tree $NEWTREE -F $FILE_WITH_COMMIT_MESSAGE \
    ++           -p $BRANCH1 -p $BRANCH2)
    +        git update-ref $BRANCH1 $NEWCOMMIT
      
    - For conflicts, the output includes the same information that you'd get
    + Note that when the exit status is non-zero, `NEWTREE` in this sequence
3:  1b60dc810e3 ! 2:  13e0f3bed5d doc: merge-tree: use || directly
    @@ Documentation/git-merge-tree.txt: linkgit:git-commit-tree[1], linkgit:git-write-
      linkgit:git-update-ref[1], and linkgit:git-mktag[1].  Thus, it can be
      used as a part of a series of steps such as:
      
    --       newtree=$(git merge-tree --write-tree $branch1 $branch2)
    +-       NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2)
     -       test $? -eq 0 || die "There were conflicts..."
    -+       newtree=$(git merge-tree --write-tree $branch1 $branch2) || {
    ++       NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2) || {
     +           echo "There were conflicts..." 1>&2
     +           exit 1
     +       }
    -        newcommit=$(git commit-tree $newtree -mMerge -p $branch1 -p $branch2)
    -        git update-ref $branch1 $newcommit
    - 
    +        NEWCOMMIT=$(git commit-tree $NEWTREE -F $FILE_WITH_COMMIT_MESSAGE \
    +            -p $BRANCH1 -p $BRANCH2)
    +        git update-ref $BRANCH1 $NEWCOMMIT

Patch

diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt
index 46091da022d..41dfb16476d 100644
--- a/Documentation/git-merge-tree.txt
+++ b/Documentation/git-merge-tree.txt
@@ -211,14 +211,15 @@  linkgit:git-commit-tree[1], linkgit:git-write-tree[1],
 linkgit:git-update-ref[1], and linkgit:git-mktag[1].  Thus, it can be
 used as a part of a series of steps such as:
 
-       newtree=$(git merge-tree --write-tree $branch1 $branch2) || {
+       NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2) || {
            echo "There were conflicts..." 1>&2
            exit 1
        }
-       newcommit=$(git commit-tree $newtree -mMerge -p $branch1 -p $branch2)
-       git update-ref $branch1 $newcommit
+       NEWCOMMIT=$(git commit-tree $NEWTREE -F $FILE_WITH_COMMIT_MESSAGE \
+           -p $BRANCH1 -p $BRANCH2)
+       git update-ref $BRANCH1 $NEWCOMMIT
 
-Note that when the exit status is non-zero, `newtree` in this sequence
+Note that when the exit status is non-zero, `NEWTREE` in this sequence
 will contain a lot more output than just a tree.
 
 For conflicts, the output includes the same information that you'd get