Custom merge drivers: accessing the pathnames and revisions of the files being merged

Custom merge drivers: accessing the pathnames and revisions of the files being merged

[Antonin Delpeuch]

Hello,

Custom merge drivers [1] provide a convenient way to extend Git's merge 
algorithms. But as far as I can tell, there is no way to access the 
pathnames and revisions of the files to merge. Those would be very 
useful to generate informative conflict markers, like the built-in merge 
strategies do.

For instance, when merging with the ort strategy and diff3 conflict 
style, I get markers such as:

<<<<<<< HEAD:main/my_file.txt
…
||||||| 194c4190b:main/my_file.txt
…
=======
…
 >>>>>>> origin/branch:main/my_renamed_file.txt

Those strings at the end of conflict markers, with the revision and the 
pathname, are very useful to understand which parts are coming from where.

When implementing a custom merge driver, I don't see how to access this 
information to include it in the conflict markers. Custom merge drivers 
are typically invoked on temporary files generated by Git with 
uninformative paths, such as ".merge_file_NgiKjJ".

Therefore, my merge driver is only able to generate conflicts which look 
like this:

<<<<<<< .merge_file_NgiKjJ
…
||||||| .merge_file_D1XtCW
…
=======
…
 >>>>>>> .merge_file_WbmrBA

Of course, in a given rebase/merge session, the order in which the 
conflicting parts will be presented will remain consistent, so I will 
generally be able to remember which revision each part corresponds to,
but it's still a mental load I would ideally try to avoid. Also, if the 
rename detection heuristics have false positives, then I can get merge 
conflicts which come from unrelated files: in that case it is very 
useful to see the pathnames, to understand this situation better.

So, I wonder: would people be open to exposing additional parameters to 
merge drivers? For instance we could add parameters "%X", "%Y" "%Z" to 
expose those "revision:pathname" strings for each part. (I think colons 
cannot be part of revision names, so this can be parsed unambiguously by 
the custom merge driver to recover the revision and pathname 
independently, if needed.)

I would be happy to submit a patch for this if you think this makes 
sense. If it is already possible to access this information in another 
way, I would like to work on documenting that.

Best wishes,
Antonin

[1]: https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver

Re: Custom merge drivers: accessing the pathnames and revisions of the files being merged

[Junio C Hamano]

Antonin Delpeuch <antonin@delpeuch.eu> writes:

> So, I wonder: would people be open to exposing additional parameters
> to merge drivers? For instance we could add parameters "%X", "%Y" "%Z"
> to expose those "revision:pathname" strings for each part. (I think
> colons cannot be part of revision names, so this can be parsed
> unambiguously by the custom merge driver to recover the revision and
> pathname independently, if needed.)

The last time this changed was in ef45bb1f (ll-merge: pass the
original path to external drivers, 2015-06-04).  

I may not necessarily endorse the choice of XYZ [*], but I do not
fundamentally oppose to such a new feature existing.  The mechanism
to define a custom merge driver is designed to be future-proof in
that only the parameters it uses is given as the value of
merge.*.driver variable, so it is not a problem that existing merge
drivers will not know what to do with "pathname in the common
ancestor", "pathname on our side", and "pathname on their side".


[Footnote]

 * Whatever letters we choose, they must have mnemonic value that
   signals two of them are the both sides of the merge that are
   equal participants, and the other one is the old-file, their
   common ancestor that plays quite a different from these two in
   the merge.  I cannot tell which one of the XYZ would be the more
   special than other two, which is the primary reason why I do not
   know if XYZ is a good idea.

Re: Custom merge drivers: accessing the pathnames and revisions of the files being merged

[Antonin Delpeuch]

Thanks a lot for your insights! Yes I also very much appreciate that the 
extension point is built in such a way that introducing new parameters 
is non-breaking.

On 16/01/2024 18:51, Junio C Hamano wrote:
>   * Whatever letters we choose, they must have mnemonic value that
>     signals two of them are the both sides of the merge that are
>     equal participants, and the other one is the old-file, their
>     common ancestor that plays quite a different from these two in
>     the merge.  I cannot tell which one of the XYZ would be the more
>     special than other two, which is the primary reason why I do not
>     know if XYZ is a good idea.

That makes perfect sense. How about:

- %S for the "source" pathname (corresponding to the %O file)

- %X for the first side of the merge (corresponding to the %A file)

- %Y for the second side of the merge (corresponding to the %B file)

Anyway, I'll try to work on a patch: it should be easy to adapt the 
letters to any other choice.

Best,

Antonin