.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "zs-diff" "1" "July 31, 2022" "" ""
.hy
.SH NAME
.PP
\f[I]zs-diff\f[R] is a terminal-based syntax-aware diff.
The syntax-aware part means that comparison isn\[cq]t sensible to
formatting changes and understands general structure of its input.
.PP
The primary purpose of the utility is to be used as external diff by
\f[V]git\f[R].
.SH INVOCATION
.SS Manual Form
.PP
\f[V]zs-diff\f[R] \f[V][options...]\f[R] \f[I]old-file\f[R]
\f[I]new-file\f[R]
.PP
To be used in a shell.
.SS Git Form
.PP
\f[V]zs-diff\f[R] \f[V][options...]\f[R] \f[I]path\f[R]
\f[I]old-file\f[R] \f[I]old-hex\f[R] \f[I]old-mode\f[R]
\f[I]new-file\f[R] \f[I]new-hex\f[R] \f[I]new-mode\f[R]
.PP
When Git calls external diff for a changed file.
.SS Git Rename Form
.PP
\f[V]zs-diff\f[R] \f[V][options...]\f[R] \f[I]path\f[R]
\f[I]old-file\f[R] \f[I]old-hex\f[R] \f[I]old-mode\f[R]
\f[I]new-file\f[R] \f[I]new-hex\f[R] \f[I]new-mode\f[R]
\f[I]new-path\f[R] \f[I]rename-msg\f[R]
.PP
When Git calls external diff for renamed and possibly changed file.
.SH USAGE AND BEHAVIOUR
.SS Invoking manually
.PP
Just do:
.IP
.nf
\f[C]
zs-diff old-file new-file
\f[R]
.fi
.SS When Invoked by Git
.PP
If parsing fails when Git-like invocation is used, the tool attempts to
invoke \f[V]git\f[R] with \f[V]--no-ext-diff\f[R] to do the diff.
Unfortunately, Git doesn\[cq]t supply enough information for a proper
invocation and \f[V]git\f[R]-header you\[cq]ll see will be with blob
hashes or temporary paths.
.SS Use with Git without Configuration
.PP
Use \f[V]$GIT_EXTERNAL_DIFF\f[R]:
.IP
.nf
\f[C]
GIT_EXTERNAL_DIFF=\[aq]zs-diff --color\[aq] git show --ext-diff
\f[R]
.fi
.SS Local Git integration
.PP
Add \f[V]zs-diff\f[R] as a diff tool to \f[V]git\f[R] with these lines
(\f[V].git/config\f[R]):
.IP
.nf
\f[C]
[diff \[dq]zs-diff\[dq]]
    command = zs-diff --color
\f[R]
.fi
.PP
Then configure which files it should be used for
(\f[V].git/info/attributes\f[R]):
.IP
.nf
\f[C]
*.[ch]        diff=zs-diff
*.h.in        diff=zs-diff

*.[ch]pp      diff=zs-diff

Makefile      diff=zs-diff
Makefile.am   diff=zs-diff
Makefile.win  diff=zs-diff

*.lua         diff=zs-diff

*.bash        diff=zs-diff
*.sh          diff=zs-diff
\f[R]
.fi
.PP
This will make it work for \f[V]git diff\f[R] and \f[V]git show\f[R],
but \f[V]git log\f[R] and other subcommands don\[cq]t use custom diff
tools by default and need \f[V]--ext-diff\f[R] option to be specified
(can be done in an alias).
.SS Global Git integration
.PP
Same as above, but specify attributes in
\f[V]\[ti]/.config/git/attributes\f[R] and use one of the following
files for configuration:
.IP \[bu] 2
\f[V]\[ti]/.config/git/config\f[R]
.IP \[bu] 2
\f[V]\[ti]/.gitconfig\f[R]
.SS Explicit use in Git
.PP
Interactive (say \f[V]y\f[R] to view specific file):
.IP
.nf
\f[C]
git difftool -x zs-diff
\f[R]
.fi
.SH SEE ALSO
.PP
\f[B]zograscope\f[R](7) for common options and list of all tools there.
.SH AUTHORS
xaizek <xaizek@posteo.net>.