wizard.merge

Advanced merge tools for git rerere, sloppy commits and parametrization.

Wizard requires infrastructure for reusing merge resolutions across many repositories, due to the number of user installs and highly repetitive conflict resolution process. This environment results in a number of unique challenges:

1. Users are commonly very sloppy with their text editors and will frequently change the line-ending style of their file. Because Git respects newline choice when core.autocrlf is off, a file that flips newline style will result in a full merge conflict.
2. We version user configuration files, which means that there will always be a set of changes between upstream and ours. Since Git refuses to automatically merge changes that are too close to each other, these frequently result in spurious merge commits.

Furthermore, both of these make it difficult to reuse rerere resolutions across installations. Thus, an advanced Wizard merge has the following properties:

1. Wizard will perform a full scan of all files that were different between common and ours, filter out those that are binary (using as close to the Git heuristic as possible) and then check among common, ours and theirs if the newlines match. The newline style of theirs always takes precedence.
2. Wizard will genericize the ours copy so that it matches common and theirs, and reparametrize it once the merge is finished. Consumers of this function should be careful to appropriately reparametrize if there are conflicts (we can’t do it any earlier, because we want clean rerere postimages).

Usage of this functionality is primarily through the merge() function; see that function more usage information. While the git and newline functions published by this module are public, use of these functions outside of this module is discouraged.

Functions

wizard.merge.merge(common_id, theirs_id, prepare_config=None, resolve_conflicts=None)

Performs a merge. Throws a MergeError if the merge fails (and leaves the current working directory in a state amenable to manual conflict resolution), or returns a tree id of the successful merge (the directory state is undefined and should not be relied upon). This function is not responsible for actually coming up with the real merge commit, because it can fail.

If prepare_config is used, you are expected to reverse the effects of this on whatever the final tree is; otherwise you will lose those changes.

Arguments:

• common_id: base commit to calculate merge off of
• theirs_id: changes to merge in from commit
• prepare_config: function that removes any user-specific values from files. This function is expected to git add any files it changes.
• resolve_conflicts: this function attempts to resolve conflicts automatically. Returns True if all conflicts are resolved, and False otherwise. It is permitted to resolve some but not all conflicts.

Note

Wizard has a strange idea of repository topology (due to lack of rebases, see documentation about doctoring retroactive commits), so we require the common and theirs commits, instead of using the normal Git algorithm.

Utility functions

wizard.merge.git_commit_tree(tree, *parents)

Convenience wrapper for git commit-tree. Writes an empty log.

wizard.merge.git_diff_text(a, b)

Returns a list of files that are text and are different between commits a and b.

wizard.merge.get_newline(filename)

Determines the newline style of filename. This will be a string if only one newline style was find, or a tuple of newline types found.

wizard.merge.convert_newline(filename, dest_nl)

Replaces the detected newline style of filename with dest_nl type newlines.

Exceptions

exception wizard.merge.Error

Base error class for merge

exception wizard.merge.MergeError

Bases: wizard.merge.Error

Merge terminated with a conflict, oh no!