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 2fc28d724165a3ff14105cdedbe670b0366450ce..9310df8f7c3388fab3b7628691b9d657410858f0 100644 (file)
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -7926,6 +7926,7 @@ gf        editing.txt     /*gf*
 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 1fcc470db8a12728bedbe7665638384c598b91a2..43b5e5f247a8a25298b9b8810a66b2eefa7314db 100644 (file)
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -494,6 +494,12 @@ ConPTY problems have been fixed "winpty" will be preferred.
 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 b96e8f6c657d0a299910b7044171565acec9b899..6703228b9ba76852746fe8fc21145b7473f46730 100644 (file)
--- a/runtime/syntax/testdir/README.txt
+++ b/runtime/syntax/testdir/README.txt
@@ -199,6 +199,9 @@ You can now examine the extracted screendumps:
 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 203c3245b7c5806d0acad44cbf1e2d3e30f60223..c7067ac0249aae040a3af088f2e0ecfc5c90fe0d 100644 (file)
--- a/src/testdir/README.txt
+++ b/src/testdir/README.txt
@@ -162,6 +162,8 @@ You can now examine the extracted screendumps:
 
 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 1211ae9c4ea4954f1dd493284a87c28e9db1cbfe..3dbdab5328af126c1e44e7e0c57cad59b3025700 100644 (file)
--- 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 @@ def Render()
                        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 @@ def Render()
   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;