I has a loupe!
| author |
Steve Losh <steve@stevelosh.com> |
| date |
Sun, 12 Jun 2011 23:33:31 -0400 |
| parents |
97c9fd0ac4a4 |
| children |
0e3a284792b2 |
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 `<localleader>` for all of its key bindings to avoid
clashing with global mappings. If you've never used `<localleader>` 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 `<localleader>`.
* `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 `<localleader>`.
* `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 `<localleader>`.
* `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.
* `<space>` - 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 `<localleader>`.
* `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 `<localleader>`.
* `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 `<localleader>`.
* `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 `<localleader>`.
* `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.