diff --git a/.gitconfig b/.gitconfig index 1b77030c0..935f871b3 100644 --- a/.gitconfig +++ b/.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 diff --git a/README.md b/README.md index e8ae33f0f..9c3cf0594 100644 --- a/README.md +++ b/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. + diff --git a/scripts/ktx-compare-git b/scripts/ktx-compare-git new file mode 100755 index 000000000..6500a6a9b --- /dev/null +++ b/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