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