Configuring External Tools

chezmoi integrates with external tools to provide a better user experience. This guide covers how to configure your preferred diff tool, merge tool, editor, and other utilities.

Editor Configuration

Setting Your Editor

By default, chezmoi uses the editor specified by the $VISUAL or $EDITOR environment variables, falling back to:

vi on Unix-like systems
notepad.exe on Windows

You can override this in your config file:

~/.config/chezmoi/chezmoi.toml

[edit]
    command = "vim"

Or set it with command-line arguments:

~/.config/chezmoi/chezmoi.toml

[edit]
    command = "code"
    args = ["--wait"]

VSCode / VSCodium

VSCode requires the --wait flag to keep chezmoi from continuing before you finish editing:

# Set via environment variable
export EDITOR="code --wait"

Or in your config:

~/.config/chezmoi/chezmoi.toml

[edit]
    command = "code"
    args = ["--wait"]

For VSCodium:

~/.config/chezmoi/chezmoi.toml

[edit]
    command = "codium"
    args = ["--wait"]

Vim

Vim requires the -f (foreground) flag:

export EDITOR="vim -f"

Or:

~/.config/chezmoi/chezmoi.toml

[edit]
    command = "vim"
    args = ["-f"]

Vim Plugins

Enhance your chezmoi workflow with these Vim plugins: chezmoi.vim - Syntax highlighting for chezmoi files including templates:

Plug 'alker0/chezmoi.vim'

vim-chezmoi - Automatically apply changes when saving with chezmoi edit:

Plug 'Lilja/vim-chezmoi'

chezmoi.nvim - Edit and auto-apply chezmoi-managed files:

use 'xvzc/chezmoi.nvim'

Auto-Apply on Save

You can also configure Vim to run chezmoi apply automatically. First, disable hardlinking:

~/.config/chezmoi/chezmoi.toml

[edit]
    hardlink = false

Then add an autocmd:

~/.vimrc

autocmd BufWritePost ~/.local/share/chezmoi/* ! chezmoi apply --source-path "%"

Neovim

~/.config/chezmoi/chezmoi.toml

[edit]
    command = "nvim"

Emacs

chezmoi.el provides convenience functions for Emacs (available on MELPA):

(use-package chezmoi)

Helix

Helix 25.01+ works out of the box:

~/.config/chezmoi/chezmoi.toml

[edit]
    command = "hx"

Diff Tool Configuration

Built-in Diff

By default, chezmoi uses a built-in diff with color output piped through your pager (usually less). If colors aren’t displaying correctly, set:

export LESS=-R

Or in your config:

~/.config/chezmoi/chezmoi.toml

pager = "less -R"

Custom Diff Tool

Use any diff tool by setting diff.command and diff.args. The templates variables .Destination and .Target contain the file paths:

~/.config/chezmoi/chezmoi.toml

[diff]
    command = "meld"
    args = ["--diff", "{{ .Destination }}", "{{ .Target }}"]

Note: If you generate your config from a template, escape the braces:

~/.local/share/chezmoi/.chezmoi.toml.tmpl

[diff]
    command = "meld"
    args = ["--diff", {{ printf "%q" "{{ .Destination }}" }}, {{ printf "%q" "{{ .Target }}" }}]

VSCode as Diff Tool

~/.config/chezmoi/chezmoi.toml

[diff]
    command = "code"
    args = ["--wait", "--diff", "{{ .Destination }}", "{{ .Target }}"]

For VSCodium:

~/.config/chezmoi/chezmoi.toml

[diff]
    command = "codium"
    args = ["--wait", "--diff", "{{ .Destination }}", "{{ .Target }}"]

Delta

Delta is a syntax-highlighting pager for git, diff, and grep output:

~/.config/chezmoi/chezmoi.toml

[diff]
    pager = "delta"

diff-so-fancy

diff-so-fancy makes diffs more readable:

~/.config/chezmoi/chezmoi.toml

[diff]
    pager = "diff-so-fancy"

Meld

Meld is a visual diff and merge tool:

~/.config/chezmoi/chezmoi.toml

[diff]
    command = "meld"
    args = ["--diff", "{{ .Destination }}", "{{ .Target }}"]

Disable the pager with a flag:

chezmoi diff --no-pager

Or in config:

~/.config/chezmoi/chezmoi.toml

[diff]
    pager = ""

Exclude Scripts from Diff

By default, chezmoi diff shows script contents. To exclude them:

~/.config/chezmoi/chezmoi.toml

[diff]
    exclude = ["scripts"]

Exclude Externals from Diff

chezmoi diff --exclude=externals

Or:

~/.config/chezmoi/chezmoi.toml

[diff]
    exclude = ["externals"]

Human-Friendly Binary Diffs

chezmoi supports “textconv” to transform binary files before diffing. This is useful for viewing diffs of binary formats.

macOS .plist Files

~/.config/chezmoi/chezmoi.toml

[[textconv]]
    pattern = "**/*.plist"
    command = "plutil"
    args = ["-convert", "xml1", "-o", "-", "-"]

