• View
• Edit
• Upload
• History
• Print

LyxAsGitMergetool

How to configure LyX as a merge tool for GIT to use the built-in compare feature for merge conflict resolving

1.  Motivation

When collaborating on LyX Documents with git, Merge conflicts may arise. Since the LyX format is text-based, you can resolve the conflicts in traditional merging tools, or even by hand. But this can be complicated without having a graphical representation of what has actually changed, at least if it goes beyond text-only changes.

Here, the built-in compare feature of LyX comes in handy (reachable under Tools → Compare), but calling it manually in case of conflicts is not the very best solution because you need to get the two file versions side-by-side first.

Luckily, git has the possibility to register custom merge tools you can invoke by a simple git command.

Here's how:

1.1  Set up LyX as merge tool in git

The configuration varies between Windows and Unix systems because of Windows absolute file paths looking different than those on Unix systems.

For Windows Systems

Issue the following command:

git config --global mergetool.lyx.cmd "\"C:\Program Files (x86)\LyX_2.3\bin\lyx\" -x \"dialog-show compare run \\\"`cygpath -wa \"$LOCAL\"`\\\" \\\"`cygpath -wa \"$REMOTE\"`\\\"\""

If your LyX executable is not in C:\Program Files (x86)\LyX_2.3\bin, adapt the path before issuing the command.

For UNIX Systems

Issue a similar but slightly different command:

git config --global mergetool.lyx.cmd "\"/path/to/lyx\" -x \"dialog-show compare run \\\"`realpath \"$LOCAL\"`\\\" \\\"`realpath \"$REMOTE\"`\\\"\""

Adapt the /path/to/lyx before issuing the command.

1.2  Usage

When encountering a merge conflict, you can start LyX in compare mode (the "old" file being the file from the current branch, the "new" file being the one from the other branch) by the simple command git mergetool -t lyx path/to/conflicting_file.lyx (replacing path/to/conflicting_file.lyx with the actual path of course).

The detected changes will then be highlighted in the document and you can manually resolve the conflicts.

When all changes are resolved, make sure to override the conflicted file with the temporarily created changes1.lyx file (File → Save as...), otherwise the conflict resolutions will get lost.

When the file is saved, close the LyX window and confirm to git that the merge was successful.

2.  Warning

The Compare function of LyX is not perfect (yet) and may not highlight all existing changes. Data loss may be possible!

3.  Categories

Category: Tip, VCS, Compare