splice.vim / doc / splice.txt

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
*splice.txt*   A plugin for resolving three-way merge conflicts.

Splice 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, Git and Bazaar.

==============================================================================
CONTENTS                                                     *Splice-contents*

    1. Version Control Integration ............... |SpliceVCS|
        1.1 Mercurial ............................ |SpliceVCS_hg|
        1.2 Git .................................. |SpliceVCS_git|
        1.3 Bazaar ............................... |SpliceVCS_bzr|
    2. Basic Usage ............................... |SpliceUsage|
        2.1 Files ................................ |SpliceUsage_files|
        2.2 Modes ................................ |SpliceUsage_modes|
    3. Key Bindings .............................. |SpliceKeys|
        3.1 Mode Selection Keys .................. |SpliceKeys_mode|
        3.2 File Selection Keys .................. |SpliceKeys_file|
        3.3 Other Keys ........................... |SpliceKeys_other|
    4. Modes ..................................... |SpliceModes|
        4.1 Grid ................................. |SpliceModes_grid|
        4.2 Loupe ................................ |SpliceModes_loupe|
        4.3 Compare .............................. |SpliceModes_compare|
        4.4 Path ................................. |SpliceModes_path|
    5. Configuration ............................. |SpliceConfig|
        5.1 splice_debug ......................... |SpliceConfig_debug|
        5.2 splice_disable ....................... |SpliceConfig_disable|
        5.3 splice_initial_diff_grid ............. |SpliceConfig_id_grid|
        5.4 splice_initial_diff_loupe ............ |SpliceConfig_id_loupe|
        5.5 splice_initial_diff_compare .......... |SpliceConfig_id_compare|
        5.6 splice_initial_diff_path ............. |SpliceConfig_id_path|
        5.7 splice_initial_layout_grid ........... |SpliceConfig_il_grid|
        5.8 splice_initial_layout_loupe .......... |SpliceConfig_il_loupe|
        5.9 splice_initial_layout_compare ........ |SpliceConfig_il_compare|
        5.10 splice_initial_layout_path .......... |SpliceConfig_il_path|
        5.11 splice_initial_scrollbind_grid ...... |SpliceConfig_is_grid|
        5.12 splice_initial_scrollbind_loupe ..... |SpliceConfig_is_loupe|
        5.13 splice_initial_scrollbind_compare ... |SpliceConfig_is_compare|
        5.14 splice_initial_scrollbind_path ...... |SpliceConfig_is_path|
        5.15 splice_initial_mode ................. |SpliceConfig_im|
        5.16 splice_prefix ....................... |SpliceConfig_prefix|
        5.17 splice_wrap ......................... |SpliceConfig_wrap|
    6. License ................................... |SpliceLicense|
    7. Bugs ...................................... |SpliceBugs|
    8. Contributing .............................. |SpliceContributing|
    9. Changelog ................................. |SpliceChangelog|
   10. Credits ................................... |SpliceCredits|


==============================================================================
1. Version Control Integration                                     *SpliceVCS*

Splice is meant to be called by your version control system when it needs you
to resolve merge conflicts.  You will need to configure your VCS to do this
before you can use Splice.

*Note: If you'd like to use a Vim GUI instead of console vim, replace
       "vim" in the following commands with your choice of "mvim" or "gvim".

------------------------------------------------------------------------------
1.1 Mercurial                                                   *SpliceVCS_hg*

Add the following lines to "~/.hgrc": >

    [merge-tools]
    splice.executable = vim
    splice.args = -f $base $local $other $output -c 'SpliceInit'
    splice.premerge = keep
    splice.priority = 1

Mercurial will now open Vim with Splice whenever a file has merge conflicts
which need to be resolved.

------------------------------------------------------------------------------
1.2 Git                                                        *SpliceVCS_git*

Add the following lines to "~/.gitconfig": >

    [merge]
    tool = splice

    [mergetool "splice"]
    cmd = "vim -f $BASE $LOCAL $REMOTE $MERGED -c 'SpliceInit'"
    trustExitCode = true

If a "git merge" or "git pull" fails with merge conflicts you can now run
"git mergetool".  Git will loop over all the files with conflicts and allow
you to resolve them with Vim and Splice.

------------------------------------------------------------------------------
1.3 Bazaar                                                     *SpliceVCS_bzr*

For Bazaar 2.4 or greater, add the following line to bazaar.conf:
>
    bzr.mergetool.splice = vim {base} {this} {other} {result} -c 'SpliceInit'
<
Optionally, change the default merge tool by setting:
>
    bzr.default_mergetool = splice
<
For earlier versions of Bazaar, set the following entry in bazaar.conf:
>
    external_merge = vim %b %t %o %r -c 'SpliceInit'
<
You can now use Vim with Splice from "bzr qconflicts".

