Skip to content

Latest commit

 

History

History
271 lines (196 loc) · 13.9 KB

FAQ.md

File metadata and controls

271 lines (196 loc) · 13.9 KB
Raw

chezmoi Frequently Asked Questions

How can I quickly check for problems with chezmoi on my machine?

Run:

chezmoi doctor

Anything ok is fine, anything warning is only a problem if you want to use the related feature, and anything error indicates a definite problem.

What are the consequences of "bare" modifications to the target files? If my .zshrc is managed by chezmoi and I edit ~/.zshrc without using chezmoi edit, what happens?

chezmoi will overwrite the file the next time you run chezmoi apply. Until you run chezmoi apply your modified ~/.zshrc will remain in place.

How can I tell what dotfiles in my home directory aren't managed by chezmoi? Is there an easy way to have chezmoi manage a subset of them?

chezmoi unmanaged will list everything not managed by chezmoi. You can add entire directories with chezmoi add -r.

How can I tell what dotfiles in my home directory are currently managed by chezmoi?

chezmoi managed will list everything managed by chezmoi.

If there's a mechanism in place for the above, is there also a way to tell chezmoi to ignore specific files or groups of files (e.g. by directory name or by glob)?

By default, chezmoi ignores everything that you haven't explicitly chezmoi add'ed. If have files in your source directory that you don't want added to your destination directory when you run chezmoi apply add their names to a file called .chezmoiignore in the source state.

Patterns are supported, and the you can change what's ignored from machine to machine. The full usage and syntax is described in the reference manual.

If the target already exists, but is "behind" the source, can chezmoi be configured to preserve the target version before replacing it with one derived from the source?

Yes. Run chezmoi add will update the source state with the target. To see diffs of what would change, without actually changing anything, use chezmoi diff.

Once I've made a change to the source directory, how do I commit it?

You have several options:

  • chezmoi cd opens a shell in the source directory, where you can run your usual version control commands, like git add and git commit.
  • chezmoi git and chezmoi hg run git and hg respectively in the source directory and pass extra arguments to the command. If you're passing any flags, you'll need to use -- to prevent chezmoi from consuming them, for example chezmoi git -- commit -m "Update dotfiles".
  • chezmoi source runs your configured version control system in your source directory. It works in the same way as the chezmoi git and chezmoi hg commands, but uses sourceVCS.command.

How do I only run a script when a file has changed?

A common example of this is that you're using Homebrew and have .Brewfile listing all the packages that you want installed and only want to run brew bundle --global when the contents of .Brewfile have changed.

chezmoi has two types of scripts: scripts that run every time, and scripts that only run when their contents change. chezmoi does not have a mechanism to run a script when an arbitrary file has changed, but there are some ways to achieve the desired behavior:

  1. Have the script create .Brewfile instead of chezmoi, e.g. in your run_once_install-packages:

    #!/bin/sh

cat > $HOME/.Brewfile <<EOF
brew "imagemagick"
brew "openssl"
EOF

brew bundle --global

  2. Don't use .Brewfile, and instead install the packages explicitly in run_once_install-packages:

    #!/bin/sh

brew install imagemagick || true
brew install openssl || true

    The || true is necessary because brew install exits with failure if the package is already installed.

  3. Use a script that runs every time (not just once) and rely on brew bundle --global being idempotent.

  4. Use a script that runs every time, records a checksum of .Brewfile in another file, and only runs brew bundle --global if the checksum has changed, and updates the recorded checksum after.

I've made changes to both the destination state and the source state that I want to keep. How can I keep them both?

chezmoi merge will open a merge tool to resolve differences between the source state, target state, and destination state. Copy the changes you want to keep in to the source state.

Why does chezmoi convert all my template variables to lowercase?

This is due to a feature in github.com/spf13/viper, the library that chezmoi uses to read its configuration file. For more information see this GitHub issue issue.

chezmoi makes ~/.ssh/config group writeable. How do I stop this?

By default, chezmoi uses your system's umask when creating files. On most systems the default umask is 0o22 but some systems use 0o02, which means that files and directories are group writeable by default.

