Edit Workflow & Daily Operations

Now that you know how to add files, use templates, and exclude things — it's time to learn the workflow you'll actually use every day. This lesson covers the core loop: edit a managed file, preview what changed, apply it, and sync with your remote repo.

The Daily Cycle

Your chezmoi workflow boils down to four steps, repeated whenever you tweak a dotfile:

Step 1: Edit the source state

The chezmoi edit command opens the source state version of a file in your editor. This is the correct way to make changes — you're editing the source of truth, not the target file directly.

chezmoi edit ~/.zshrc

This opens ~/.local/share/chezmoi/dot_zshrc (or the template version if one exists) in your $EDITOR. Make your changes, save, and quit.

Step 2: Preview with diff

Before applying anything, see exactly what will change in your home directory:

chezmoi diff

This shows a unified diff between the source state and the current target. If you're happy with the changes, proceed to apply. If something looks wrong, go back and edit again.

Step 3: Apply changes

Push the source state into your home directory:

chezmoi apply

This updates every managed file in your home directory to match the source state. It's idempotent — running it multiple times with no source changes does nothing.

Step 4: Commit and push

The source state is a git repo. Commit your changes and push to your remote:

chezmoi cd
git add .
git commit -m "chore: update zshrc aliases"
git push
exit

Or use the shorthand without entering the source directory:

chezmoi git -- add .
chezmoi git -- commit -m "chore: update zshrc aliases"
chezmoi git -- push

The edit --apply shortcut

If you want to skip the separate diff and apply steps, use --apply to apply immediately after your editor closes:

chezmoi edit --apply ~/.zshrc

This is a single command that opens the file, waits for you to save and quit, then applies the changes to the target. It's convenient for quick tweaks where you trust the edit. Skip it when you want to review the diff first.

Checking status

For a quick overview of what's changed without the full diff output, use status:

chezmoi status

This prints a concise list of files that differ between source and target, with single-character indicators:

 M home/dot_zshrc
 A home/dot_config/starship.toml

The indicators follow the same convention as git status: A for added, M for modified, D for deleted. It's the fastest way to see if your source and target are in sync.

Pulling changes on another machine

When you've pushed changes from one machine and want to pull them on another, use update:

chezmoi update

This is the equivalent of git pull + chezmoi apply in a single command. It pulls the latest changes from your remote repo into the source state, then applies them to your home directory.

Workflow comparison

There are three common ways to get a change into chezmoi. Here's when to use each:

Exercise: The full daily loop

Practice the complete cycle with a managed file:

Step 1: Edit

Open a managed file (use any file you've already added in previous lessons):

chezmoi edit ~/.gitconfig

Add a comment or an alias — something small and verifiable:

# Added via chezmoi edit workflow
[alias]
    st = status

Save and quit your editor.

Step 2: Diff

Preview the change:

chezmoi diff

You should see your new lines as additions in the diff output.

Step 3: Apply

chezmoi apply

Verify the change landed:

cat ~/.gitconfig | grep "st = status"

Step 4: Commit and push

chezmoi git -- add .
chezmoi git -- commit -m "chore: add git status alias"
chezmoi git -- push

Step 5: Confirm status is clean

chezmoi status

This should produce no output — source and target are in sync, and everything is committed.

Knowledge check

Next up

You now have the complete daily workflow: edit, diff, apply, commit. In Lesson 8: Run Scripts Deep Dive, you'll learn how to automate tasks that go beyond file management — installing packages, setting defaults, and running setup commands as part of chezmoi apply.