==============================================================================
2. Basic Usage                                                   *SpliceUsage*

Splice 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.

Splice has several "modes" to help you work with the various files.

------------------------------------------------------------------------------
2.1 Files                                                  *SpliceUsage_files*

When resolving a merge there are four files you will work with:

Original                                       *SpliceUsage_files_original*
    The original file, as it appears in the parent revision of the two
    revisions being merged.

One                                                 *SpliceUsage_files_one*
    The file as it appears in the first revision being merged.

    This is usually the "current" revision, or the one you are at when you
    run "hg merge REV").

Two                                                 *SpliceUsage_files_two*
    The file as it appears in the second revision being merged.

    This is usually the "target" revision, or the one you specify in the
    "hg merge REV" command).

Result                                           *SpliceUsage_files_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.

------------------------------------------------------------------------------
2.2 Modes                                                  *SpliceUsage_modes*

Splice has four "modes" or "views" for working with the files.

Grid                                               *SpliceUsage_modes_grid*
    Shows all four files at once to give you an overview of the merge.

    See |SpliceModes-grid| for more information.

Loupe                                             *SpliceUsage_modes_loupe*
    Shows a single file at a time for close examination of a single file.

    See |SpliceModes-loupe| for more information.

Compare                                         *SpliceUsage_modes_compare*
    Shows two files at a time for examining the movement of changes between
    pairs of files.

    See |SpliceModes-compare| for more information.

Path                                               *SpliceUsage_modes_path*
    Shows three files at a time:

      - The original
      - Either one or two
      - The result

    Used for examining how a change moves through one "path" or "branch"
    of the merge.

    See |SpliceModes-path| for more information.


==============================================================================
3. Key Bindings                                                   *SpliceKeys*

All of Splice's key mappings are prefixed with a single key to group them
together and avoid shadowing other mappings.  By default this key is '-'
(minus/hyphen).

See the |SpliceConfig_prefix| setting if you'd like to change this prefix to
something else.

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.

------------------------------------------------------------------------------
3.1 Mode Selection Keys                                      *SpliceKeys_mode*

<prefix>g                                       *Grid*
                        Switch to grid view.

<prefix>l                                      *Loupe*
                        Switch to loupe view.

<prefix>c                                    *Compare*
                        Switch to compare view.

<prefix>p                                       *Path*
                        Switch to path view.

------------------------------------------------------------------------------
3.2 File Selection Keys                                      *SpliceKeys_file*

<prefix>o                                   *Original*
                        Select the original file.

<prefix>1                                        *One*
                        Select file one.

<prefix>2                                        *Two*
                        Select file two.

<prefix>r                                     *Result*
                        Select the result file.

------------------------------------------------------------------------------
3.3 Other Keys                                              *SpliceKeys_other*

<prefix>d                                       *Diff*
                        Cycle through various diff combinations.

<prefix>D                                    *DiffOff*
                        Turn off all diffs.

<prefix>u                                    *UseHunk*
                        Place a hunk from file one or two into
                        the result file.

<prefix>s                                     *Scroll*
                        Toggle scroll locking on and off.

<prefix><space>                               *Layout*
                        Cycle through various layouts of the
                        current view.

<prefix>n                                       *Next*
                        Move to the next unresolved conflict.

<prefix>N                                   *Previous*
                        Move to the previous unresolved conflict.

<prefix>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.

<prefix>CC                                    *Cancel*
                        Exits Vim with an error code (like |:cquit|).
                        Indicates to the VCS that the merge was
                        NOT successful.

==============================================================================
4. Modes                                                         *SpliceModes*

This section describes each mode in detail.

------------------------------------------------------------------------------
4.1 Grid                                                    *SpliceModes_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                                     *SpliceModes_grid_layouts*
------------

    Layout 0                 Layout 1                        Layout 2
    +-------------------+    +--------------------------+    +---------------+
    |     Original      |    | One    | Result | Two    |    |      One      |
    |                   |    |        |        |        |    |               |
    +-------------------+    |        |        |        |    +---------------+
    |  One    |    Two  |    |        |        |        |    |     Result    |
    |         |         |    |        |        |        |    |               |
    +-------------------+    |        |        |        |    +---------------+
    |      Result       |    |        |        |        |    |      Two      |
    |                   |    |        |        |        |    |               |
    +-------------------+    +--------------------------+    +---------------+

Grid-Specific Key Bindings                          *SpliceModes_grid_keys*
--------------------------

<prefix>o                                   *Original-Grid*
                        Select the original file, but only in layout 1.

<prefix>u                                    *UseHunk-Grid*
                        Disabled in this mode.

<prefix>u1                                  *UseHunk1-Grid*
                        Place a hunk from file one into the result file.

<prefix>u2                                  *UseHunk2-Grid*
                        Place a hunk from file two into the result file.