You can override this for chezmoi by setting the umask configuration variable in your configuration file, for example:

umask = 0o22

Note that this will apply to all files and directories that chezmoi manages and will ensure that none of them are group writeable. It is not currently possible to control group write permissions for individual files or directories. Please open an issue on GitHub if you need this.

chezmoi's source file naming system cannot handle all possible filenames

This is correct. Certain target filenames, for example ~/dot_example, are incompatible with chezmoi's attributes used in the source state.

This is a deliberate, practical compromise. Target state metadata (private, encrypted, etc.) need to be stored for each file. Using the source state filename for this means that the contents of the file are untouched, there is no need to maintain the metadata in a separate file, is independent of the underlying filesystem and version control system, and unambiguously associates the metadata with a single file.

In practice, dotfile filenames are unlikely to conflict with chezmoi's attributes. If this does cause a genuine problem for you, please open an issue on GitHub.

gpg encryption fails. What could be wrong?

The gpg.recipient key should be ultimately trusted, otherwise encryption will fail because gpg will prompt for input, which chezmoi does not handle. You can check the trust level by running:

gpg --export-ownertrust

The trust level for the recipient's key should be 6. If it is not, you can change the trust level by running:

gpg --edit-key $recipient

Enter trust at the prompt and chose 5 = I trust ultimately.

I'm getting errors trying to build chezmoi from source

chezmoi requires Go version 1.13 or later and Go modules enabled. You can check the version of Go with:

go version

Enable Go modules by setting GO111MODULE=on when running go get:

GO111MODULE=on go get -u github.com/twpayne/chezmoi

For more details on building chezmoi, see the Contributing Guide.

What inspired chezmoi?

chezmoi was inspired by Puppet, but created because Puppet is a slow overkill for managing your personal configuration files. The focus of chezmoi will always be personal home directory management. If your needs grow beyond that, switch to a whole system configuration management tool.

Can I use chezmoi to manage files outside my home directory?

In practice, yes, you can, but this is strongly discouraged beyond using your system's package manager to install the packages you need.

chezmoi is designed to operate on your home directory, and is explicitly not a full system configuration management tool. That said, there are some ways to have chezmoi manage a few files outside your home directory.

chezmoi's scripts can execute arbitrary commands, so you can use a run_ script that is run every time you run chezmoi apply, to, for example:

  • Make the target file outside your home directory a symlink to a file managed by chezmoi in your home directory.
  • Copy a file managed by chezmoi inside your home directory to the target file.
  • Execute a template with chezmoi execute-template --output=filename template where filename is outside the target directory.

chezmoi executes all scripts as the user executing chezmoi, so you may need to add extra privilege elevation commands like sudo or PowerShell start -verb runas -wait to your script.

chezmoi, by default, operates on your home directory but this can be overridden with the --destination command line flag or by specifying destDir in your config file, and could even be the root directory (/ or C:\). This allows you, in theory, to use chezmoi to manage any file in your filesystem, but this usage is extremely strongly discouraged.

If your needs extend beyond modifying a handful of files outside your target system, then existing configuration management tools like Puppet, Chef, Ansible, and Salt are much better suited - and of course can be called from a chezmoi run_ script. Put your Puppet Manifests, Chef Recipes, Ansible Modules, and Salt Modules in a directory ignored by .chezmoiignore so they do not pollute your home directory.

Where does the name "chezmoi" come from?

"chezmoi" splits to "chez moi" and pronounced /ʃeɪ mwa/ (shay-moi) meaning "at my house" in French. It's seven letters long, which is an appropriate length for a command that is only run occasionally.

What other questions have been asked about chezmoi?

See the issues on GitHub.

Where do I ask a question that isn't answered here?

Please open an issue on GitHub.

I like chezmoi. How do I say thanks?

Thank you! chezmoi was written to scratch a personal itch, and I'm very happy that it's useful to you. Please give chezmoi a star on GitHub, and if you're happy to share your public dotfile repo then tag it with chezmoi. Contributions are very welcome and every bug report, support request, and feature request helps make chezmoi better. Thank you :)