0001-Detailed-tools-useful-when-resolving-merge-conflicts.patch

0001-Detailed-tools-useful-when-resolving-merge-conflicts.patch

[Dan Hensgen]

[-- Attachment #1: Type: text/plain, Size: 53 bytes --]

Sorry, had trouble with git send-email.

Thanks,
Dan

[-- Attachment #2: 0001-Detailed-tools-useful-when-resolving-merge-conflicts.patch --]
[-- Type: application/octet-stream, Size: 2019 bytes --]

From b2ca52f8ba70e689cd8e9424707629e4ca37fab3 Mon Sep 17 00:00:00 2001
From: Dan Hensgen <dan@macbook.danhensgen.com>
Date: Wed, 20 Aug 2008 23:14:06 -0400
Subject: [PATCH] Detailed tools useful when resolving merge conflicts

Signed-off-by: Dan Hensgen <dan@methodhead.com>
---
 Documentation/git-merge.txt |   27 ++++++++++++++++++++-------
 1 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 17a15ac..bff56c5 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -126,13 +126,26 @@ After seeing a conflict, you can do two things:
    up working tree changes made by 2. and 3.; 'git-reset --hard' can
    be used for this.
 
- * Resolve the conflicts.  `git diff` would report only the
-   conflicting paths because of the above 2. and 3.
-   Edit the working tree files into a desirable shape
-   ('git mergetool' can ease this task), 'git-add' or 'git-rm'
-   them, to make the index file contain what the merge result
-   should be, and run 'git-commit' to commit the result.
-
+ * Resolve the conflicts.  Edit the working tree files into shape
+   and 'git-add' to the index.  'git-commit' to seal the deal.
+
+You can work through conflict with a number of tools:
+
+ * Look at the originals.  'git show :1:filename' shows the
+   common ancestor, 'git show :2:filename' shows the HEAD
+   version and 'git show :3:filename' shows the remote
+   version.
+
+ * Diff the conflicts against the originals.  'git-diff --base'
+   diffs against the common ancestor, 'git-diff --ours' diffs
+   against the HEAD version and 'git-diff --theirs' diffs
+   against the remote version.
+
+ * Use a mergetool.  'git diff mergetool' to start the merge
+   process.  Four versions of a conflicted file get written as
+   the mergetool starts, BASE, LOCAL, REMOTE and BACKUP.
+   They're created for the  mergetool, but they're handy
+   alternatives to the 'git show :1:filename' command.
 
 SEE ALSO
 --------
-- 
1.5.6.2

Re: 0001-Detailed-tools-useful-when-resolving-merge-conflicts.patch

[Junio C Hamano]

"Dan Hensgen" <dan@methodhead.com> writes:

> + * Resolve the conflicts.  Edit the working tree files into shape
> +   and 'git-add' to the index.  'git-commit' to seal the deal.

The documentation assumed the user have experience with the usual conflict
markers, and a more detailed explanation than what we currently have is
certainly welcomed.

I however cannot tell who the intended target audience of your description
is, from the order of presentation.

If you primarily target newbies and GUI-minded people, I think mergetool
should be the first one.

On the other hand, for command-line oriented people, you failed to
describe two more common and useful ways.

 - "git diff" itself will show the diff that contains the conflicted part,
   in a three-way diff format.  For example, if you try to merge c48544e
   (gitweb: use new Git::Repo API, and add optional caching, 2008-08-18)
   into c5a00f7 (Merge branch 'master' into next, 2008-08-20), you would
   see something like this:

   $ git diff
   diff --cc t/t9500-gitweb-standalone-no-errors.sh
   index 46ba19b,7f134f5..0000000
   --- i/t/t9500-gitweb-standalone-no-errors.sh
   +++ w/t/t9500-gitweb-standalone-no-errors.sh
   @@@ -54,7 -54,7 +54,11 @@@ gitweb_run () 
           # written to web server logs, so we are not interested in that:
           # we are interested only in properly formatted errors/warnings
           rm -f gitweb.log &&
   ++<<<<<<< HEAD:t/t9500-gitweb-standalone-no-errors.sh
    +	perl -- "$TEST_DIRECTORY/../gitweb/gitweb.perl" \
   ++=======
   + 	"$PERL_PATH" -- "$TEST_DIRECTORY/../gitweb/gitweb.perl" \
   ++>>>>>>> lw/gitweb:t/t9500-gitweb-standalone-no-errors.sh
                   >/dev/null 2>gitweb.log &&
           if grep -q -s "^[[]" gitweb.log >/dev/null; then false; else true; fi
  
   which makes it clear that since the common ancestor, our side (HEAD)
   added the line that begins with "perl", while the branch you are
   merging (lw/gitweb) added the line that begins with "$PERL_PATH".  In
   this case, Lea's change is a pure superset of what our side did, so I'd
   take the latter half as the resolution.

 - "git log --merge -p --left-right <path>" will show the commits on your
   fork and the other branch that touch the paths involved in the merge,
   with explanations why each change was made.  The first entry of the
   output is c48544e (gitweb: use new Git::Repo API, and add optional
   caching, 2008-08-18) that changes "perl" to "$PERL_PATH" and also
   introduces "$TEST_DIRECTORY/" by replacing what used to be "$(pwd)",
   and you can tell it is from Lea's branch by looking at its "commit"
   line with right-pointing-arrow '>' at the beginning:

   commit >c48544e29a0a9ea2f2b4a601cf4977174b53e803
   Author: Lea Wiemann <lewiemann@gmail.com>
   Date:   Mon Aug 18 21:39:49 2008 +0200

   The second entry in the output is bfdbee9 (tests: use $TEST_DIRECTORY
   to refer to the t/ directory, 2008-08-08) with a left-pointing arrow,
   which is mine:

   commit <bfdbee98109c5ad2dbbc392e7eed1ae688acc039
   Author: Junio C Hamano <gitster@pobox.com>
   Date:   Fri Aug 8 02:26:28 2008 -0700

   that only changes "$(pwd)" to "$TEST_DIRECTORY".  By looking at these
   two, you can be sure that taking Lea's change as the superset is the
   right thing to do.

You can of course alternatively look at the original, but I do not think
that should be taught as the first two suggestions before mergetool, plain
"git diff" or "git log --merge".