# HG changeset patch # User Steve Losh # Date 1307988574 14400 # Node ID 27f2b1ae4f34e26a14e9f69e79ab2cd1533f45cd # Parent 48a4ac7ce6326b66680dc1f19c1e0e88bc0dea79 Moar help. diff -r 48a4ac7ce632 -r 27f2b1ae4f34 README.markdown --- a/README.markdown Mon Jun 13 13:36:32 2011 -0400 +++ b/README.markdown Mon Jun 13 14:09:34 2011 -0400 @@ -65,208 +65,4 @@ Read the docs: `:help threesome` -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 48a4ac7ce632 -r 27f2b1ae4f34 doc/threesome.txt --- a/doc/threesome.txt Mon Jun 13 13:36:32 2011 -0400 +++ b/doc/threesome.txt Mon Jun 13 14:09:34 2011 -0400 @@ -25,13 +25,16 @@ 1.1 Files ..................... |ThreesomeUsage-files| 1.2 Modes ..................... |ThreesomeUsage-modes| 2. Key Bindings ................... |ThreesomeKeys| + 2.1 Mode Selection Keys ....... |ThreesomeKeys-mode| + 2.2 File Selection Keys ....... |ThreesomeKeys-file| + 2.3 Other Keys ................ |ThreesomeKeys-other| 3. Modes .......................... |ThreesomeModes| 3.1 Grid ...................... |ThreesomeModes-grid| 3.2 Loupe ..................... |ThreesomeModes-loupe| 3.3 Compare ................... |ThreesomeModes-compare| 3.4 Path ...................... |ThreesomeModes-path| 4. Configuration .................. |ThreesomeConfig| - 4.1 threesome_disable ......... |threesome_disable| + 4.1 threesome_disable ......... |ThreesomeConfig-disable| 5. License ........................ |ThreesomeLicense| 6. Bugs ........................... |ThreesomeBugs| 7. Contributing ................... |ThreesomeContributing| @@ -44,6 +47,15 @@ Threesome takes a lot of inspiration for its user interface from Adobe Lightroom, a photo editing program. +When resolving merge conflicts your goal is: + + - Examine the three files describing the changes being merged. + - Combine these changes into a fourth file (the "result"). + - Save the result to disk. + - Exit Vim with a non-error status code to tell the VCS the merge succeeded. + +Threesome has several "modes" to help you work with the various files. + ------------------------------------------------------------------------------ 1.1 Files *ThreesomeUsage-files* @@ -74,10 +86,7 @@ ------------------------------------------------------------------------------ 1.2 Modes *ThreesomeUsage-modes* -Threesome has four "modes" or "views" for working with these files. - -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.** +Threesome has four "modes" or "views" for working with the files. Grid *ThreesomeUsage-modes-grid* Shows all four files at once to give you an overview of the merge. @@ -107,3 +116,239 @@ See |ThreesomeModes-path| for more information. +============================================================================== +2. Key Bindings *ThreesomeKeys* + +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 |maplocalleader| documentation and +configure a key for it. + +All keybindings are used across (almost) all modes. + +The behavior of some of them changes depending on the current mode, but the +effects should be fairly intuitive. + +------------------------------------------------------------------------------ +2.1 Mode Selection Keys *ThreesomeKeys-mode* + +g *Grid* + Switch to grid view. + +l *Loupe* + Switch to loupe view. + +c *Compare* + Switch to compare view. + +p *Path* + Switch to path view. + +------------------------------------------------------------------------------ +2.2 File Selection Keys *ThreesomeKeys-file* + +o *Original* + Select the original file. + +1 *One* + Select file one. + +2 *Two* + Select file two. + +r *Result* + Select the result file. + +------------------------------------------------------------------------------ +2.3 Other Keys *ThreesomeKeys-other* + +d *Diff* + Cycle through various diff combinations. + +u *UseHunk* + 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. + +============================================================================== +3. Modes *ThreesomeModes* + +This section describes each mode in detail. + +------------------------------------------------------------------------------ +3.1 Grid *ThreesomeModes-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 +-------------------------- + +o *Original* + Select the original file, but only in layout 1. + +u *UseHunk* + Disabled in this mode. + +u1 *UseHunk1* + Place a hunk from file one into the result file. + +u2 *UseHunk2* + Place a hunk from file two into the result file. + +Grid Diffs +---------- + +1. No diff. +2. Diff all files. +3. Diff the original and file one. +4. Diff the original and file two. +5. Diff file one and the result. +6. Diff file two and the result. +7. Diff the original and the result. + +------------------------------------------------------------------------------ +3.2 Loupe *ThreesomeModes-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 +--------------------------- + +u *UseHunk* + Disabled in this mode. + +Loupe Diffs +----------- + +No diffs are possible in loupe mode. + +------------------------------------------------------------------------------ +3.3 Compare *ThreesomeModes-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 +----------------------------- + +u *UseHunk* + 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 files. + +------------------------------------------------------------------------------ +3.4 Path *ThreesomeModes-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 +-------------------------- + +u *UseHunk* + 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.