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