Changes

Changes #

Overview #

This document describes what’s new in chezmoi v2 for chezmoi v1 users.

If you’re not using a dotfile manager, then read why you should you use a dotfile manager and then install chezmoi and follow the quick-start guide.

If you’re already using a dotfile manager, but not chezmoi, then read about how chezmoi compares to other dotfile managers first and then install chezmoi, follow the quick-start guide, and read the how-to guide to quickly discover chezmoi’s functionality.

Version 2 #

chezmoi version 2 brings many new features and fixes a few corner-case bugs. Very few, if any, changes should be required to your source directory, templates, or config file.

New features in version 2 #

  • The new chezmoi status command shows you a concise list of differences, much like git status.
  • The chezmoi apply command prompts you if a file has been modified by something other than chezmoi since chezmoi last wrote it, keeping you in full control of your changes, wherever you make them.
  • The chezmoi init command will try to guess your dotfile repository if you give it a short argument. For example, chezmoi init username is the equivalent of chezmoi init https://github.com/username/dotfiles.git.
  • chezmoi includes a builtin git command which it will use if it cannot find git in your $PATH. This means that you don’t even have to install git to setup your dotfiles on a new machine.
  • chezmoi detects when your config file template has changed and prompts you to re-run chezmoi init if needed.
  • The new create_ attribute allows you to create a file with initial content, but not have it overwritten by chezmoi apply.
  • The new modify_ attribute allows you to modify an existing file with a script, so you can use chezmoi to manage parts, but not all, of a file.
  • The new script attributes before_ and after_ control when scripts are run relative to when your files are updated.
  • The new --exclude option allows you to control what types of target will be updated. For example chezmoi apply --exclude=scripts will cause chezmoi to apply everything except scripts and chezmoi init --apply --exclude=encrypted will exclude encrypted files.
  • The new --keep-going option causes chezmoi to keep going as far as possible rather than stopping at the first error it encounters.
  • The new --no-tty option stops chezmoi from opening a TTY to read input (including passwords) and instead reads them from stdin.
  • The new --source-path option allows you to specify targets by source path, which you can use in an on-save editor hook to automatically run chezmoi apply when you edit a dotfile in your source state.
  • The new gitHubKeys template function allows you to populate your ~/.ssh/authorized_keys from your public SSH keys on GitHub.
  • The promptBool function now also recognizes y, yes, on, n, no, and off as boolean values.
  • The chezmoi archive command now includes scripts in the generated archive, and can generate .zip files.
  • The new edit.command and edit.args configuration variables give you more control over the command invoked by chezmoi edit.
  • The chezmoi init command has a new --one-shot option which does a shallow clone of your dotfiles repo, runs chezmoi apply, and then removes your source and configuration directories. It’s the fastest way to set up your dotfiles on a ephemeral machine and then remove all traces of chezmoi.
  • Standard template variables are set on a best-effort basis. If errors are encountered, chezmoi leaves the variable unset rather than terminating with the error.
  • The new .chezmoi.version template variable contains the version of chezmoi. You can compare versions using version comparison functions.
  • The new .chezmoi.fqdnHostname template variables contains the fully-qualified domain name of the machine, if it can be determined.
  • You can now encrypt whole files with age.

Changes from version 1 #

chezmoi version 2 includes a few minor changes from version 1, mainly to enable the new functionality and for consistency:

  • chezmoi uses a different format to persist its state. Specifically, this means that all your run_once_ scripts will be run again the first time you run chezmoi apply.
  • chezmoi add, and many other commands, are now recursive by default.
  • chezmoi apply will warn if a file in the destination directory has been modified since chezmoi last wrote it. To force overwriting, pass the --force option.
  • chezmoi edit no longer supports the --prompt option.
  • The only diff format is now git. The diff.format configuration variable is ignored.
  • Diffs include the contents of scripts that would be run.
  • Mercurial support has been removed.
  • The chezmoi source command has been removed, use chezmoi git instead.
  • The sourceVCS configuration group has been renamed to git.
  • The order of files for a three-way merge passed to merge.command is now actual file, target state, source state.
  • The chezmoi keyring command has been moved to chezmoi secret keyring.
  • The genericSecret configuration group has been renamed to secret.
  • The chezmoi chattr command uses encrypted instead of encrypt as the attribute for encrypted files.
  • The gpg recipient is configured with the gpg.recipient configuration variable, gpgRecipient is no longer used.
  • The structure of data output by chezmoi dump has changed.
  • The .chezmoi.homedir template variable has been replaced with .chezmoi.homeDir. For compatibility, .chezmoi.homedir will continue to be supported until version 2.1.
  • The .chezmoi.fullHostname template variable has been removed, as it did not contain the full hostname. Use .chezmoi.fqdnHostname (UNIX only) instead.