Skip to content

Commit

Permalink
Wrapper script to use ktx compare for git diff. (#919)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
MarkCallow authored Jun 14, 2024
1 parent e8a2e19 commit 8cd4fea
Show file tree
Hide file tree
Showing 3 changed files with 76 additions and 2 deletions.
7 changes: 6 additions & 1 deletion .gitconfig
Original file line number Diff line number Diff line change
@@ -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
Expand Down
38 changes: 37 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

33 changes: 33 additions & 0 deletions scripts/ktx-compare-git
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 8cd4fea

Please sign in to comment.