Git - Difftastic Manual
Description: The manual for difftastic, the structural diff tool

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Git

Difftastic can be used an external diff command in git, allowing difftastic to be used with any git subcommand.

> Warning

> git v2.43.1 and earlier can crash when using an external diff and file permissions have changed.

> If you can’t upgrade git, use the `difftool` configuration described below.

## One-Off Usage

You can set the `diff.external` configuration option when running `git diff`, or set the `GIT_EXTERNAL_DIFF` environment variable.

View uncommitted changes with difftastic:

    $ git -c diff.external=difft diff

Other git commands also require the `--ext-diff` argument in order to use `diff.external`.

View changes from the most recent commit with difftastic:

    $ git -c diff.external=difft show --ext-diff

View changes from recent commits on the current branch with difftastic:

    $ git -c diff.external=difft log -p --ext-diff

## Regular Usage

If you like difftastic, we recommend that you configure git aliases so you can use difftastic more easily.

    [alias]
        # Difftastic aliases, so `git dlog -p` is `git log -p`
        # with difftastic and likewise for the other subcommands.
        dlog = -c diff.external=difft log --ext-diff
        dshow = -c diff.external=difft show --ext-diff
        ddiff = -c diff.external=difft diff

The author likes the following additional aliases to reduce typing:

    [alias]
        # `git log` with patches shown with difftastic.
        dl = -c diff.external=difft log -p --ext-diff

        # Show the most recent commit with difftastic.
        ds = -c diff.external=difft show --ext-diff

        # `git diff` with difftastic.
        dft = -c diff.external=difft diff

## Difftastic By Default

If you want to use difftastic as your default diff tool, add the following to your `~/.gitconfig`.

    [diff]
        external = difft

This changes `git diff` to use difftastic, and other commands now only require `--ext-diff`.

    $ git diff
    $ git show --ext-diff
    $ git log -p --ext-diff

If you’ve configured difftastic as the default diff tool, you can opt-out for an individual command with `--no-ext-diff`.

    $ git diff --no-ext-diff

## Difftool

Git also has a difftool feature which allows users to invoke CLI or GUI comparison tools.

For best results, we recommend using `-c diff.external=difft` as described above. Git passes more information to the external diff, including file permission changes and rename information, so difftastic can show more information.

To define a difftool named `difftastic`, add the following to your `~/.gitconfig`.

    [difftool "difftastic"]
        # See `man git-difftool` for a description of MERGED, LOCAL and REMOTE.
        cmd = difft "$MERGED" "$LOCAL" "abcdef1" "100644" "$REMOTE" "abcdef2" "100644"

You can now use difftastic as a difftool:

    $ git difftool -t difftastic

For the best results when using difftastic as a difftool, we recommend the following additional git configuration:

    [difftool]
        # Run the difftool immediately, don't ask 'are you sure' each time.
        prompt = false

    [pager]
        # Use a pager if the difftool output is larger than one screenful,
        # consistent with the behaviour of `git diff`.
        difftool = true

    [diff]
        # Set difftastic as the default difftool, so we don't need to specify
        # `-t difftastic` every time.
        tool = difftastic