# HG changeset patch # User Steve Losh # Date 1307756381 14400 # Node ID 97c9fd0ac4a4f9813c5dd9415538add5a4addeea Initial commit. diff -r 000000000000 -r 97c9fd0ac4a4 .hgignore --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/.hgignore Fri Jun 10 21:39:41 2011 -0400 @@ -0,0 +1,9 @@ +syntax: glob + +.DS_Store +*.pyc +*.swp +*.swo +*.un~ +.ropeproject +tags diff -r 000000000000 -r 97c9fd0ac4a4 LICENSE diff -r 000000000000 -r 97c9fd0ac4a4 README.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.markdown Fri Jun 10 21:39:41 2011 -0400 @@ -0,0 +1,240 @@ +Threesome is a Vim plugin for resolving conflicts during three-way merges. +It's designed to be used as a merge tool for version control systems like +Mercurial and Git. + +* Basic Usage +* Key Bindings +* Modes +* Configuration +* Contributing +* Changelog +* License + +Basic Usage +=========== + +Threesome takes a lot of inspiration for its user interface from Adobe +Lightroom, a photo editing program. + +When resolving a merge there are four files you will work with: + +* **Original**: the original file, as it appears in the parent revision of the two revisions being merged. +* **One**: the file as it appears in the first revision being merged (usually the "current" revision, or the one you are at when you run 'hg merge REV'). +* **Two**: the file as it appears in the second revision being merged (usually the "target" revision, or the one you specify in the 'hg merge REV' command). +* **Result**: the result of merging the two revisions of the file (this is the file that your version control system expects to contain the final result once you're done). + +Threesome has four "modes" or "views" for working with these files: + +* **Grid**: shows all four files at once, to give you an overview of the merge. +* **Loupe**: shows a single file at a time, for close examination of a single file. +* **Compare**: shows two files at a time, for examining the movement of changes between pairs of files. +* **Path**: shows three files at a time: the original, either one or two, and the result, for examining how a change moves through one "path" or "branch" of the merge. + +Your goal is to use these views to resolve all merge conflicts by making the +result file look like it should, saving it to disk, and closing Vim. + +Key Bindings +============ + +Threesome makes use of `` for all of its key bindings to avoid +clashing with global mappings. If you've never used `` now +would be a good time to read the help and configure a key for it. + +All keybindings that are used across all modes. The behavior of some of them +changes depending on the current mode, but the effects should be fairly +intuitive. + +Mode Selection +-------------- + +All keybindings begin with ``. + +* `g` - Grid - Switch to grid view. +* `l` - Loupe - Switch to loupe view. +* `c` - Compare - Switch to compare view. +* `p` - Path - Switch to path view. + +File Selection +-------------- + +All keybindings begin with ``. + +* `o` - Original - Select the original file. +* `1` - One - Select file one. +* `2` - Two - Select file two. +* `r` - Result - Select the result file. + +Other +----- + +All keybindings begin with ``. + +* `d` - Diff - Cycle through various diff combinations. +* `u` - Use Hunk - Place a hunk from file one or two into the result file. +* `s` - Scroll - Toggle scroll locking on and off. +* `` - Layout - Cycle through various layouts of the current view. + +* `n` - Next - Move to the next unresolved conflict. +* `N` - Previous - Move to the previous unresolved conflict. + +* `q` - Quit - Save the result file and exit Vim. Indicates to the VCS that the merge was successful and it should use the current contents of the result file as the result. +* `CC` - Cancel - Exits Vim with an error code (like :cq). Indicates to the VCS that the merge was NOT successful. + +Modes +===== + +This section describes each mode in detail. + +Grid +---- + +The grid view is used to get an overview of all files at once to get a birds' +eye view of the merge. + +### Grid Layouts + + Layout 1 Layout 2 + +-------------------+ +--------------------------+ + | Original | | One | Result | Two | + | | | | | | + +-------------------+ | | | | + | One | Two | | | | | + | | | | | | | + +-------------------+ | | | | + | Result | | | | | + | | | | | | + +-------------------+ +--------------------------+ + +### Grid-Specific Key Bindings + +All keybindings begin with ``. + +* `o` - Original - Focus the original file (only in layout 1). +* `1` - One - Focus file one. +* `2` - Two - Focus file two. +* `r` - Result - Focus the result file. +* `d` - Diff - Cycle through various diff combinations. +* `u1` - Use Hunk 1 - Place a hunk from file one into the result file. +* `u2` - Use Hunk 2 - Place a hunk from file two into the result file. + +### Grid Diffs + +1. No diff. +2. Diff the original and file one. +3. Diff the original and file two. +4. Diff file one and the result. +5. Diff file two and the result. +6. Diff the original and the result. + +Loupe +----- + +The loupe view is used to focus on and examine a single file in detail. + +### Loupe Layouts + + Layout 1 + +-------------------+ + | Any Single File | + | | + | | + | | + | | + | | + | | + | | + +-------------------+ + +### Loupe-Specific Key Bindings + +All keybindings begin with ``. + +* `o` - Original - View the original file. +* `1` - One - View file one. +* `2` - Two - View file two. +* `r` - Result - View the result file. +* `d` - Diff - Disabled. +* `u` - Use Hunk - Disabled. + +### Loupe Diffs + +No diffs are possible in loupe mode. + +Compare +------- + +The compare view is used to examine the differences between two files at +a time. + +### Compare Layouts + + Layout 1 Layout 2 + +-------------------+ +-------------------+ + | Orig | Result | | Orig | + | | | | or One | + | or | or | | or Two | + | | | | | + | One | One | +-------------------+ + | | | | One | + | or | or | | or Two | + | | | | or Result | + | Two | Two | | | + +-------------------+ +-------------------+ + +### Compare-Specific Key Bindings + +All keybindings begin with ``. + +* `o` - Original - Place the original file in the left/top window. +* `1` - One - Place file one in the right/bottom window if the original is visible, otherwise place it in the left/top window. +* `2` - Two - Place file two in the left/top window if the result is visible, otherwise place it in the right/bottom window. +* `r` - Result - Place the result file in the right/bottom window. +* `d` - Diff - Cycle through various diff combinations. +* `u` - Use Hunk - If the result file and file one/two are both visible, place a hunk from one/two into the result file. Otherwise, disabled. + +### Compare Diffs + +1. No diff. +2. Diff both windows. + +Path +---- + +The path view is used to view the flow of changed through one "path" or +"branch" of the merge. + +### Path Layouts + + Layout 1 Layout 2 + +--------------------------+ +-------------------+ + | Orig | | Result | | Orig | + | | | | | | + | | One | | | | + | | | | +-------------------+ + | | or | | | One | + | | | | | or Two | + | | Two | | | | + | | | | +-------------------+ + | | | | | Result | + +--------------------------+ | | + | | + +-------------------+ + +### Path-Specific Key Bindings + +All keybindings begin with ``. + +* `o` - Original - Focus the original file. +* `1` - One - Place file one in the center window and focus it. +* `2` - Two - Place file two in the center window and focus it. +* `r` - Result - Focus the result file. +* `d` - Diff - Cycle through various diff combinations. +* `u` - Use Hunk - Place a hunk from file one or two (whichever is currently in + the center window) into the result file. + +### Path Diffs + +1. No diff. +2. Diff the original and center windows. +3. Diff the center and result windows. +4. Diff the original and result windows. diff -r 000000000000 -r 97c9fd0ac4a4 docs/threesome.txt