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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 21, 2008, 05:53 UTC
Message-ID: <7vvdxukj6w.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <8f6a00e30808202027s1d481a01q22c5a7444cd03f80@mail.gmail.com>

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