PDF Files

~/.config/chezmoi/chezmoi.toml

[[textconv]]
    pattern = "**/*.pdf"
    command = "pdftotext"
    args = ["-", "-"]

Images (with exiftool)

~/.config/chezmoi/chezmoi.toml

[[textconv]]
    pattern = "**/*.{jpg,png}"
    command = "exiftool"
    args = ["-"]

Merge Tool Configuration

Default Merge Tool

By default, chezmoi uses vimdiff. Configure a custom merge tool with merge.command and merge.args: Templates variables available:

.Destination - file in destination state
.Source - file in source state
.Target - file in target state

Neovim

~/.config/chezmoi/chezmoi.toml

[merge]
    command = "nvim"
    args = ["-d", "{{ .Destination }}", "{{ .Source }}", "{{ .Target }}"]

VSCode

VSCode requires a wrapper script to provide all four files for 3-way merge:

~/.config/chezmoi/chezmoi.toml

[merge]
    command = "bash"
    args = [
        "-c",
        "cp {{ .Target | quote }} {{ printf \"%s.base\" .Target | quote }} && code --new-window --wait --merge {{ .Destination | quote }} {{ .Target | quote }} {{ printf \"%s.base\" .Target | quote }} {{ .Source | quote }}",
    ]

Beyond Compare

Beyond Compare is a commercial diff and merge tool:

~/.config/chezmoi/chezmoi.toml

[merge]
    command = "bcomp"
    args = ["{{ .Destination }}", "{{ .Source }}", "{{ .Target }}", "{{ .Source }}"]

Meld

~/.config/chezmoi/chezmoi.toml

[merge]
    command = "meld"
    args = ["{{ .Destination }}", "{{ .Source }}", "{{ .Target }}"]

KDiff3

~/.config/chezmoi/chezmoi.toml

[merge]
    command = "kdiff3"
    args = ["{{ .Destination }}", "{{ .Source }}", "{{ .Target }}", "-o", "{{ .Source }}"]

HTTP/SOCKS5 Proxy

Configure chezmoi to use a proxy for external sources and updates:

HTTP Proxy

Set environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

Or in config:

~/.config/chezmoi/chezmoi.toml

[http]
    proxy = "http://proxy.example.com:8080"

SOCKS5 Proxy

export ALL_PROXY=socks5://proxy.example.com:1080

Flatpak Integration

Tools installed via Flatpak require special invocation.

Wrapper Script Approach (Recommended)

Create a wrapper script with the same name as the command:

~/bin/keepassxc-cli

#!/bin/bash
flatpak run --command=keepassxc-cli org.keepassxc.KeePassXC -- "$@"

Make it executable:

chmod +x ~/bin/keepassxc-cli

Ensure ~/bin is in your $PATH.

Direct Configuration

For tools with .command and .args config options:

~/.config/chezmoi/chezmoi.toml

[diff]
    command = "flatpak"
    args = ["run", "com.vscodium.codium", "--wait", "--diff"]

Password Manager Integration

chezmoi integrates with many password managers. Each requires configuration:

1Password

~/.config/chezmoi/chezmoi.toml

[onepassword]
    command = "op"

Bitwarden

~/.config/chezmoi/chezmoi.toml

[bitwarden]
    command = "bw"

KeePassXC

~/.config/chezmoi/chezmoi.toml

[keepassxc]
    command = "keepassxc-cli"
    database = "/path/to/database.kdbx"

LastPass

~/.config/chezmoi/chezmoi.toml

[lastpass]
    command = "lpass"

Pass

~/.config/chezmoi/chezmoi.toml

[pass]
    command = "pass"

Shell Completion

chezmoi provides shell completion for bash, zsh, fish, and PowerShell.

Bash

# Add to ~/.bashrc
eval "$(chezmoi completion bash)"

Or install system-wide:

chezmoi completion bash | sudo tee /usr/share/bash-completion/completions/chezmoi

Zsh

# Add to ~/.zshrc
eval "$(chezmoi completion zsh)"

Or add to fpath:

