Git merge

From Gramps
Revision as of 16:16, 6 November 2019 by Prculley (talk | contribs) (Configure git for scripts)
Jump to: navigation, search

Merging with git in Gramps has some challenges. The normal merge process, particularly with po files, can generate a lot of merge conflicts, due to the Python file line numbers, ordering changes and changes in line breaks in the po messages.

For the GrampsAddons we also have merge conflict issues, often with the gpr files and version numbers.

This describes the use of several scripts to make these merges a bit easier.

Configure git for scripts

The basic idea is to configure git to use some extra scripts which have a bit more knowledge about the files to be merged. At the moment there are three scripts:

  • po_driver.py this does the merge for po files.
  • po_conv.py this assists a "diff" for parts of git to ignore po comments
  • gpr_driver.py this does the merge for gpr.py files to deal with version number changes.

The three files need to be copied to your system in a convenient place. Since I use Windows, the path on my system is "C:\apps". Adjust your system path as appropriate here and in the .gitconfig file. Download https://gramps-project.org/wiki/index.php/File:Git_merge_drivers.zip (stored here) to a convenient location with your browser and unzip them.

Then you need to edit the .gitconfig file for your system, usually in your home directory. add the following to that file:

[merge "pofile"]
  name = Gettext merge driver
  driver = "python3.exe c:/Apps/po_driver.py" %O %A %B
[diff "pofile"]
  textconv="python3 c:/Apps/po_conv.py"
[merge "gprfile"]
  name = gpr.py merge driver
  driver = "python3.exe c:/Apps/gpr_driver.py" %O %A %B

Then you need to edit the .git/info/attributes file for each git directory that you use. I did this for my "Gramps" and "GrampsAddons" directories. If the file doesn't exist, create it. Add the following to that file:

# .gitattributes
# deal with po files on merge
*.po   merge=pofile
*.pot  merge=pofile
*.po   diff=pofile
*.pot  diff=pofile
# deal with gpr.py files on merge
*.gpr.py   merge=gprfile

Performing the merge

With the above scripts installed, the actual merge is normal

git merge

When merge conflicts occur, you need to make sure that any conflicts that occur in po files be fixed with a normal text editor, NOT the "git mergetool". This is because the git mergetool command sends the configured tool the three (base, local, remote) files to the tool, andy you lose the advantage of the script. The po file will have the usual ">>>>", "<<<<", and "====" indications where conflicts need to be resolved, so you can search on those to find what to fix.

For other non-po file types, the normal merge conflict process you like can be used. I use the "git mergetool" command with kdiff3 configured as my mergetool.

Making merges (when there are conflicts) easier

A tool which shows a 3-way merge can be helpful in determining what needs to be done. First configure git for the tool of choice (kdiff3 for windows shown here):

git config --global merge.tool kdiff3
git config --global mergetool.kdiff3.cmd "C:/Program Files/KDiff3/kdiff3.exe"  # Windows
git config --global --add mergetool.kdiff3.trustExitCode false

Then when a merge conflict comes up you can:

git mergetool

External links