Re: Writing merge strategy?

[Junio C Hamano <gitster@pobox.com>]

"Israel, Daniel M" <dmi1@lanl.gov> writes:

> I need a custom merge strategy (not driver) for a tool I’m writing, and I’m wondering:
>
> 1. Is there documentation for the API anywhere?

It used to be far easier to figure out back when git-merge.sh was a
script before 1c7b76be ("Build in merge", 2008-07-07) and it got
even harder to figure out after we removed contrib/examples/ at
49eb8d39 ("Remove contrib/examples/*", 2018-03-25), but you can
still find in "git show 1c7b76be^:git-merge.sh" output the following
snippet that shows how your merge strategy is called by the caller:

-- >8 -- snipsnap -- >8 --

    git-merge-$strategy $common -- "$head_arg" "$@"
    exit=$?
    if test "$no_commit" = t && test "$exit" = 0
    then
        merge_was_ok=t
	exit=1 ;# pretend it left conflicts.
    fi

    test "$exit" = 0 || {

	# The backend exits with 1 when conflicts are left to be resolved,
	# with 2 when it does not handle the given merge at all.

	if test "$exit" -eq 1
	then
	    cnt=`{
		git diff-files --name-only
		git ls-files --unmerged
	    } | wc -l`
	    if test $best_cnt -le 0 -o $cnt -le $best_cnt
	    then
		best_strategy=$strategy
		best_cnt=$cnt
	    fi
	fi
	continue
    }

    # Automerge succeeded.
    result_tree=$(git write-tree) && break

-- 8< -- snipsnap -- 8< --

You'll be called with common ancestor commit(s), double-dash, HEAD
(i.e. the commit the work by histories are being merged into), and
the commits being merged, on the command line.  You are expected to

 - update the index with the merge result and exit with 0, if you
   auto-resolved the merge cleanly; or

 - update the index with the cleanly merged result at stage #0, and
   for conflicted paths, place the common anestor version at stage
   #1, the version from HEAD at stage #2 and the version(s) from
   merged commit(s) at stage #3.  Signal that your automerge is
   usable with manual resolution by exiting with 1; or

 - do nothing and exit with 2, to signal that you were not capable
   of handling this particular merge.

The "git merge" command that called your strategy is responsible for
making a commit out of the index you left, recording the parent
commits, reacting to "merge --no-commit -S" and other options.

> 2. Does git-merge actually do any magic, or could I just run the
> script that implements my merge directly?  In other words, is
> there really any difference between a merge strategy and a script
> that creates the tree I want and then commits it using
> git-commit-tree with multiple -p arguments.

Other "magic" we let "git merge" do are things like handling
fast-forward, iterating over multiple strategies and use what works,
etc.

If you are not doing a strategy but a custom script, you'd be
reinventing "git merge".  As long as your custom script produces a
commit object that records the resulting tree, parent commits and
log message correctly, nobody who examines that resulting merge
commit would not even know you did not use "git merge" to record it.

And that is perfectly fine as long as the result suits your needs