chezmoi completion zsh > ~/.zsh/completions/_chezmoi

Fish

chezmoi completion fish | source

Or:

chezmoi completion fish > ~/.config/fish/completions/chezmoi.fish

PowerShell

Add to your PowerShell profile:

chezmoi completion powershell | Out-String | Invoke-Expression

Script Interpreters

Override the interpreter for run scripts:

~/.config/chezmoi/chezmoi.toml

[interpreters.ps1]
    command = "pwsh"
    args = ["-NoLogo"]

[interpreters.py]
    command = "python3"

Custom Umask

Control file permissions:

~/.config/chezmoi/chezmoi.toml

umask = 0o022

This prevents group-writeable files (useful for ~/.ssh/config).

Pinentry for GPG

Configure pinentry for GPG encryption:

~/.config/chezmoi/chezmoi.toml

[pinentry]
    command = "pinentry-mac"
    args = []

Warnings Configuration

Disable specific warnings:

~/.config/chezmoi/chezmoi.toml

[warnings]
    # Don't warn about config file template generating different output
    configFileTemplateHasChangedExternally = false

Git Configuration

Configure git behavior:

~/.config/chezmoi/chezmoi.toml

[git]
    autoCommit = true
    autoPush = true
    commitMessageTemplate = "{{ .commitMessage }}"

Use a different VCS:

~/.config/chezmoi/chezmoi.toml

[git]
    command = "git"

useBuiltinGit = false

Troubleshooting

Editor Returns Too Quickly

If you see:

chezmoi: warning: $EDITOR returned in less than 1s

Your editor is forking a background process. Add the appropriate flag:

VSCode: --wait
Vim: -f
Sublime: -w

Colors Not Showing in Diff

Set the LESS environment variable:

export LESS=-R

Flatpak Tools Not Found

Ensure your wrapper scripts are:

Executable (chmod +x)
In your $PATH
Named exactly like the command

Get Started

Core Concepts

User Guide

Encryption & Secrets

Password Managers

Advanced Usage

FAQ

​Editor Configuration

​Setting Your Editor

​VSCode / VSCodium

​Vim

​Vim Plugins

​Auto-Apply on Save

​Neovim

​Emacs

​Helix

​Diff Tool Configuration

​Built-in Diff

​Custom Diff Tool

​VSCode as Diff Tool

​Delta

​diff-so-fancy

​Meld

​Disable Pager

​Exclude Scripts from Diff

​Exclude Externals from Diff

​Human-Friendly Binary Diffs

​macOS .plist Files

​PDF Files

​Images (with exiftool)

​Merge Tool Configuration

​Default Merge Tool

​Neovim

​VSCode

​Beyond Compare

​Meld

​KDiff3

​HTTP/SOCKS5 Proxy

​HTTP Proxy

​SOCKS5 Proxy

​Flatpak Integration

​Wrapper Script Approach (Recommended)

​Direct Configuration

​Password Manager Integration

​1Password

​Bitwarden

​KeePassXC

​LastPass

​Pass

​Shell Completion

​Bash

​Zsh

​Fish

​PowerShell

​Script Interpreters

​Custom Umask

​Pinentry for GPG

​Warnings Configuration

​Git Configuration

​Troubleshooting

​Editor Returns Too Quickly

​Colors Not Showing in Diff

​Flatpak Tools Not Found

Build docs developers (and LLMs) love

Editor Configuration

Setting Your Editor

VSCode / VSCodium

Vim

Vim Plugins

Auto-Apply on Save

Neovim

Emacs

Helix

Diff Tool Configuration

Built-in Diff

Custom Diff Tool

VSCode as Diff Tool

Delta

diff-so-fancy

Meld

Disable Pager

Exclude Scripts from Diff

Exclude Externals from Diff

Human-Friendly Binary Diffs

macOS .plist Files

PDF Files

Images (with exiftool)

Merge Tool Configuration

Default Merge Tool

Neovim

VSCode

Beyond Compare

Meld

KDiff3

HTTP/SOCKS5 Proxy

HTTP Proxy

SOCKS5 Proxy

Flatpak Integration

Wrapper Script Approach (Recommended)

Direct Configuration

Password Manager Integration

1Password

Bitwarden

KeePassXC

LastPass

Pass

Shell Completion

Bash

Zsh

Fish

PowerShell

Script Interpreters

Custom Umask

Pinentry for GPG

Warnings Configuration

Git Configuration

Troubleshooting

Editor Returns Too Quickly

Colors Not Showing in Diff

Flatpak Tools Not Found