Grid Diffs                                         *SpliceModes_grid_diffs*
----------

1. No diff.
2. Diff all files.

------------------------------------------------------------------------------
4.2 Loupe                                                  *SpliceModes_loupe*

The loupe view is used to focus on and examine a single file in detail.

Loupe Layouts                                   *SpliceModes_loupe_layouts*
-------------

    Layout 0
    +-----------------+
    | Any Single File |
    |                 |
    |                 |
    |                 |
    |                 |
    |                 |
    +-----------------+

Loupe-Specific Key Bindings                        *SpliceModes_loupe_keys*
---------------------------

<prefix>u                                    *UseHunk-Loupe*
                        Disabled in this mode.

Loupe Diffs                                       *SpliceModes_loupe_diffs*
-----------

No diffs are possible in loupe mode.

------------------------------------------------------------------------------
4.3 Compare                                              *SpliceModes_compare*

The compare view is used to examine the differences between two files at
a time.

Compare Layouts                               *SpliceModes_compare_layouts*
---------------

    Layout 0                 Layout 1
    +-------------------+    +-------------------+
    | Orig    | Result  |    | Orig              |
    |         |         |    | or One            |
    |    or   |    or   |    | or Two            |
    |         |         |    |                   |
    | One     | One     |    +-------------------+
    |         |         |    | One               |
    |    or   |    or   |    | or Two            |
    |         |         |    | or Result         |
    | Two     | Two     |    |                   |
    +-------------------+    +-------------------+

Compare-Specific Key Bindings                    *SpliceModes_compare_keys*
-----------------------------

<prefix>u                                    *UseHunk-Compare*
                        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                                   *SpliceModes_compare_diffs*
-------------

1. No diff.
2. Diff both files.

------------------------------------------------------------------------------
4.4 Path                                                    *SpliceModes_path*

The path view is used to view the flow of changed through one "path" or
"branch" of the merge.

Path Layouts                                     *SpliceModes_path_layouts*
------------

    Layout 0                        Layout 1
    +--------------------------+    +-------------------+
    | Orig   |        | Result |    | Orig              |
    |        | One    |        |    |                   |
    |        |        |        |    +-------------------+
    |        |   or   |        |    | One               |
    |        |        |        |    | or Two            |
    |        | Two    |        |    +-------------------+
    |        |        |        |    | Result            |
    |        |        |        |    |                   |
    +--------------------------+    +-------------------+
    

Path-Specific Key Bindings                          *SpliceModes_path_keys*
--------------------------

<prefix>u                                    *UseHunk-Path*
                        Place a hunk from file one or two (whichever
                        is currently in the center window) into the
                        result file.

Path Diffs                                         *SpliceModes_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.

==============================================================================
5. Configuration                                                *SpliceConfig*

You can tweak the behavior of Splice by setting a few variables in your
|vimrc| file. For example: >

    let g:splice_initial_mode = "compare"
    let g:splice_initial_layout_grid = 2
    let g:splice_initial_layout_compare = 1

------------------------------------------------------------------------------
5.1 g:splice_debug                                        *SpliceConfig_debug*

Set this to 1 to force Splice to reload every time its file is sourced.

Options: 0 or 1
Default: 0 (Splice is loaded only once)

------------------------------------------------------------------------------
5.2 g:splice_disable                                    *SpliceConfig_disable*

Set this to 1 to disable Splice entirely.

Useful if you use the same ~/.vim folder on multiple machines and some of
them may not have Python support.

Options: 0 or 1
Default: 0 (Splice is enabled as usual)

------------------------------------------------------------------------------
5.3 g:splice_initial_diff_grid                          *SpliceConfig_id_grid*

Set this to change the diff the grid mode starts in.

See |SpliceModes-grid-diffs| for the list of diffs.

Options: 0, or 1
Default: 0

------------------------------------------------------------------------------
5.4 g:splice_initial_diff_loupe                        *SpliceConfig_id_loupe*

Set this to change the diff the loupe mode starts in.

See |SpliceModes-loupe-diffs| for the list of diffs.

Options: 0
Default: 0

------------------------------------------------------------------------------
5.5 g:splice_initial_diff_compare                    *SpliceConfig_id_compare*

Set this to change the diff the compare mode starts in.

See |SpliceModes-compare-diffs| for the list of diffs.

Options: 0 or 1
Default: 0

------------------------------------------------------------------------------
5.6 g:splice_initial_diff_path                          *SpliceConfig_id_path*

Set this to change the diff the path mode starts in.

See |SpliceModes-path-diffs| for the list of diffs.

options: 0, 1, 2, 3, or 4
Default: 0

------------------------------------------------------------------------------
5.7 g:splice_initial_layout_grid                        *SpliceConfig_il_grid*

