David Aguilar [off-list ref] writes:
I'm personally not opposed to the vimdiff4 variants (we already have 3
others) but what I think might be missing is a bit of documentation
that documents the builtin tools and their variants.
Hmph, are we encouraging everybody to add yet another variant? I
wonder if we can stop at adding a single "vimdiffX" variant that
takes the layout information (like the one this vimdiff4 passes to
the underlying tool via the command line option) in a configuration
variable and stop adding more variants, or is vim's specification of
the layout we use here via the command line not flexible enough to
serve all future needs? I also wonder if all the existing vimdiff
variants can be done in terms of such a vimdiffX implementation.
Right now git-mergetool.txt includes config/mergetool.txt for
documenting its config variables. It might be worth having a common
"mergetools.txt" where the builtin tools and variants can be
documented and then we can include that file from both
git-mergetool.txt and git-difftool.txt.
That would be a good place to write up the differences between the
variants, and the diagram you included in the commit message would be
helpful there as well.
Yup, in any case, I do like the suggestion to document the variants.
Thanks, both.
Thanks David and Juno for your feedback.
I completely agree that adding another vimdiffX variant is ... not elegant.
So I've been thinking a bit more about how this whole "vim layout" mechanism can
be made more generic and this is what I came up with:
1. Let's add a new configuration variable to the "vimdiff" merge tool called
"layout":
[mergetool "vimdiff"]
layout = ...
2. If this new variable is *not* present, vim will behave in the same way it
does today (ie. a top row with the local, base and remote buffers, and a
bottom row with the merged buffer).
3. In all other cases, the contents of the "layout" variable will be
intepreted following these rules:
- ";" is used to separate "tab descriptors"
- "," is used to separate "row descriptors"
- "|" is used to separate "column descriptors"
- "+" is used to load buffers that won't be displayed by default
This will be better understood with some examples that emulate the behavior
of the current "vimdiff", "vimdiff1", "vimdiff2" and "vimdiff3" variants as
well as the proposed "vimdiff4" one:
vimdiff --> layout = "LOCAL | BASE | REMOTE, MERGED"
------------------------------------------
| | | |
| LOCAL | BASE | REMOTE |
| | | |
------------------------------------------
| |
| MERGED |
| |
------------------------------------------
vimdiff1 --> layout = "LOCAL* | REMOTE"
------------------------------------------
| | |
| | |
| | |
| LOCAL | REMOTE |
| | |
| | |
| | |
------------------------------------------
NOTE: In this case (where there is no "MERGED"
buffer specified in the "layout" string), a "*"
is needed to indicate which file will be the one
containing the final version of the file after
resolving conflicts.
vimdiff2 --> layout = "LOCAL | MERGED | REMOTE"
------------------------------------------
| | | |
| | | |
| | | |
| LOCAL | BASE | REMOTE |
| | | |
| | | |
| | | |
| | | |
------------------------------------------
vimdiff3 --> layout = "LOCAL + REMOTE + BASE + MERGED"
------------------------------------------
| |
| |
| |
| MERGED |
| |
| |
| |
------------------------------------------
NOTE: LOCAL, REMOTE and BASE are loaded as hidden
buffers and you need to recall them explicitely.
vimdiff4 --> layout = "BASE | LOCAL | REMOTE, MERGED; BASE | LOCAL; BASE | REMOTE"
------------------------------------------
| <TAB #1> | TAB #2 | TAB #3 | |
------------------------------------------
| | | |
| LOCAL | BASE | REMOTE |
| | | |
------------------------------------------
| |
| MERGED |
| |
------------------------------------------
------------------------------------------
| TAB #1 | <TAB #2> | TAB #3 | |
------------------------------------------
| | |
| | |
| | |
| BASE | LOCAL |
| | |
| | |
| | |
------------------------------------------
------------------------------------------
| TAB #1 | TAB #2 | <TAB #3> | |
------------------------------------------
| | |
| | |
| | |
| BASE | REMOTE |
| | |
| | |
| | |
------------------------------------------
The nice thing about this approach is that, as we have seen, it is generic
enough to rule all current variants obsolete.
So, please let me know what you think about this:
* Do you like this approach? Or am I trying to crack a nut with a sledgehammer
by making the whole thing too complex?
* In case you like it, should we keep the old "vimdiff1", "vimdiff2" and
"vimdiff3" variants for backwards compatibility?
If the answer is "yes", I'll just alias them to the new "layout" mechanism
so that the amount of extra code needed for supporting them is minimal.
If you tell me you like this proposal, I'll go ahead and implement a patch for
all of this, taking into consideration David's suggestions for avoiding problems
with file with spaces in their names and also adding new documentation for all
of this.
NOTE: The only non-trivial thing about implementing this is how to parse the
"layout" variable syntax *in bash* to convert it into a sequence of vim
commands that achieves the expected outcome... but seems like a funny
weekend project :)
If you think it is not worth the effort, let me know if it is OK to just add
"vimdiff4" + documentation instead for now (or something else).
Thanks.