Wrapper script to use ktx compare for git diff. (#919)

Those wishing to use this must run, or have run, install-gitconfig.sh so
that .gitconfig, which now includes a "ktx-compare" diff command will be
included by their repo clone's `.git/config`.

They need to have the `ktx` command installed and in $PATH.

They need to add the line

  *.ktx2 binary diff=ktx-compare

to their clone's .git/info/attributes. This is not included in the
repo's .gitattributes because not everyone will have the ktx command
installed. This will not work in a user-global or system-global Git
attributes file because those are lower priority than `.gitattributes`
so are read first and `.gitattributes` already has an entry for
`*.ktx2`, indicating `binary`, which overrides anything from the global
files.

Will be happy to accept a PR to add a .ps1 equivalent script.

.gitconfig

@@ -1,6 +1,11 @@
-# Copyright 2016-2020 The Khronos Group Inc.
+# Copyright 2016-2024 The Khronos Group Inc.
 # SPDX-License-Identifier: Apache-2.0
 
+# Use ktx compare for diff'ing .ktx2 files.
+# Note ktx-compare-git expects `ktx` to be in the user's path
+[diff "ktx-compare"]
+    command = bash scripts/ktx-compare-git
+
 # Filters used by KTX repo
 [filter "keyworder"]
     smudge = bash scripts/expand_kw %f

README.md

@@ -34,7 +34,9 @@ Javascript wrapper for Basis Universal formats. For use with KTX parsers written
 - *libktx.jar, libktx-jni* - Java wrapper and native interface library.
 [`interface/java_binding`](https://github.com/KhronosGroup/KTX-Software/tree/main/interface/java_binding)
 - *ktx* - a generic command line tool for managing KTX2 files with subcommands.[`tools/ktx`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/ktx)
+  - *ktx compare* - Compare two KTX2 files
   - *ktx create* - Create a KTX2 file from various input files
+  - *ktx deflate* - Deflate a KTX2 file with zstd or ZLIB
   - *ktx extract* - Export selected images from a KTX2 file
   - *ktx encode* - Encode a KTX2 file
   - *ktx transcode* - Transcode a KTX2 file
@@ -122,4 +124,38 @@ these files.
 
 ### Useful Tools
 
-For finding strings within the KTX-Software source use `scripts/gk`. Type `scripts/gk -h` for help. `gk` avoids looking in any build directories, `.git`, `external` or `tests/cts`.
+#### scripts/gk
+
+For finding strings within the KTX-Software source. Type `scripts/gk -h` for help. `gk` avoids looking in any build directories, `.git`, `external` or `tests/cts`.
+
+#### scripts/ktx-compare-git
+
+Wrapper that allows use of `ktx compare` when using `git diff` on KTX2 files.
+Together with this, `.gitconfig` now includes a *ktx-compare* diff command.
+Those wishing to use this must run, or have run, install-gitconfig.{ps1,sh}
+as described above for keyword expansion so that `.gitconfig` is
+included by your local `.git/config`.
+    
+You need to have the `ktx` command installed in a directory on your $PATH.
+    
+You need to add the line
+
+``` 
+*.ktx2 binary diff=ktx-compare
+```
+  
+to your repo clone's `.git/info/attributes`. This is not included in the repo's
+`.gitattributes` because not everyone will have the `ktx` command installed nor have `.gitconfig` included by `.git/config`.
+
+*NOTE:* This line in a user-global or system-global Git attributes file will not 
+work because those are lower priority than `.gitattributes` so are read first
+and `.gitattributes` already has an entry for *.ktx2, indicating binary, which
+overrides anything from the global files.
+
+To set up your `tests/cts` submodule to use this, copy the *ktx-compare* diff
+command to `.git/modules/tests/cts/config`. Depending on when you set up the
+submodule and when you ran `install-gitconfig.sh`, it may already be there.
+Add the attribute line to `.git/modules/tests/cts/info/attributes`.
+
+We will be happy to accept a PR to add a .ps1 equivalent script.
+

scripts/ktx-compare-git

@@ -0,0 +1,33 @@
+#! /usr/bin/env bash
+# -*- tab-width: 4; -*-
+# vi: set sw=2 ts=4:
+
+# Copyright 2024 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# Wrapper for git diff to use ktx compare.
+
+# Per https://git-scm.com/docs/git/2.18.0#Documentation/git.txt-codeGITEXTERNALDIFFcode
+# git diff sends 7 arguments:
+#    path old-file old-hex old-mode new-file new-hex new-mode
+
+if [ $# -ne 7 ]; then
+  echo "$0: Git did not provide the expected 7 arguments."
+  exit 1
+fi
+
+oldfile=$2
+newfile=$5
+
+#echo "oldfile = $oldfile"
+#echo "newfile = $newfile"
+
+ktx compare $oldfile $newfile
+# Mask ktx compare's exit code. git diff expects the diff program to exit
+# without error even when there are differences.
+status=$?
+if [ $status -eq 7 ]; then
+  exit 0
+else
+  exit $status
+fi