From: Michael Montalbo <mmontalbo@gmail.com>

The --word-diff documentation describes the output modes and word-regex mechanics but does not explain that word-diff operates within the hunks produced by the line-level diff rather than performing an independent word-stream comparison. This can surprise users when the line-level alignment causes word-level changes to appear even though the words in both files are identical.

Add a short note explaining the two-stage relationship.

Signed-off-by: Michael Montalbo <mmontalbo@gmail.com>
---
    doc: clarify that --word-diff operates on line-level hunks
    
    CC: Vincent Lefevre vincent@vinc17.net, Johannes Sixt j6t@kdbg.org

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2113%2Fmmontalbo%2Fmm%2Fdoc-word-diff-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2113/mmontalbo/mm/doc-word-diff-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2113

 Documentation/diff-options.adoc | 5 +++++
 1 file changed, 5 insertions(+)

From: Michael Montalbo <mmontalbo@gmail.com>

The --word-diff documentation describes the output modes and word-regex mechanics but does not explain that word-diff operates within the hunks produced by the line-level diff rather than performing an independent word-stream comparison. This can surprise users when the line-level alignment causes word-level changes to appear even though the words in both files are identical.

Add an implementation note explaining the two-stage relationship and that the output may change if Git acquires a different implementation in the future.

Signed-off-by: Michael Montalbo <mmontalbo@gmail.com>
---
    doc: clarify that --word-diff operates on line-level hunks
    
    CC: Vincent Lefevre vincent@vinc17.net, Johannes Sixt j6t@kdbg.org

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2113%2Fmmontalbo%2Fmm%2Fdoc-word-diff-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2113/mmontalbo/mm/doc-word-diff-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2113

Range-diff vs v1:

 1:  73f7b06c06 ! 1:  bc5ca5a147 doc: clarify that --word-diff operates on line-level hunks
     @@ Commit message
          changes to appear even though the words in both files are
          identical.
      
     -    Add a short note explaining the two-stage relationship.
     +    Add an implementation note explaining the two-stage relationship
     +    and that the output may change if Git acquires a different
     +    implementation in the future.
      
          Signed-off-by: Michael Montalbo <mmontalbo@gmail.com>
      
     @@ Documentation/diff-options.adoc: endif::git-diff[]
       Note that despite the name of the first mode, color is used to
       highlight the changed parts in all modes if enabled.
      ++
     -+Word diff works by finding word-level changes within each hunk of
     -+the line-level diff.  The line-level alignment determines which
     -+changed lines are compared to each other, which can affect the
     -+word-level output.
     ++The `--word-diff` option operates by taking the same line-by-line
     ++diff that is produced without the option and computing
     ++word-by-word changes within each hunk.  This may produce a
     ++larger diff than a dedicated word-diff tool would.  If Git
     ++acquires a different implementation in the future, the output
     ++may change.  Note that this is similar to the `--diff-algorithm`
     ++option, which may also change the output.
       
       `--word-diff-regex=<regex>`::
       	Use _<regex>_ to decide what a word is, instead of considering

 Documentation/diff-options.adoc | 8 ++++++++
 1 file changed, 8 insertions(+)