From 149c040c45ffb7b14732869c69f01169c7ccd856 Mon Sep 17 00:00:00 2001 From: Wilfred Hughes Date: Mon, 28 Apr 2025 09:03:22 -0700 Subject: [PATCH] Prefer 'line-oriented diff' terminology 'Text diff' is confusing as the input files to difftastic's structural diffing logic is also text. Line-oriented more accurately captures the important aspect. --- CHANGELOG.md | 44 ++++++++-------- README.md | 4 +- difft.1 | 9 ++-- difft.1.md | 6 +-- homepage/index.html | 104 ++++++++++--------------------------- manual/src/glossary.md | 4 ++ manual/src/introduction.md | 12 ++--- src/diff/sliders.rs | 2 +- src/line_parser.rs | 5 +- src/options.rs | 6 +-- 10 files changed, 77 insertions(+), 119 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5cb4e04a3..3835520fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -291,7 +291,7 @@ types. ### Diffing Fixed an issue where adding or removing blank lines would be ignored -by the textual diffing logic. +by the line-oriented diffing logic. Directory diffing now respects `.gitignore` files. @@ -512,8 +512,8 @@ UTF-16. Many files can be decoded as UTF-16 without decoding errors but produce nonsense results, so this heuristic seems to work better. Fixed an issue where difftastic would discard the last newline in a -file before diffing. This was most noticeable when doing textual diffs -and the last line had changed. +file before diffing. This was most noticeable when doing line-oriented +diffs and the last line had changed. ### Display @@ -543,12 +543,12 @@ Added support for Newick and Racket. ### Diffing -Difftastic now uses a textual diff on files that have any parse +Difftastic now uses a line-oriented diff on files that have any parse errors. The parse error limit defaults to 0, but it is configurable with `DFT_PARSE_ERROR_LIMIT` or `--parse-error-limit`. -Textual diffing now respects `--check-only`, consistent with syntactic -diffing. +Line-oriented diffing now respects `--check-only`, consistent with +structural diffing. ### Display @@ -603,13 +603,13 @@ Improved CSS parsing and HTML sublanguage parsing. Added an `--ignore-comments` option. -Improved textual diffing performance, particularly when the two files -have few lines in common. +Improved line-oriented diffing performance, particularly when the two +files have few lines in common. ### Display -Fixed an issue with unwanted underlines with textual diffing when -DFT_BYTE_LIMIT is reached. +Fixed an issue with unwanted underlines with line-oriented diffing +when DFT_BYTE_LIMIT is reached. Fixed a crash in inline display when the file ends with whitespace. @@ -640,8 +640,8 @@ constituents. `--display=inline` now respects `--tab-width`. -Fixed an issue with unwanted underlines with textual diffing when -DFT_GRAPH_LIMIT is reached. +Fixed an issue with unwanted underlines with line-oriented diffing +when DFT_GRAPH_LIMIT is reached. Improved syntax highlighting for predefined types in TypeScript. @@ -1241,9 +1241,9 @@ Fixed a crash when line wrapping produced an entirely blank line. ### Diffing -Improved word diffing (in both comments and textual diffs) when source -contains Unicode characters. Word splitting now uses the Unicode -alphabetic property. +Improved word diffing (in both comments and line-oriented diffs) when +the source contains Unicode characters. Word splitting now uses the +Unicode alphabetic property. Fixed a crash when comments contained multibyte Unicode characters. @@ -1308,12 +1308,12 @@ Improved minor display issues when one file is longer than the other. If given binary files, difftastic will now report if the file contents are identical. -Difftastic will now use a text diff for large files, rather than -trying to use more memory than is available. This threshold is +Difftastic will now use a line-oriented diff for large files, rather +than trying to use more memory than is available. This threshold is configurable with `--node-limit` and `DFT_NODE_LIMIT`. -Fixed a bug in the text diff logic where lines weren't shown if they -did not have both word additions and word removals. +Fixed a bug in the line-oriented diff logic where lines weren't shown +if they did not have both word additions and word removals. ### Command Line Interface @@ -1433,9 +1433,9 @@ Fixed a parsing performance regression introduced in 0.13. ### Diffing -Text diffing now has a standalone implementation rather than reusing -structural diff logic. This is significantly faster and highlighted -better. +Line-oriented diffing now has a standalone implementation rather than +reusing structural diff logic. This is significantly faster and +highlighted better. Improved performance when diffing two identical files. This is common when diffing directories. diff --git a/README.md b/README.md index 7666c503f..e2ef8369f 100644 --- a/README.md +++ b/README.md @@ -99,8 +99,8 @@ favourite tool, and I will link it in the README! ### What about parse errors? -By default, difftastic falls back to a line-oriented text diff -whenever parse errors are encountered. +By default, difftastic falls back to a line-oriented diff whenever +parse errors are encountered. This is a conservative choice to ensure that difftastic never claims two syntactically different files are the same. diff --git a/difft.1 b/difft.1 index cad3f88b5..b092f56c5 100644 --- a/difft.1 +++ b/difft.1 @@ -26,7 +26,7 @@ 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. +Use a line\-oriented 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. @@ -65,8 +65,8 @@ 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. +Use a line\-oriented diff if the structural graph exceed this number of +nodes in memory. .TP \f[B]\-h, \-\-help\f[R] Print help information. @@ -108,7 +108,8 @@ 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. +Use a line\-oriented 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. diff --git a/difft.1.md b/difft.1.md index 366321698..a993cc442 100644 --- a/difft.1.md +++ b/difft.1.md @@ -35,7 +35,7 @@ OPTIONS **\-\-byte-limit** _LIMIT_ -: Use a text diff if either input file exceeds this size. +: Use a line-oriented diff if either input file exceeds this size. **\-\-check-only** @@ -71,7 +71,7 @@ OPTIONS **\-\-graph-limit** _LIMIT_ -: Use a text diff if the structural graph exceed this number of nodes in memory. +: Use a line-oriented diff if the structural graph exceed this number of nodes in memory. **-h, \-\-help** @@ -111,7 +111,7 @@ OPTIONS **\-\-parse-error-limit** _LIMIT_ -: Use a text diff if the number of parse errors exceeds this value. +: Use a line-oriented diff if the number of parse errors exceeds this value. **\-\-skip-unchanged** diff --git a/homepage/index.html b/homepage/index.html index cc6bc29c4..3b9b0c08f 100644 --- a/homepage/index.html +++ b/homepage/index.html @@ -1,4 +1,4 @@ - + @@ -94,8 +94,8 @@ Difftastic parses your code with tree-sitter. Unlike a line-oriented text diff, difftastic understands that - the inner expression hasn't changed here. + >. Unlike a line-oriented diff, difftastic understands that the + inner expression hasn't changed here.

