• English / Japanese

(C) 2000 Hisashi MORITA

Compares two text files by word, by character, or by line

TTY output

HTML output

Comparison by character

Digest mode (useful for viewing scattered changes within a long text)

DocDiff compares two text files and shows the difference. It can compare files word by word, character by character, or line by line. It has several output formats such as TTY, HTML, Manued, or user-defined markup.

It supports several encodings and end-of-line characters, including ASCII (and other single byte encodings such as ISO-8859-*), UTF-8, EUC-JP, Shift_JIS (Windows-31J), CR, LF, and CRLF.

$ docdiff [options] file1 file2

Type docdiff --help to show command line options.

docdiff [options] file1 file2
      --resolution=RESOLUTION
                       specify resolution (granularity)
                       line|word|char (default: word)
      --line           same as --resolution=line
      --word           same as --resolution=word
      --char           same as --resolution=char
      --encoding=ENCODING
                       specify character encoding
                       ASCII|EUC-JP|Shift_JIS|CP932|UTF-8|auto (default: auto)
                       (try ASCII for single byte encodings such as ISO-8859)
      --ascii          same as --encoding=ASCII
      --iso8859        same as --encoding=ASCII
      --iso8859x       same as --encoding=ASCII (deprecated)
      --eucjp          same as --encoding=EUC-JP
      --sjis           same as --encoding=Shift_JIS
      --cp932          same as --encoding=CP932
      --utf8           same as --encoding=UTF-8
      --eol=EOL        specify end-of-line character
                       CR|LF|CRLF|auto (default: auto)
      --cr             same as --eol=CR
      --lf             same as --eol=LF
      --crlf           same as --eol=CRLF
      --format=FORMAT  specify output format
                       tty|manued|html|wdiff|stat|user (default: tty)
                       (stat is deprecated)
                       (user tags can be defined in configuration file)
      --tty            same as --format=tty
      --manued         same as --format=manued
      --html           same as --format=html
      --wdiff          same as --format=wdiff
      --stat           same as --format=stat (not implemented) (deprecated)
  -L, --label LABEL    use label instead of file name
                       (not implemented; exists for compatibility with diff)
      --digest         digest output, do not show all
      --summary        same as --digest
      --display=DISPLAY
                       specify presentation type (effective only with digest)
                       inline|block|multi (default: inline)
                       (experimental feature) (multi is deprecated)
      --cache          use file cache (not implemented) (deprecated)
      --pager=PAGER    specify pager
                       (falls back to $DOCDIFF_PAGER, $PAGER, or none)
      --no-pager       do not use pager
      --config-file=FILE
                       specify configuration file to read
      --no-config-file do not read configuration files
      --verbose        run verbosely (not well-supported) (deprecated)
      --help           show help message
      --version        show version
      --license        show license (deprecated)
      --author         show author(s) (deprecated)
When invoked as worddiff or chardiff, resolution will be set accordingly.
Configuration files: /etc/docdiff/docdiff.conf, ~/.config/docdiff/docdiff.conf,
or ~/etc/docdiff/docdiff.conf (deprecated)

$ cat 01_en_ascii_lf.txt
Hello, my name is Watanabe.
I am just another Ruby porter.
$ cat 02_en_ascii_lf.txt
Hello, my name is matz.
It's me who has created Ruby.  I am a Ruby hacker.
$ docdiff --tty 01_en_ascii_lf.txt 02_en_ascii_lf.txt
Hello, my name is Watanabe.matz.
It's me who has created Ruby.  I am just another a Ruby porter.hacker.
$

• Runtime requirements:
  • Ruby (>= 3.0)
• Development requirements:
  • Test::Unit
  • Make (GNU Make)
  • Git
  • md2html (for generating documents)
  • Rake (optional)
  • sed, gzip, tar, etc.

Several operating environments have a packaged version of DocDiff available. If this applies to you, installing DocDiff via these packages is probably the easiest option.

Site-wide installation:

$ sudo apt update
$ sudo apt install docdiff

If you are familiar with the Ruby programming language, you may prefer to install DocDiff as a gem package.

User-wide installation from RubyGems.org:

$ gem install docdiff

User-wide installation from local build:

$ rake build
$ gem install pkg/docdiff-X.Y.Z.gem

(Note that you have to set the PATH environment variable correctly to run applications that are installed as gems. Environment management tools for Ruby such as rbenv may come in handy.)

If you really have to install DocDiff from source using Make, test it carefully before proceeding.

Test installation in tmp directory:

$ mkdir tmp
$ make install DESTDIR=tmp PREFIX=/local
$ tree tmp || la -lR tmp

User-wide installation example (not recommended though, as this may overwrite files and mess up your directory structure):

$ make install DESTDIR=~ PREFIX=/local

You can place configuration files at:

• /etc/docdiff/docdiff.conf (site-wide configuration)

• ~/.config/docdiff/docdiff.conf (user configuration) (see $XDG_CONFIG_HOME)

  (Warning: You are discouraged from using either ~/etc/docdiff/docdiff.conf or ~/.docdiff/docdiff.conf, both of which are deprecated though they are still effective for backward compatibility at the moment. Also note that multiple user configuration files cannot coexist at the same time.)

