# extdiff

Contents

- Description
- Commands
  - File content management

command to allow external programs to compare revisions

# Description

The extdiff Mercurial extension allows you to use external programs to compare revisions, or revision with working directory. 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.

If there is more than one file being compared and the "child" revision is the working directory, any modifications made in the external diff program will be copied back to the working directory from the temporary directory.

The extdiff extension also allows you to configure new diff commands, 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
    cdiff = gdiff -Nprc5
    ## or the old way:
    #cmd.cdiff = gdiff
    #opts.cdiff = -Nprc5

    # add new command called meld, runs meld (no need to name twice).  If
    # the meld executable is not available, the meld tool in [merge-tools]
    # will be used, if available
    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
    vimdiff = gvim -f "+next" \
              "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"

Tool arguments can include variables that are expanded at runtime:

    $parent1, $plabel1 - filename, descriptive label of first parent
    $child,   $clabel  - filename, descriptive label of child revision
    $parent2, $plabel2 - filename, descriptive label of second parent
    $root              - repository root
    $parent is an alias for $parent1.

The extdiff extension will look in your [diff-tools] and [merge-tools] sections for diff tool arguments, when none are specified in [extdiff].

    [extdiff]
    kdiff3 =

    [diff-tools]
    kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child

If a program has a graphical interface, it might be interesting to tell Mercurial about it. It will prevent the program from being mistakenly used in a terminal-only environment (such as an SSH terminal session), and will make `hg extdiff --per-file` open multiple file diffs at once instead of one by one (if you still want to open file diffs one by one, you can use the --confirm option).

Declaring that a tool has a graphical interface can be done with the `gui` flag next to where `diffargs` are specified:

    [diff-tools]
    kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
    kdiff3.gui = true

You can use -I/-X and 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).

# Commands

## File content management

### extdiff

use external program to diff repository (or selected files):

    hg extdiff [OPT]... [FILE]...

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

To select a different program, use the -p/--program option. The program will be passed the names of two directories to compare, unless the --per-file option is specified (see below). To pass additional options to the program, use -o/--option. These will be passed before the names of the directories or files to compare.

The --from, --to, and --change options work the same way they do for `hg diff`.

The --per-file option runs the external program repeatedly on each file to diff, instead of once on two directories. By default, this happens one by one, where the next file diff is open in the external program only once the previous external program (for the previous file diff) has exited. If the external program has a graphical interface, it can open all the file diffs at once instead of one by one. See `hg help -e extdiff` for information about how to tell Mercurial that a given program has a graphical interface.

The --confirm option will prompt the user before each invocation of the external program. It is ignored if --per-file isn't specified.

Options:

`-p, --program <CMD>`
| comparison program to run
`-o, --option <OPT[+]>`
| pass option to comparison program
`-r, --rev <REV[+]>`
| revision (DEPRECATED)
`--from <REV1>` | revision to diff from
`--to <REV2>` | revision to diff to
`-c, --change <REV>`
| change made by revision
`--per-file` | compare each file instead of revision snapshots
`--confirm` | prompt user before each external program invocation
`--patch` | compare patches for two revisions
`-I, --include <PATTERN[+]>`
| include names matching the given patterns
`-X, --exclude <PATTERN[+]>`
| exclude names matching the given patterns
`-S, --subrepos` | recurse into subrepositories

[+] marked option can be specified multiple times