@@ -189,9 +189,7 @@ type="image/svg+xml" > -

- C++ -

+

C++

@@ -203,9 +201,7 @@ type="image/svg+xml" >
-

- C# -

+

C#

@@ -219,9 +215,7 @@ >
-

- Clojure -

+

Clojure

@@ -235,9 +229,7 @@ >
-

- Dart -

+

Dart

@@ -251,9 +243,7 @@ >
-

- Erlang -

+

Erlang

@@ -267,9 +257,7 @@ >
-

- Go -

+

Go

@@ -283,9 +271,7 @@ >
-

- Haskell -

+

Haskell

@@ -299,9 +285,7 @@ >
-

- Java -

+

Java

@@ -315,9 +299,7 @@ >
-

- JavaScript -

+

JavaScript

@@ -331,9 +313,7 @@ >
-

- Kotlin -

+

Kotlin

@@ -347,9 +327,7 @@ >
-

- Lisp -

+

Lisp

@@ -363,9 +341,7 @@ >
-

- Lua -

+

Lua

@@ -379,9 +355,7 @@ >
-

- OCaml -

+

OCaml

@@ -395,9 +369,7 @@ >
-

- PHP -

+

PHP

@@ -410,9 +382,7 @@ type="image/svg+xml" >
-

- Python -

+

Python

@@ -426,9 +396,7 @@ >
-

- R -

+

R

@@ -442,9 +410,7 @@ >
-

- Ruby -

+

Ruby

@@ -458,9 +424,7 @@ >
-

- Rust -

+

Rust

@@ -474,9 +438,7 @@ >
-

- Scala -

+

Scala

@@ -490,9 +452,7 @@ >
-

- TypeScript -

+

TypeScript

@@ -528,9 +488,7 @@ >
-

- HCL -

+

HCL

@@ -544,9 +502,7 @@ >
-

- HTML -

+

HTML

@@ -560,9 +516,7 @@ >
-

- JSON -

+

JSON

@@ -576,9 +530,7 @@ >
-

- YAML -

+

YAML

