## page was renamed from UsingExtdiff
== Extdiff extension ==
'''This extension is currently being distributed along with Mercurial.'''

''Author: Vadim Gelfer''

=== Overview ===
The {{{extdiff}}} Mercurial extension allows you to use external programs
to compare revisions, or revision with working dir.
The external diff programs are called with a configurable set of options and two
non-option arguments: paths to directories containing snapshots of files to compare, or paths to the files themselves if only one file is modified.

=== Configuration ===
To enable this extension (in ~/.hgrc):

{{{
  [extensions]
  extdiff =
}}}

Then, the {{{extdiff}}} command should be available:

{{{
$ hg extdiff -h
hg extdiff [OPT]... [FILE]...

use external program to diff repository (or selected files)

    Show differences between revisions for the specified files, using
    an external program.  The default program used is diff, with
    default options "-Npru".
...
}}}

=== Use ===

You can run {{{extdiff}}} with default settings ({{{diff -Npru}}}):

{{{
$ hg extdiff
making snapshot of 1 files from rev dfe87137ed14
making snapshot of 1 files from working dir
diff -Npru crew.dfe87137ed14/mercurial/localrepo.py crew/mercurial/localrepo.py
--- crew.dfe87137ed14/mercurial/localrepo.py    2007-01-18 16:04:59.795697215 -0600
+++ crew/mercurial/localrepo.py 2007-01-18 16:04:59.805704181 -0600
@@ -990,10 +990,12 @@ class localrepository(repo.repository):
...
}}}

Or, use the -p option specify an external diff utility for comparing files:

{{{
$ hg extdiff -p kdiff3
}}}

Please note that the external diff utility of your choice must be able to compare directories.

You may use the {{{-o}}} option to specify options to the external diff utility:

{{{
$ hg extdiff -p diff -o -Npruw
}}}

You may also use {{{--rev/-r}}} and {{{-I/-X}}} options, as well as the list of file or
directory names like normal {{{hg diff}}} command.  The {{{extdiff}}} extension
makes snapshots of only needed files, so running the external diff program will actually be
pretty fast (at least faster than having to compare the entire tree).

=== Create Custom extdiff Commands ===
The {{{extdiff}}} extension also allows users to configure new diff commands in the hgrc files,
so you do not need to type {{{hg extdiff -p kdiff3}}} always.

{{{
  [extdiff]
  # add new command that runs GNU diff(1) in 'context diff' mode
  cmd.cdiff = gdiff
  opts.cdiff = -Nprc5

  # similarly, a command that runs GNU diff(1) in 'side-by-side' mode
  cmd.ydiff = gdiff
  opts.ydiff = -Npry

  # add new command called vdiff, runs kdiff3
  cmd.vdiff = kdiff3

  # add new command called meld, runs meld (no need to name twice)
  cmd.meld =

  # add new command called vimdiff, runs gvimdiff with DirDiff plugin
  #(see http://www.vim.org/scripts/script.php?script_id=102)
  # Non english user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
  # your .vimrc
  cmd.vimdiff = gvim
  opts.vimdiff = -f '+next' '+execute "DirDiff" fnameescape(argv(0)) fnameescape(argv(1))'

  # add new command called ediff, runs emacs diff
  cmd.ediff = sh
  opts.ediff = -c 'if [ -d $0 ]; then emacs --eval "(ediff-directories \"$0\" \"$1\" \"\")"; else emacs --eval "(ediff-files \"$0\" \"$1\")"; fi'


  # add new command to run ImageMagick compare (image diff).  Does not work on directories.

  # note:  could subsitute ImageMagick's "display" call instead of "gqview" for
  # greater portability, but gqview is nicer

  cmd.imdiff = sh  
  opts.imdiff = -c 'compare $0 $1 compared.png; gqview compared.png'
}}}

Each custom diff commands can have two parts: a {{{'cmd'}}} and an {{{'opts'}}}
part.  The {{{cmd.xxx}}} option defines the name of an executable program
that will be run, and {{{opts.xxx}}} defines a set of command-line options
which will be inserted to the command between the program name and
the files/directories to {{{diff}}} (i.e. the {{{cdiff}}} example above).

With the sample configuration above, you may now invoke the new commands:

{{{
$ hg vdiff    # call kdiff3
$ hg cdiff    # call gdiff with -Nprc5 option
$ hg meld     # call meld
$ hg ediff    # call emacs diff
$ hg imdiff   # call compare for an image diff  (don't invoke on directories)
}}}

=== FileMerge on Mac OS X ===

To use !FileMerge with extdiff on Mac OS X,
create the following shell
[[http://hints.macworld.com/article.php?story=20070220223441729|script]]
called {{{opendiff-w}}} somewhere in your $PATH
(remember to make the script executable: {{{chmod a+x opendiff-w}}}):
{{{
#!/bin/sh
# opendiff returns immediately, without waiting for FileMerge to exit.
# Piping the output makes opendiff wait for FileMerge.
opendiff "$@" | cat
}}}
Add to your {{{.hgrc}}}:
{{{
[extdiff]
cmd.opendiff = opendiff-w
}}}
You can now use !FileMerge for diffing from Mercurial:
{{{
$ hg opendiff
}}}

=== See also ===
 * WordDiff

----
CategoryBundledExtension