How to Use configsync diff to Audit Config Drift

Config drift happens when your local configuration files diverge from your last pushed snapshot. You install a tool that appends to .zshrc. You tweak an editor setting and forget to push. A package manager updates a config file during an upgrade. Over time, these small changes accumulate and your machines fall out of sync.

The danger of drift is that it is invisible. Everything works fine on your current machine, so you do not notice the divergence. Then you switch machines, pull your config, and discover you are missing a week of changes that were never pushed.

The simplest form of configsync diff compares your local files against your last pushed snapshot:

This produces a unified colorized diff, similar to git diff. Lines removed from the snapshot appear in red, lines added locally appear in green. If nothing has changed, the command produces no output.

The full diff is useful for reviewing changes in detail, but sometimes you just want a summary. ConfigSync offers three output modes:

The --stat mode shows a summary like git diff --stat: each changed file with insertion and deletion counts. The --name-only mode lists only the paths of files that differ, useful for scripting or a quick glance.

When you have many tracked files, you can narrow the diff to specific modules:

Filtering is especially useful when you know exactly which area you have been modifying and do not want to sift through unrelated changes.

You can compare your local files against the last snapshot pushed from a different machine:

This answers the question: how does my current setup differ from what is on my other machine? It is useful when you are debugging a "works on my machine" issue and need to find the configuration difference between two environments.

Every push creates a numbered snapshot. You can diff against any snapshot in your history:

This is valuable when you know something changed but are not sure when. Diff against progressively older snapshots to find when a specific change was introduced.

Run configsync diff as part of your regular workflow in these situations:

Before pulling: Check what would change on your local machine. If the incoming changes conflict with local edits, you can back up your local files first.

Before pushing: Verify exactly what you are about to sync. Catch accidental changes or secrets that should not be pushed.

Weekly audit: Run configsync diff --stat once a week to catch drift before it accumulates. If files are drifting, push the changes or revert them.

Config drift is inevitable. The difference between a well-maintained environment and a broken one is whether you detect and address drift before it causes problems.