Skip to content

PluginChezmoi

Jump to bottom
Fábio Luciano edited this page Mar 23, 2026 · 1 revision

Plugin: chezmoi

Display the number of pending differences detected by chezmoi in a safe, non-interactive mode. The plugin appears in the status bar only when differences are detected, and disappears automatically when no supported differences remain.

Screenshot

󰒔 3       # 3 differences detected - blue/info
󰒔 7       # 7 differences detected - yellow/warning
󰒔 25      # 25 differences detected - red/error
            # (hidden when no supported differences are found)

Requirements

Property Value
Platform macOS, Linux
Dependencies chezmoi
Content Type dynamic
Presence conditional (hidden when no supported differences are found)

Installation

# macOS (Homebrew)
brew install chezmoi

# Linux (script install)
curl -fsLS get.chezmoi.io | bash

# Linux (Debian/Ubuntu)
sudo snap install chezmoi --classic
# or
wget https://github.com/twpayne/chezmoi/releases/latest/download/chezmoi_linux_amd64.deb
sudo dpkg -i chezmoi_linux_amd64.deb

Make sure chezmoi is initialized before using this plugin:

chezmoi init

Quick Start

# Enable plugin
set -g @powerkit_plugins "chezmoi"

Configuration Example

# Enable plugin
set -g @powerkit_plugins "chezmoi"

# Icon
set -g @powerkit_plugin_chezmoi_icon "󰒔"

# Thresholds
set -g @powerkit_plugin_chezmoi_warning_threshold "5"
set -g @powerkit_plugin_chezmoi_critical_threshold "20"

# Exclude types that can trigger prompts or external side effects
set -g @powerkit_plugin_chezmoi_exclude_types "scripts,always,templates,encrypted,externals"

# Cache duration (seconds) - increase for large home directories
set -g @powerkit_plugin_chezmoi_cache_ttl "60"

Options Reference

Option Type Default Description
@powerkit_plugin_chezmoi_icon icon 󰒔 Plugin icon
@powerkit_plugin_chezmoi_warning_threshold number 5 Number of pending differences to trigger warning health
@powerkit_plugin_chezmoi_critical_threshold number 20 Number of pending differences to trigger error health
@powerkit_plugin_chezmoi_exclude_types string scripts,always,templates,encrypted,externals Comma-separated chezmoi entry types excluded from safe status
@powerkit_plugin_chezmoi_cache_ttl number 60 Cache duration in seconds
@powerkit_plugin_chezmoi_show_only_on_threshold bool false Only show when warning/error threshold is exceeded

States

State Condition Visibility
active chezmoi initialized, safe status found 1 or more pending differences Visible
inactive chezmoi not initialized, or no supported differences were found Hidden

Health Levels

Level Condition Color
info 1 to warning_threshold - 1 pending differences Blue
warning warning_threshold to critical_threshold - 1 pending differences Yellow
error critical_threshold or more pending differences Red

Context Values

Context Description
chezmoi_info Pending differences below warning threshold
chezmoi_warning Pending differences at or above warning threshold
chezmoi_error Pending differences at or above critical threshold

Display Format

The plugin shows just the number of pending differences detected by safe chezmoi status:

<count>

Examples

Display Meaning
3 3 differences detected (info)
7 7 differences detected (warning)
25 25 differences detected (error)
(hidden) No supported differences were found

How It Works

The plugin runs chezmoi status --no-pager --no-tty in safe mode and excludes entry types that commonly trigger prompts or side effects:

  • scripts
  • always
  • templates
  • encrypted
  • externals

Each non-empty output line is counted as one pending difference.

This gives you real chezmoi source/target drift detection for supported entry types, while avoiding template rendering and secret manager prompts in setups that use Bitwarden or other secret backends.

Important limitation: if a file is managed as a chezmoi template or encrypted entry, it is excluded by default in safe mode, so differences in those entries will not be counted unless you change @powerkit_plugin_chezmoi_exclude_types.

Status codes reported by chezmoi status:

Code Meaning
A Entry was added / will be created
D Entry was deleted / will be deleted
M Entry was modified / will be modified
R Script would run

Examples

Minimal Configuration

set -g @powerkit_plugins "chezmoi"

Combined with Git and Development Tools

set -g @powerkit_plugins "group(git,chezmoi),group(cpu,memory),datetime"

Custom Thresholds

set -g @powerkit_plugins "chezmoi"
# Show warning when 3 or more files are pending
set -g @powerkit_plugin_chezmoi_warning_threshold "3"
# Show error when 10 or more files are pending
set -g @powerkit_plugin_chezmoi_critical_threshold "10"

Slower Cache for Large Home Dirs

set -g @powerkit_plugins "chezmoi"
# Check status every 5 minutes instead of every minute
set -g @powerkit_plugin_chezmoi_cache_ttl "300"

Less Restrictive Mode

set -g @powerkit_plugins "chezmoi"
# Re-enable template checks if your setup does not prompt for secrets
set -g @powerkit_plugin_chezmoi_exclude_types "scripts,always,externals"

Troubleshooting

Plugin is always hidden

  1. Make sure chezmoi is initialized: chezmoi source-path should print a path without errors.
  2. Make sure safe status finds differences: chezmoi status --no-pager --no-tty --exclude "scripts,always,templates,encrypted,externals" should show output.
  3. If the missing files are templated or encrypted, reduce @powerkit_plugin_chezmoi_exclude_types and accept that prompts may come back.
  4. Check that chezmoi is in your $PATH.

Plugin is slow to update

If your chezmoi tree is large, increase cache_ttl:

set -g @powerkit_plugin_chezmoi_cache_ttl "300"

Force refresh

Clear the PowerKit cache to force an immediate re-check:

# Via keybinding (default: Ctrl+d if configured)
# Or manually:
rm -rf ~/.cache/tmux-powerkit/data/plugin_chezmoi_*
tmux source ~/.tmux.conf

Clone this wiki locally