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>

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()*

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*
 

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:

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:

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;