A "three-way merge" is based on the concept of two files having "diffs" from a base (common ancestor) file, and the ability to combine those diffs into a new single file. The below example illustrates a base file having two changes made to it, and those two changes being merged together:
See "How CALAMARI diffs files" for more on how the diffs are determined.
To merge files in CALAMARI, call calamari with the names of the "base," "theirs," and "yours" files as arguments. You can optionally specify the "result" file that the merge will be saved as; if you do not specify a result filename, you will be prompted for one when you save.
calamari base.png theirs.png yours.png [result.png]
Theirs stencil: Applies a "stencil" over the merge editor, both obscuring parts of the result that do not correspond to diffs in the "theirs" file, and preventing those parts from being painted over.
Yours stencil: Like the Theirs stencil, but corresponds to diffs in the "yours" file.
Conflict stencil: Like the other two stencils, but corresponds to conflicting diffs (usually the intersection of the "yours" and "theirs" diffs).
Color options: Allows you to set the color of the stencils, the color that Automerge paints conflicts with, the color that the Eraser replaces the image with, and the threshold at which color differences are considered to be "diffs".
Zoom: Allows you to set the zoom level of the merge editor.
Automerge: Automatically merges the entire file by accepting all non-conflicting diffs from both "theirs" and "yours". Conflicts will be painted with the "conflict color" set in Color Options, and should be replaced with "theirs" or "yours" before saving.
Paint: Allows you to selectively paint in the merge editor with colors taken from the "theirs" file, the "yours" file, or a blend of the two. The slider determines which of the two images you will use.
Spray: Like the Paint tool, but it is automatically applied to the entire image as the slider is moved. The Spray tool is most effective when used in combination with one of the stencils - for example, by applying the Conflict stencil and using the Spray tool, you can simultaneously resolve all the conflicts in the image without harming the non-conflicting portions.
Eraser: Allows you to selectively overwrite portions of the merged image with a neutral color (the default is #FFFFFF00, or transparent white). The color can be chosen in the Color options dialog.
Save: Saves the image. If you have not saved the image yet, and you did not specify a "result" on the command line, you will be prompted for a filename.
File > Save: Saves the image.
File > Save As...: Prompts you for a new filename and saves the image.
File > Export Stencils: Saves the "base", "theirs", and "conflict" stencils as black and white PNGs in the same location as the saved merge image.
File > Exit: Guess what this does.
View > Diff Base vs Theirs...: Opens a new CALAMARI window which diffs the "base" and "theirs" files.
View > Diff Base vs Yours...: Opens a new CALAMARI window which diffs the "base" and "yours" files.
Help > CALAMARI Help: Brings you here.
Help > About: A mildly informative blurb.
Theirs: The "theirs" file that you passed to CALAMARI. As in diff mode, clicking on this image will set the slider to the top position, and will scroll the merge editor to the clicked area if appropriate.
Yours: As above, but with the "yours" file.
Slider: Sets the blend of colors that will be used by the Paint and Spray tools. Disabled if neither of those tools is active.
Merge Editor: This is where you modify the merge result using the Automerge, Paint, Spray, and Erase tools.