Notation is as follows (also refer to the file docdiff.conf.example included in the distribution archive):

# comment
key1 = value
key2 = value
...

Every value is treated as string, unless it seems like a number. In such case, value is treated as a number (usually an integer).

Sometimes DocDiff fails to auto-recognize encoding and/or end-of-line characters. You may get an error like this.

charstring.rb:47:in `extend': wrong argument type nil (expected Module) (TypeError)

In such a case, try explicitly specifying encoding and end-of-line character (e.g. docdiff --utf8 --crlf).

When comparing space-separated text (such as English or program source code), the word next to the end of line may be sometimes unnecessarily deleted and inserted. This is due to the limitation of DocDiff's word splitter. It splits strings into words like the following.

• Text 1:

  foo bar
  

  ("foo bar" => ["foo ", "bar"])

• Text 2:

  foo
  bar
  

  ("foo\nbar" => ["foo", "\n", "bar"])

• Comparison result:

  foo foo
  bar
  

  ("<del>foo </del><ins>foo</ins><ins>\n</ins>bar")

Foo is (unnecessarily) deleted and inserted at the same time.

I would like to fix this sometime, but it's not easy. If you split single space as single element (i.e. ["foo", " ", "bar"]), the word order of the comparison result will be less natural. Suggestions are welcome.

If you want to use DocDiff as an external diff program from VCSs, the following may work.

• Git:

  $ GIT_EXTERNAL_DIFF=~/bin/gitdocdiff.sh git diff
  

  ~/bin/gitdocdiff.sh:

  #!/bin/sh
  docdiff --ascii --lf --tty --digest $2 $5
  

• Subversion:

  $ svn diff --diff-cmd=docdiff --extensions "--ascii --lf --tty --digest"
  

(Sometimes just git diff --word-diff-regex="\w" suffices though.)

With zsh, you can use DocDiff or other utility to compare arbitrary sources. In the following example, we compare specific revision of foo.html in a repository with one on a website.

• Git:

  $ docdiff --tty --digest =(git show abc1234:foo.html) =(git show def4567:foo.html)
  

• Subversion:

  $ docdiff =(svn cat -r3 http://svn.example.org/repos/foo.html) =(curl --silent http://www.example.org/foo.html)
  

You may be able to compare document files other than plain text, if you use appropriate converters.

• Comparing the text in two PDF documents:

  $ docdiff =(pdftotext foo.pdf -) =(pdftotext bar.pdf -)
  

• Comparing the text in two HTML documents (without tags):

  $ docdiff =(w3m -dump -cols 10000 foo.html) =(w3m -dump -cols 10000 http://www.example.org/foo.html)
  

• Comparing the text in two Microsoft Word documents:

  $ docdiff =(wvWare foo.doc | w3m -T text/html -dump -cols 10000) =(wvWare bar.doc | w3m -T text/html -dump -cols 10000)
  

If you want to compare Latin-* (ISO-8859-*) text files, try using ASCII as their encoding. When ASCII is specified, DocDiff assumes single-byte characters.

• Comparing Latin-1 text:

  $ docdiff --encoding=ASCII latin-1-old.txt latin-1-new.txt
  

This software is distributed under so-called modified BSD style license (http://www.opensource.org/licenses/bsd-license.php) (without advertisement clause)). By contributing to this software, you agree that your contribution may be incorporated under the same license.

Copyright and condition of use of main portion of the source:

Copyright (C) Hisashi MORITA.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Neither the name of the University nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Diff library (lib/docdiff/diff.rb and lib/docdiff/diff/*) was originally a part of Ruby/CVS by Akira TANAKA. Ruby/CVS is licensed under modified BSD style license. See the following for detail.

• http://raa.ruby-lang.org/list.rhtml?name=ruby-cvs
• http://cvs.m17n.org/~akr/ruby-cvs/

• Hisashi MORITA (author)

• Akira TANAKA (diff library author)
• Shin'ichiro HARA (initial idea and algorithm suggestion)
• Masatoshi SEKI (patch)
• Akira YAMADA (patch, Debian package)
• Kenshi MUTO (testing, bug report, Debian package)
• Kazuhiro NISHIYAMA (bug report)
• Hiroshi OHKUBO (bug report)
• Shugo MAEDA (bug report)
• Kazuhiko (patch)
• Shintaro Kakutani (patches)
• Masayoshi Takahashi (patches)
• Masakazu Takahashi (patch)
• Hibariya (bug report)
• Hiroshi SHIBATA (patch)
• Tamotsu Takahashi (patches)
• MIKAMI Yoshiyuki (patch)

Excuse us this list is far from complete and fails to acknowledge many more who have helped us somehow. We really appreciate it.

• HTML/XHTML
• TTY (Graphic rendition using VT100 / ANSI escape sequences)
  • VT100
  • ANSI
• Manued (in Japanese) (Manuscript Editing Language: a proofreading method for text)

There are many other software that can compare text word by word and/or character by character.

• CLI:
  • wdiff (requires spaces between words)
  • cdif / sdif-tools
• GUI:
  • WinMerge (Windows)
• Editor extensions:
  • ediff (Emacs)
  • diff-detail (xyzzy)