@@ -646,7 +598,7 @@ theme: "tango", cols: 133, rows: 24, - } + }, ); diff --git a/manual/src/glossary.md b/manual/src/glossary.md index 943bbbf18..31007ca47 100644 --- a/manual/src/glossary.md +++ b/manual/src/glossary.md @@ -16,6 +16,10 @@ the hunk. **LHS**: Left-hand side. Difftastic compares two items, and LHS refers to the first item. See also 'RHS'. +**Line-oriented**: A traditional diff that compares which lines have +been added or removed, unlike difftastic. For example, GNU diff or the +diffs displayed on GitHub. + **List**: A list is an item in difftastic's syntax tree structure that has an open delimiter, children, and a close delimiter. It represents things like expressions and function definitions. See also 'atom'. diff --git a/manual/src/introduction.md b/manual/src/introduction.md index 7e2c40e3e..8783d45b5 100644 --- a/manual/src/introduction.md +++ b/manual/src/introduction.md @@ -52,15 +52,15 @@ A line-oriented diff does a much worse job here. -Some textual diff tools also highlight word changes (e.g. GitHub or -git's `--word-diff`). They still don't understand the code +Some line-oriented diff tools also highlight word changes (e.g. GitHub +or git's `--word-diff`). They still don't understand the code though. Difftastic will always find matched delimiters: you can see the closing `)` from `or_else` has been highlighted. -## Fallback Textual Diffing +## Fallback Line-Oriented Diffing If input files are not in a format that difftastic understands, it -uses a conventional line-oriented text diff with word highlighting. +uses a conventional line-oriented diff with word highlighting. -Difftastic will also use textual diffing when given extremely large -inputs. +Difftastic will also use line-oriented diffing when given extremely +large inputs. diff --git a/src/diff/sliders.rs b/src/diff/sliders.rs index 2d271fffc..38cc87739 100644 --- a/src/diff/sliders.rs +++ b/src/diff/sliders.rs @@ -29,7 +29,7 @@ //! can change which item is marked as novel (e.g. either `B` in the //! example above) whilst still showing a valid, minimal diff. //! -//! A similar problem exists with line-based textual diffs, see +//! A similar problem exists with line-oriented diffs, see //! [diff-slider-tools](https://github.com/mhagger/diff-slider-tools) //! for a thorough discussion. diff --git a/src/line_parser.rs b/src/line_parser.rs index ea6308334..a3bf03054 100644 --- a/src/line_parser.rs +++ b/src/line_parser.rs @@ -107,8 +107,9 @@ fn line_len_in_bytes(line: &str) -> usize { } } -/// Build a vec of MatchedPos, performing a textual diff. Match up -/// unchanged lines, and match up unchanged words within novel lines. +/// Build a vec of MatchedPos, performing a line-oriented diff. Match +/// up unchanged lines, and match up unchanged words within novel +/// lines. /// /// The resulting vec only has novel items from the LHS. Callers /// should do `change_positions(rhs_src, lhs_src)` to obtain diff --git a/src/options.rs b/src/options.rs index a61cc4032..a5b29da40 100644 --- a/src/options.rs +++ b/src/options.rs @@ -280,7 +280,7 @@ When multiple overrides are specified, the first matching override wins.")) Arg::new("byte-limit").long("byte-limit") .value_name("LIMIT") .action(ArgAction::Set) - .help("Use a text diff if either input file exceeds this size.") + .help("Use a line-oriented diff if either input file exceeds this size.") .default_value(format!("{}", DEFAULT_BYTE_LIMIT)) .env("DFT_BYTE_LIMIT") .value_parser(clap::value_parser!(usize)) @@ -289,7 +289,7 @@ When multiple overrides are specified, the first matching override wins.")) .arg( Arg::new("graph-limit").long("graph-limit") .value_name("LIMIT") - .help("Use a text diff if the internal graph exceeds this number of vertices. This limit controls the worst case runtime and memory usage for difftastic. + .help("Use a line-oriented diff if the internal graph exceeds this number of vertices. This limit controls the worst case runtime and memory usage for difftastic. Higher values will allow difftastic to perform a structural diff in more cases. Higher values will also increase the time before difftastic gives up on structural diffing, and increase peak memory usage.") .default_value(format!("{}", DEFAULT_GRAPH_LIMIT)) @@ -302,7 +302,7 @@ Higher values will allow difftastic to perform a structural diff in more cases. Arg::new("parse-error-limit").long("parse-error-limit") .value_name("LIMIT") .action(ArgAction::Set) - .help("Use a text diff if the number of parse errors exceeds this value.") + .help("Use a line-oriented diff if the number of parse errors exceeds this value.") .default_value(format!("{}", DEFAULT_PARSE_ERROR_LIMIT)) .env("DFT_PARSE_ERROR_LIMIT") .value_parser(clap::value_parser!(usize))