chezmoi requires Go 1.13 or later and Go modules enabled. Enable Go modules by
setting the environment variable
chezmoi is a standard Go project, using standard Go tooling, with a few extra tools. Install these extra tools with:
go build .
Run all tests:
go test ./...
go run .
Documentation and templates changes
The canonical documentation for chezmoi is in the
docs directory. The help
text (the output of
chezmoi command --help) and the website
(https://chezmoi.io/) are generated from this.
chezmoi embeds documentation and templates in its binary.
If you update any file in the
assets/templates/ directories, you
must also run
All changes are made via pull requests. In your pull request, please make sure that:
All existing tests pass.
There are appropriate additional tests that demonstrate that your PR works as intended.
The documentation is updated, if necessary. For new features you should add an entry in
docs/HOWTO.mdand a complete description in
The code is correctly formatted, according to
gofumports. You can ensure this by running
The commit messages match chezmoi’s convention, specifically that they begin with a capitalized verb in the imperative and give a short description of what the commit does. Detailed information or justification can be optionally included in the body of the commit message.
Commits are logically separate, with no merge or “fixup” commits.
The branch applies cleanly to
Releases are managed with
To create a new release, push a tag, e.g.:
git tag -a v0.1.0 -m "First release" git push origin v0.1.0
To build a test release, without publishing, run:
If you’re packaging chezmoi for an operating system or distribution:
Please set the version number, git commit, and build time in the binary. This greatly assists debugging when end users report problems or ask for help. You can do this by passing the following flags to the Go linker:
-X github.com/twpayne/chezmoi/cmd.VersionStr=$VERSION -X github.com/twpayne/chezmoi/cmd.Commit=$COMMIT -X github.com/twpayne/chezmoi/cmd.Date=$DATE
$VERSIONshould be the chezmoi version, e.g.
vprefix is optional and will be stripped, so you can pass the git tag in directly.
$COMMITshould be the full git commit hash at which chezmoi is built, e.g.
$DATEshould be the date of the build in RFC3339 format, e.g.
Please enable cgo, if possible. chezmoi can be built and run without cgo, but the
.chezmoi.grouptemplate variables may not be set correctly on some systems.
chezmoi includes a
docscommand which prints its documentation. By default, the docs are embedded in the binary. You can disable this behaviour, and have chezmoi read its docs from the filesystem by building with the
noembeddocsbuild tag and setting the directory where chezmoi can find them with the
-X github.com/twpayne/chezmoi/cmd.DocDir=$DOCDIRlinker flag. For example:
go build -tags noembeddocs -ldflags "-X github.com/twpayne/chezmoi/cmd.DocsDir=/usr/share/doc/chezmoi" .
To remove the
docscommand completely, use the
chezmoi includes an
upgradecommand which attempts to self-upgrade. You can remove this command completely by building chezmoi with the
chezmoi includes shell completions in the
completionsdirectory. Please include these in the package and install them in the shell-appropriate directory, if possible.
If the instructions for installing chezmoi in chezmoi’s install guide are absent or incorrect, please open an issue or submit a PR to correct them.
Updating the website
Before building the website, you must download the Hugo Book Theme by running:
git submodule update --init
Test the website locally by running:
( cd chezmoi.io && hugo serve )
and visit http://localhost:1313/.
To build the website in a temporary directory, run:
( cd chezmoi.io && make )
From here you can run
to show changes and
to push them. You can only push changes if you have write permissions to the chezmoi GitHub repo.