tests: Load screendump files with "git vimdumps"
Also, fold the difference part and the bottom part for the
identical screendump files.
closes: #16380
Co-authored-by: D. Ben Knoble <ben.knoble+github@gmail.com>
Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/doc/tags b/runtime/doc/tags
index 2fc28d7..9310df8 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -7926,6 +7926,7 @@
gg motion.txt /*gg*
gh visual.txt /*gh*
gi insert.txt /*gi*
+git-vimdumps terminal.txt /*git-vimdumps*
gj motion.txt /*gj*
gk motion.txt /*gk*
glob() builtin.txt /*glob()*
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index 1fcc470..43b5e5f 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -494,6 +494,12 @@
Environment variables are used to pass information to the running job:
VIM_SERVERNAME v:servername
+ *git-vimdumps*
+There exists a git-difftool extension called `git-vimdumps` that can be used
+to conveniently inspect screendump files and diff them. Please see in the Vim
+Repository the file `src/testdir/commondumps.vim` on how to create and use
+this git extension.
+
==============================================================================
2. Terminal functions *terminal-function-details*
diff --git a/runtime/syntax/testdir/README.txt b/runtime/syntax/testdir/README.txt
index b96e8f6..6703228 100644
--- a/runtime/syntax/testdir/README.txt
+++ b/runtime/syntax/testdir/README.txt
@@ -199,6 +199,9 @@
Viewing generated screendumps (submitted for a pull request)
------------------------------------------------------------
+Note: There is also a "git difftool" extension described in
+ src/testdir/commondumps.vim
+
First, you need to check out the topic branch with the proposed changes and
write down a difference list between the HEAD commit (index) and its parent
commit with respect to the changed "dumps" filenames:
diff --git a/src/testdir/README.txt b/src/testdir/README.txt
index 203c324..c7067ac 100644
--- a/src/testdir/README.txt
+++ b/src/testdir/README.txt
@@ -162,6 +162,8 @@
VIEWING GENERATED SCREENDUMPS (submitted for a pull request):
+Note: There is also a "git difftool" extension described in ./commondumps.vim.
+
First, you need to check out the topic branch with the proposed changes and
write down a difference list between the HEAD commit (index) and its parent
commit with respect to the changed "dumps" filenames:
diff --git a/src/testdir/commondumps.vim b/src/testdir/commondumps.vim
index 1211ae9..3dbdab5 100644
--- a/src/testdir/commondumps.vim
+++ b/src/testdir/commondumps.vim
@@ -1,7 +1,112 @@
vim9script
-# (Script-local.)
+# See below on how to configure the git difftool extension
+
+# Extend "git difftool" with the capability for loading screendump files.
+if v:progname =~? '\<g\=vimdiff$'
+ # Let "(g)vimdiff" render other files.
+ if [argv(0), argv(1)]
+ ->filter((_: number, fname: string) =>
+ fname =~? '^\%(/dev/null\|.\+\.dump\)$')
+ ->len() == 2
+ try
+ if argv(0) ==? '/dev/null'
+ term_dumpload(argv(1))
+ elseif argv(1) ==? '/dev/null'
+ term_dumpload(argv(0))
+ else
+ term_dumpdiff(argv(0), argv(1))
+ endif
+ finally
+ silent bwipeout 1 2
+ endtry
+ endif
+
+ # Always stop from further sourcing this script for "(g)vimdiff".
+ finish
+endif
+
+# CONSIDER ALTERNATIVES FOR ENABLING THE ABOVE EXTENSION.
#
+# For convenience, it is assumed that there is a defined "$VIM_FORK_PATHNAME"
+# environment variable holding an absolute pathname for the root directory of
+# this repository.
+#
+#
+# A. USE Git FOR CONFIGURATION.
+#
+# Define the following Git variables with "git config --edit --local" (where
+# the "vimdumps" name is arbitrary):
+#
+# ------------------------------------------------------------------------------
+# [diff]
+# tool = vimdumps
+# [difftool.vimdumps]
+# cmd = vimdiff -S "${VIM_FORK_PATHNAME:?}"/src/testdir/commondumps.vim -o -- "$LOCAL" "$REMOTE"
+# ------------------------------------------------------------------------------
+#
+# Rendered screendump files (among other files) between revisions can now be
+# compared, two at a time, by using "git difftool", e.g.:
+# git difftool 50423ab8~1 50423ab8
+# git difftool 50423ab8~1 50423ab8 -- '**/*.dump'
+#
+# The raw files can also be examined:
+# :all
+#
+#
+# B. USE Bash FOR CONFIGURATION (on Debian GNU/Linux).
+#
+# 1. Make an alias that sources this file, e.g.:
+# alias git_vimdiff="git difftool -x 'vimdiff -S "${VIM_FORK_PATHNAME:?}"/vim/src/testdir/commondumps.vim -o --'"
+#
+# 2. Enable programmable completion for the alias, e.g.:
+# cat ~/.local/share/bash-completion/completions/git_vimdiff
+#
+# ------------------------------------------------------------------------------
+# ## Consider (un)setting "$BASH_COMPLETION_USER_DIR" and/or "$XDG_DATA_HOME" so
+# ## that this file can be found and sourced; look for these variables in the
+# ## "/usr/share/bash-completion/bash_completion" script.
+# ##
+# ## Look for __git_complete() examples in the header comment of the sourced
+# ## "/usr/share/bash-completion/completions/git" script.
+# [ -r /usr/share/bash-completion/completions/git ] &&
+# . /usr/share/bash-completion/completions/git &&
+# __git_complete git_vimdiff _git_difftool
+# ------------------------------------------------------------------------------
+#
+# Rendered screendump files (among other files) between revisions can now be
+# compared, two at a time, by using the alias, e.g.:
+# git_vimdiff 50423ab8~1 50423ab8
+# git_vimdiff 50423ab8~1 50423ab8 -- '**/*.dump'
+#
+# The raw files can also be examined:
+# :all
+
+
+# Script-local functions
+#
+# Fold the difference part and the bottom part when the top and the bottom
+# parts are identical.
+def FoldDumpDiffCopy()
+ try
+ normal mc
+ # Shape the pattern after get_separator() from "terminal.c".
+ const separator: string = '^\(=\+\)\=\s\S.*\.dump\s\1$'
+ const start_lnum: number = search(separator, 'eW', (line('$') / 2))
+ if start_lnum > 0
+ const end_lnum: number = search(separator, 'eW')
+ if end_lnum > 0 && getline((start_lnum + 1), (end_lnum - 1))
+ ->filter((_: number, line: string) => line !~ '^\s\+$')
+ ->empty()
+ setlocal foldenable foldmethod=manual
+ exec 'normal ' .. start_lnum .. 'GzfG'
+ endif
+ endif
+ finally
+ normal `c
+ endtry
+enddef
+
# Render a loaded screendump file or the difference of a loaded screendump
# file and its namesake file from the "dumps" directory.
def Render()
@@ -13,6 +118,7 @@
fnamemodify(failed_fname, ':p:h:h') .. '/dumps')
if filereadable(dumps_fname)
term_dumpdiff(failed_fname, dumps_fname)
+ FoldDumpDiffCopy()
else
term_dumpload(failed_fname)
endif
@@ -21,6 +127,8 @@
endtry
enddef
+# Public functions
+#
# Search for the "failed" directory in the passed _subtreedirname_ directories
# (usually "\<src\>" or "\<syntax\>") and, if found, select its passed _count_
# occurrence, add all its "*.dump" files to the argument list and list them;