Troubleshooting
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.
The output of chezmoi diff
is broken and does not contain color. What could be wrong?
By default, chezmoi's diff output includes ANSI color escape sequences (e.g.
ESC[37m
) and is piped into your pager (by default less
). chezmoi assumes
that your pager passes through the ANSI color escape sequences, as configured on
many systems, but not all. If your pager does not pass through ANSI color escape
sequences then you will see monochrome diff output with uninterpreted ANSI color
escape sequences.
This can typically by fixed by setting the environment variable
$ export LESS=-R
which instructs less
to display "raw" control characters via the -R
/
--RAW-CONTROL-CHARS
option.
You can also set the pager
configuration variable in your config file, for
example:
pager = "less -R"
If you have set a different pager (via the pager
configuration variable or
PAGER
environment variable) then you must ensure that it passes through raw
control characters. Alternatively, you can use the --color=false
option to
chezmoi to disable colors or the --no-pager
option to chezmoi to disable the
pager.
Why do I get a blank buffer when running chezmoi edit
?
What's happening here is that your editor is forking, detaching, and terminating the original process, which chezmoi cannot distinguish from the editor terminating normally.
You have two options:
1. Configure your editor command to remain in the foreground. For vim
, this
means passing the -f
flag, e.g. by setting the edit.flags
configuration
variable to ["-f"]
, or by setting the EDITOR
environment variable to
include the -f
flag, e.g. export EDITOR="mvim -f"
. For VSCode, pass the
--wait
flag.
2. Set the edit.hardlink
configuration variable to false
.
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 022
but some systems use 002
, 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 = 0o022
Note
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 reports chezmoi: user: lookup userid NNNNN: input/output error
This is likely because the chezmoi binary you are using was statically compiled with musl and the machine you are running on uses LDAP or NIS.
The immediate fix is to use a package built for your distribution (e.g a .deb
or .rpm
) which is linked against glibc and includes LDAP/NIS support instead
of the statically-compiled binary.
If the problem still persists, then please open an issue on GitHub.
chezmoi reports chezmoi: timeout
or chezmoi: timeout obtaining persistent state lock
chezmoi will report this when it is unable to lock its persistent state
(~/.config/chezmoi/chezmoistate.boltdb
), typically because another instance of
chezmoi is currently running and holding the lock.
This can happen, for example, if you have a run_
script that invokes
chezmoi
, or are running chezmoi in another window.
Under the hood, chezmoi uses bbolt which permits multiple simultaneous readers, but only one writer (with no readers).
Commands that take a write lock include add
, apply
, edit
, forget
,
import
, init
, state
, unmanage
, and update
. Commands that take a read
lock include diff
, status
, and verify
.
chezmoi reports chezmoi: fork/exec /tmp/XXXXXXXXXX.XX: permission denied
when executing a script
This error occurs when your temporary directory is mounted with the noexec
option.
As chezmoi scripts can be templates, encrypted, or both, chezmoi needs to write
the final script's contents to a file so that it can be executed by the
operating system. By default, chezmoi will use $TMPDIR
for this.
You can change the temporary directory into which chezmoi writes and executes
scripts with the scriptTempDir
configuration variable. For example, to use a
subdirectory of your home directory you can use:
scriptTempDir = "~/tmp"