diff --git a/CHANGELOG.md b/CHANGELOG.md index 00622088db..14ca03d411 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ endings with a file with unix line endings will not show spurious changes. +### Documentation + +Difftastic now has a man page, see the `difft.1` file. + ## 0.57 (released 1st April 2024) ### Parsing diff --git a/difft.1 b/difft.1 index 09234e7360..2a3a1e6eee 100644 --- a/difft.1 +++ b/difft.1 @@ -19,10 +19,144 @@ difftastic (difft) is a CLI diff tool that compares files based on their syntax, not line\-by\-line. Difftastic produces accurate diffs that are easier for humans to read. +.SS OPTIONS +.TP +\f[B]\-\-background\f[R] \f[I]BACKGROUND\f[R] +Set the background brightness. +Difftastic will prefer brighter colours on dark backgrounds. +.TP +\f[B]\-\-byte\-limit\f[R] \f[I]LIMIT\f[R] +Use a text diff if either input file exceeds this size. +.TP +\f[B]\-\-check\-only\f[R] +Report whether there are any changes, but don\[cq]t calculate them. +Much faster. +.TP +\f[B]\-\-color\f[R] \f[I]WHEN\f[R] +When to use color output. +.TP +\f[B]\-\-context\f[R] \f[I]LINES\f[R] +The number of contextual lines to show around changed lines. +.TP +\f[B]\-\-display\f[R] \f[I]MODE\f[R] +Display mode for showing results. +.RS +.PP +\f[I]side\-by\-side\f[R]: Display the before file and the after file in +two separate columns, with line numbers aligned according to unchanged +content. +If a change is exclusively additions or exclusively removals, use a +single column. +.PP +\f[I]side\-by\-side\-show\-both\f[R]: The same as +\f[I]side\-by\-side\f[R], but always uses two columns. +.PP +\f[I]inline\f[R]: A single column display, closer to traditional diff +display. +.PP +\f[I]json\f[R]: Output the results as a machine\-readable JSON array +with an element per file. +.RE +.TP +\f[B]\-\-exit\-code\f[R] +Set the exit code to 1 if there are syntactic changes in any files. +For files where there is no detected language (e.g.\ unsupported +language or binary files), sets the exit code if there are any byte +changes. +.TP +\f[B]\-\-graph\-limit\f[R] \f[I]LIMIT\f[R] +Use a text diff if the structural graph exceed this number of nodes in +memory. +.TP +\f[B]\-h, \-\-help\f[R] +Print help information. +.TP +\f[B]\-\-ignore\-comments\f[R] +Don\[cq]t consider comments when diffing. +.TP +\f[B]\-\-list\-languages\f[R] +Print the all the languages supported by difftastic, along with their +extensions. +.TP +\f[B]\-\-missing\-as\-empty\f[R] +Treat paths that don\[cq]t exist as equivalent to an empty file. +Only applies when diffing files, not directories. +.TP +\f[B]\-\-override\f[R] \f[I]GLOB:NAME\f[R] +Associate this glob pattern with this language, overriding normal +language detection. +For example: +.RS +.PP +$ difft \-\-override=\[cq]*.c:C++\[cq] old.c new.c +.PP +See \f[B]\-\-list\-languages\f[R] for the list of language names. +Language names are matched case insensitively. +Overrides may also specify the language \f[I]\[lq]text\[rq]\f[R] to +treat a file as plain text. +.PP +This argument may be given more than once. +For example: +.PP +$ difft \-\-override=`CustomFile:json' \-\-override=\[cq]*.c:text\[cq] +old.c new.c +.PP +To configure multiple overrides using environment variables, difftastic +also accepts \f[B]DFT_OVERRIDE_1\f[R] up to \f[B]DFT_OVERRIDE_9\f[R]. +.PP +$ export DFT_OVERRIDE=`CustomFile:json' $ export +DFT_OVERRIDE_1=`\f[I].c:text\[cq] $ export +DFT_OVERRIDE_2=\[cq]\f[R].js:javascript jsx' +.PP +When multiple overrides are specified, the first matching override wins. +.RE +.TP +\f[B]\-\-parse\-error\-limit\f[R] \f[I]LIMIT\f[R] +Use a text diff if the number of parse errors exceeds this value. +.TP +\f[B]\-\-skip\-unchanged\f[R] +Don\[cq]t display anything if a file is unchanged. +.TP +\f[B]\-\-sort\-paths\f[R] +When diffing a directory, output the results sorted by path. +This is slower. +.TP +\f[B]\-\-strip\-cr\f[R] +Remove any carriage return characters before diffing. +This can be helpful when dealing with files on Windows that contain +CRLF, i.e.\ ***. +.TP +\f[B]\-\-syntax\-highlight\f[R] \f[I]on/off\f[R] +Enable or disable syntax highlighting. +.TP +\f[B]\-\-tab\-width\f[R] \f[I]NUMSPACES\f[R] +Treat a tab as this many spaces. +.TP +\f[B]\-V, \-\-version\f[R] +Print version information. +.TP +\f[B]\-\-width\f[R] \f[I]COLUMNS\f[R] +Use this many columns when calculating line wrapping. +If not specified, difftastic will detect the terminal width. +.SS DEBUG OPTIONS +.TP +\f[B]\-\-dump\-syntax\f[R] \f[I]PATH\f[R] +Parse a single file with tree\-sitter and display the difftastic syntax +tree. +.TP +\f[B]\-\-dump\-ts\f[R] \f[I]PATH\f[R] +Parse a single file with tree\-sitter and display the tree\-sitter parse +tree. +.SH MANUAL +A full HTML manual is available at \c +.UR https://difftastic.wilfred.me.uk/introduction +.UE \c +\&. .SH BUGS -See GitHub Issues: \c +See GitHub issues at \c .UR https://github.com/Wilfred/difftastic/issues .UE \c +\&. .SH AUTHOR Wilfred Hughes \c .MT me@wilfred.me.uk diff --git a/difft.1.md b/difft.1.md index 0362c7eac2..fe037b8a5a 100644 --- a/difft.1.md +++ b/difft.1.md @@ -25,10 +25,150 @@ difftastic (difft) is a CLI diff tool that compares files based on their syntax, not line-by-line. Difftastic produces accurate diffs that are easier for humans to read. +OPTIONS +------- + +**\-\-background** _BACKGROUND_ + +: Set the background brightness. Difftastic will prefer brighter colours on dark + backgrounds. + +**\-\-byte-limit** _LIMIT_ + +: Use a text diff if either input file exceeds this size. + +**\-\-check-only** + +: Report whether there are any changes, but don't calculate them. Much faster. + +**\-\-color** _WHEN_ + +: When to use color output. + +**\-\-context** _LINES_ + +: The number of contextual lines to show around changed lines. + +**\-\-display** _MODE_ + +: Display mode for showing results. + + _side-by-side_: Display the before file and the after file in two separate columns, with + line numbers aligned according to unchanged content. If a change is exclusively + additions or exclusively removals, use a single column. + + _side-by-side-show-both_: The same as _side-by-side_, but always uses two columns. + + _inline_: A single column display, closer to traditional diff display. + + _json_: Output the results as a machine-readable JSON array with an element per file. + +**\-\-exit-code** + +: Set the exit code to 1 if there are syntactic changes in any files. For files where + there is no detected language (e.g. unsupported language or binary files), sets the exit + code if there are any byte changes. + +**\-\-graph-limit** _LIMIT_ + +: Use a text diff if the structural graph exceed this number of nodes in memory. + +**-h, \-\-help** + +: Print help information. + +**\-\-ignore-comments** + +: Don't consider comments when diffing. + +**\-\-list-languages** + +: Print the all the languages supported by difftastic, along with their extensions. + +**\-\-missing-as-empty** + +: Treat paths that don't exist as equivalent to an empty file. Only applies when diffing + files, not directories. + +**\-\-override** _GLOB:NAME_ + +: Associate this glob pattern with this language, overriding normal language detection. + For example: + + $ difft \-\-override='*.c:C++' old.c new.c + + See **\-\-list-languages** for the list of language names. Language names are matched case + insensitively. Overrides may also specify the language _"text"_ to treat a file as plain + text. + + This argument may be given more than once. For example: + + $ difft \-\-override='CustomFile:json' \-\-override='*.c:text' old.c new.c + + To configure multiple overrides using environment variables, difftastic also accepts + **DFT_OVERRIDE_1** up to **DFT_OVERRIDE_9**. + + $ export DFT_OVERRIDE='CustomFile:json' + $ export DFT_OVERRIDE_1='*.c:text' + $ export DFT_OVERRIDE_2='*.js:javascript jsx' + + When multiple overrides are specified, the first matching override wins. + +**\-\-parse-error-limit** _LIMIT_ + +: Use a text diff if the number of parse errors exceeds this value. + +**\-\-skip-unchanged** + +: Don't display anything if a file is unchanged. + +**\-\-sort-paths** + +: When diffing a directory, output the results sorted by path. This is slower. + +**\-\-strip-cr** + +: Remove any carriage return characters before diffing. This can be helpful when dealing + with files on Windows that contain CRLF, i.e. **\r\n**. + +**\-\-syntax-highlight** _on/off_ + +: Enable or disable syntax highlighting. + +**\-\-tab-width** _NUMSPACES_ + +: Treat a tab as this many spaces. + +**-V, \-\-version** + +: Print version information. + +**\-\-width** _COLUMNS_ + +: Use this many columns when calculating line wrapping. If not specified, difftastic will + detect the terminal width. + +DEBUG OPTIONS +------------- + +**\-\-dump-syntax** _PATH_ + +: Parse a single file with tree-sitter and display the difftastic syntax tree. + +**\-\-dump-ts** _PATH_ + +: Parse a single file with tree-sitter and display the tree-sitter parse + tree. + +MANUAL +====== + +A full HTML manual is available at . + BUGS ==== -See GitHub Issues: +See GitHub issues at . AUTHOR ======