Set this to change the layout the grid mode starts in.

See |SpliceModes-grid-layouts| for the list of layouts.

Options: 0, 1, or 2
Default: 0

------------------------------------------------------------------------------
5.8 g:splice_initial_layout_loupe                      *SpliceConfig_il_loupe*

Set this to change the layout the loupe mode starts in.

See |SpliceModes-loupe-layouts| for the list of layouts.

Options: 0
Default: 0

------------------------------------------------------------------------------
5.9 g:splice_initial_layout_compare                  *SpliceConfig_il_compare*

Set this to change the layout the compare mode starts in.

See |SpliceModes-compare-layouts| for the list of layouts.

Options: 0 or 1
Default: 0

------------------------------------------------------------------------------
5.10 g:splice_initial_layout_path                       *SpliceConfig_il_path*

Set this to change the layout the path mode starts in.

See |SpliceModes-path-layouts| for the list of layouts.

Options: 0 or 1
Default: 0

------------------------------------------------------------------------------
5.11 g:splice_initial_scrollbind_grid                   *SpliceConfig_is_grid*

Set this to 1 to enable |scrollbind| by default in grid mode.

Options: 0 or 1
Default: 0

------------------------------------------------------------------------------
5.12 g:splice_initial_scrollbind_loupe                 *SpliceConfig_is_loupe*

Set this to 1 to enable |scrollbind| by default in loupe mode.

Options: 0 or 1
Default: 0

------------------------------------------------------------------------------
5.13 g:splice_initial_scrollbind_compare             *SpliceConfig_is_compare*

Set this to 1 to enable |scrollbind| by default in compare mode.

Options: 0 or 1
Default: 0

------------------------------------------------------------------------------
5.14 g:splice_initial_scrollbind_path                   *SpliceConfig_is_path*

Set this to 1 to enable |scrollbind| by default in path mode.

Options: 0 or 1
Default: 0

------------------------------------------------------------------------------
5.15 g:splice_initial_mode                                   *SpliceConfig_im*

Set this to change the mode Splice initially starts up in.

See |SpliceModes| for a description of each mode.

Options: "grid", "loupe", "compare", or "path"
Default: "grid"

------------------------------------------------------------------------------
5.16 g:splice_prefix                                     *SpliceConfig_prefix*

Set this to change the prefix Splice will bind all of its mappings to.

For example: >

    let g:splice_prefix = "<leader>t"

Will make all Splice commands start with <leader>t instead of the default '-'.

Options: Any valid key mapping string
Default: "-"

------------------------------------------------------------------------------
5.17 g:splice_wrap                                         *SpliceConfig_wrap*

Set this to "wrap" or "nowrap" to set |wrap| or |nowrap| on all windows by
default.

By default Splice will use your default settings.

Options: "wrap", "nowrap"
Default: None (use the default settings)

==============================================================================
6. License                                                     *SpliceLicense*

Splice is copyright Steve Losh & contributors, 2011+ and is licensed
under the MIT/X11 license.

==============================================================================
7. Bugs                                                           *SpliceBugs*

Please report any bugs you may find on the GitHub issue tracker:

    http://github.com/sjl/splice.vim/issues

==============================================================================
8. Contributing                                           *SpliceContributing*

Think you can make Splice better?  Awesome.  New contributors are always
welcome.

Fork the project on BitBucket or GitHub and send a pull request.

    BitBucket: http://bitbucket.org/sjl/splice.vim
    GitHub:    http://github.com/sjl/splice.vim

==============================================================================
9. Changelog                                                 *SpliceChangelog*

v1.0.0
    * Rename to Splice.
    * Change the default prefix to '-' instead of <localleader>.
v0.2.0
    * Add threesome_leader as a config option.
v0.1.1
    * Fix a bug when the user doesn't use :set hidden.
v0.1.0
    * Preliminary "it probably won't eat your data" release!
v0.0.8
    * A bunch of cleanup.
v0.0.7
    * Add use hunk functionality.
v0.0.6
    * Add the HUD.
    * Configurable wrapping.
v0.0.5
    * Configurable scrollbinding.
v0.0.4
    * Basic configuration settings.
v0.0.3
    * Multiple layout support.
v0.0.2
    * There's still not much working, but at least there's some help now!
v0.0.1
    * Oh god nothing works please don't use this for real work yet.

==============================================================================
10. Credits                                                    *SpliceCredits*

Splice was originally written by Steve Losh after he got fed up with the lack
of a powerful, intuitive, beautiful three-way merge program on OS X.

A lot of the inspiration for the layout of the code came from vim-orgmode.

The UI is a combination of ideas from Conflict2Diff.vim, Fugitive.vim, and
Adobe Lightroom.

==============================================================================

 vim:ts=4:et:ft=help:
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.