Fernando Ramos <greenfoo@xxxxxx> writes: >> It looks like it's emitting a new warning from the "Makefile" in >> check-docs: >> >> $ (make clean && make check-docs) >/dev/null 2>&1; make check-docs >> make -C Documentation lint-docs >> make[1]: Entering directory '/home/avar/g/git/Documentation' >> make[1]: Nothing to be done for 'lint-docs'. >> make[1]: Leaving directory '/home/avar/g/git/Documentation' >> removed but documented: git-difftool--vimdiff >> removed but documented: git-mergetool--vimdiff >> removed but documented: git-version > > Looking at how the Makefile works it looks like this error is triggered > because... > > 1. I have created these two new files: > - Documentation/git-difftool--vimdiff.txt > - Documentation/git-mergetool--vimdiff.txt > > 2. None of them are real programs (such as "git-clone") or scripts (such as > "git-mergetool--lib.sh") > > All the other "Documentation/*.txt" files are associated to "something" that > can be executed, but not these two (they are only meant to be accessed from "git > help" / "man"). Thanks for noticing and reporting, Ævar. I think the right place to describe how vimdiff or other configuration should be configured should live next to configuration documentation for other backends. Documentation/git-mergetool.txt is the main entry point for those who want to learn about "git mergetool", i.e. "git mergetool --help" shows what's in there. The documentation talks about the "mergetool" front-end, and then includes config/mergetool.txt for the configuration files. After all, the topic adds only one mergetool.<tool>.layout configuration variable. The file config/mergetool.txt would be the place to describe that variable, after the entry for mergetool.meld.useAutoMerge, which is already is about a variable that is specific to a particular backend. If we can successfully can go this route, we do not need any new file added at all. Alternatively, in the longer run, we may want backend specific information in the "git mergetool --help" documentation. Maybe vimdiff is the first and currently only such backend that wants documentation specific to it, but it does not has to stay that way forever. So adding a new section "BACKENDS SPECIFIC HINTS" after "TEMPORARY FILES" section, and add "VIMDIFF" as its first (and currently only) subsection, would be a reasonable thing to do. Create a Documentation/mergetools/ subdirectory, add vimdiff.txt file in there, move the most of what is in git-mergetool--vimdiff.txt, and include it from Documentation/git-mergetool.txt, perhaps like the attached patch outlines? diff --git c/Documentation/config/mergetool.txt w/Documentation/config/mergetool.txt index cafbbef46a..19ca39d43d 100644 --- c/Documentation/config/mergetool.txt +++ w/Documentation/config/mergetool.txt @@ -45,6 +45,11 @@ mergetool.meld.useAutoMerge:: value of `false` avoids using `--auto-merge` altogether, and is the default value. +mergetool.vimdiff.layout:: + The vimdiff backend uses this variable to control how its split + windows look like. See BACKEND SPECIFIC HINTS section of + linkgit:git-mergetool[1] for details. + mergetool.hideResolved:: During a merge Git will automatically resolve as many conflicts as possible and write the 'MERGED' file containing conflict markers around diff --git c/Documentation/git-mergetool.txt w/Documentation/git-mergetool.txt index e587c7763a..6cf3734544 100644 --- c/Documentation/git-mergetool.txt +++ w/Documentation/git-mergetool.txt @@ -113,6 +113,16 @@ Setting the `mergetool.keepBackup` configuration variable to `false` causes `git mergetool` to automatically remove the backup as files are successfully merged. +BACKEND SPECIFIC HINTS +---------------------- + +Here we'll give backend specific hints. + +vimdiff +~~~~~~~ +include::mergetools/vimdiff.txt[] + + GIT --- Part of the linkgit:git[1] suite diff --git c/Documentation/mergetools/vimdiff.txt w/Documentation/mergetools/vimdiff.txt new file mode 100644 index 0000000000..1cac121283 --- /dev/null +++ w/Documentation/mergetools/vimdiff.txt @@ -0,0 +1,11 @@ +vimdiff +~~~~~~~ + +Vimdiff backend allows `mergetools.vimdiff.layout` to specify how +the split window is used ... + +Layout +^^^^^^ + +Text. +
