From 6c952eb02fea4bc10f65bc1e8df86a53c340ba7a Mon Sep 17 00:00:00 2001 From: Tom Payne Date: Mon, 24 May 2021 20:04:31 +0200 Subject: [PATCH] Format code blocks in documentation --- README.md | 8 +- chezmoi.io/content/_index.md | 8 +- docs/ARCHITECTURE.md | 8 +- docs/CONTRIBUTING.md | 59 +++- docs/FAQ.md | 20 +- docs/HOWTO.md | 622 +++++++++++++++++++++++------------ docs/INSTALL.md | 32 +- docs/QUICKSTART.md | 60 +++- docs/REFERENCE.md | 544 ++++++++++++++++++------------ docs/TEMPLATING.md | 198 +++++++---- 10 files changed, 1014 insertions(+), 545 deletions(-) diff --git a/README.md b/README.md index fc81e32e1b2..7289f4ae397 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,15 @@ Manage your dotfiles across multiple diverse machines, securely. With chezmoi, you can install chezmoi and your dotfiles on a new, empty machine with a single command: - sh -c "$(curl -fsLS git.io/chezmoi)" -- init --apply +```console +$ sh -c "$(curl -fsLS git.io/chezmoi)" -- init --apply +``` Updating your dotfiles on any machine is a single command: - chezmoi update +```console +$ chezmoi update +``` * [How do I start with chezmoi now?](#how-do-i-start-with-chezmoi-now) * [What does chezmoi do and why should I use it?](#what-does-chezmoi-do-and-why-should-i-use-it) diff --git a/chezmoi.io/content/_index.md b/chezmoi.io/content/_index.md index 564142673b5..da910864bbf 100644 --- a/chezmoi.io/content/_index.md +++ b/chezmoi.io/content/_index.md @@ -10,11 +10,15 @@ Manage your dotfiles across multiple diverse machines, securely. With chezmoi, you can install chezmoi and your dotfiles on a new, empty machine with a single command: - sh -c "$(curl -fsLS git.io/chezmoi)" -- init --apply +```console +$ sh -c "$(curl -fsLS git.io/chezmoi)" -- init --apply +``` Updating your dotfiles on any machine is a single command: - chezmoi update +```console +$ chezmoi update +``` ## How do I start with chezmoi now? diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index f7f9eca552d..bfbbc48f182 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -20,7 +20,9 @@ interested in contributing to chezmoi. You can generate Go documentation for chezmoi's source code with `go doc`, for example: - go doc -all -u github.com/twpayne/chezmoi/v2/internal/chezmoi +```console +$ go doc -all -u github.com/twpayne/chezmoi/v2/internal/chezmoi +``` You can also [browse chezmoi's generated documentation online](https://pkg.go.dev/github.com/twpayne/chezmoi/v2) but this only includes @@ -170,7 +172,9 @@ framework. End-to-end tests use with the test scripts themselves in `testdata/scripts`. You can run individual end-to-end tests with - go test . -run=TestScript/ +```console +$ go test . -run=TestScript/ +``` where `` is the basename of file in `testdata/scripts`. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9000552df5f..9af8f934d43 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -22,26 +22,36 @@ chezmoi requires Go 1.16 or later. chezmoi is a standard Go project, using standard Go tooling, with a few extra tools. Ensure that these extra tools are installed with: - make ensure-tools +```console +$ make ensure-tools +``` Build chezmoi: - go build . +```console +$ go build . +``` Run all tests: - go test ./... +```console +$ go test ./... +``` Run chezmoi: - go run . +```console +$ go run . +``` ## Generated code chezmoi generates shell completions, the install script, and the website from a single source of truth. You must run - make generate +```console +$ make generate +``` if you change includes any of the following: @@ -104,12 +114,15 @@ Releases are managed with [`goreleaser`](https://goreleaser.com/). To build a test release, without publishing, (Linux only) run: - make test-release - +```console +$ make test-release +``` Publish a new release by creating and pushing a tag, e.g.: - git tag v1.2.3 - git push --tags +```console +$ git tag v1.2.3 +$ git push --tags +``` This triggers a [GitHub Action](https://github.com/twpayne/chezmoi/actions) that builds and publishes archives, packages, and snaps, and creates a new [GitHub @@ -120,11 +133,15 @@ Publishing [Snaps](https://snapcraft.io/) requires a `SNAPCRAFT_LOGIN` secret](https://github.com/twpayne/chezmoi/settings/secrets/actions). Snapcraft logins periodically expire. Create a new snapcraft login by running: - snapcraft export-login --snaps=chezmoi --channels=stable --acls=package_upload - +```console +$ snapcraft export-login --snaps=chezmoi --channels=stable --acls=package_upload - +``` [brew](https://brew.sh/) formula must be updated manually with the command: - brew bump-formula-pr --tag=v1.2.3 chezmoi +```console +$ brew bump-formula-pr --tag=v1.2.3 chezmoi +``` ## Packaging @@ -181,25 +198,35 @@ branch](https://github.com/twpayne/chezmoi/tree/gh-pages) to GitHub. Before building the website, you must download the [Hugo Book Theme](https://github.com/alex-shpak/hugo-book) by running: - git submodule update --init +```console +$ git submodule update --init +``` Test the website locally by running: - ( cd chezmoi.io && hugo serve ) +```console +$ ( cd chezmoi.io && hugo serve ) +``` and visit http://localhost:1313/. To build the website in a temporary directory, run: - ( cd chezmoi.io && make ) +```console +$ ( cd chezmoi.io && make ) +``` From here you can run - git show +```console +$ git show +``` to show changes and - git push +```console +$ git push +``` to push them. You can only push changes if you have write permissions to the chezmoi GitHub repo. diff --git a/docs/FAQ.md b/docs/FAQ.md index 6457d9f1667..ed5f4bf747a 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -30,7 +30,9 @@ Run: - chezmoi doctor +```console +$ 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. @@ -104,7 +106,9 @@ 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 +```toml +umask = 0o022 +``` 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 @@ -266,12 +270,16 @@ 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 +```console +$ 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 +```console +$ gpg --edit-key $recipient +``` Enter `trust` at the prompt and chose `5 = I trust ultimately`. @@ -308,7 +316,9 @@ lock include `diff`, `status`, and `verify`. chezmoi requires Go version 1.16 or later. You can check the version of Go with: - go version +```console +$ go version +``` For more details on building chezmoi, see the [Contributing Guide]([CONTRIBUTING.md](https://github.com/twpayne/chezmoi/blob/master/docs/CONTRIBUTING.md)). diff --git a/docs/HOWTO.md b/docs/HOWTO.md index d29b14ae78a..ba27a655069 100644 --- a/docs/HOWTO.md +++ b/docs/HOWTO.md @@ -67,32 +67,44 @@ of your choice (e.g. [Bitbucket](https://bitbucket.org), their repo `dotfiles`) and push the repo in the source directory here. For example: - chezmoi cd - git remote add origin https://github.com/username/dotfiles.git - git push -u origin main - exit +```console +$ chezmoi cd +$ git remote add origin https://github.com/username/dotfiles.git +$ git push -u origin main +$ exit +``` On another machine you can checkout this repo: - chezmoi init https://github.com/username/dotfiles.git +```console +$ chezmoi init https://github.com/username/dotfiles.git +``` You can then see what would be changed: - chezmoi diff +```console +$ chezmoi diff +``` If you're happy with the changes then apply them: - chezmoi apply +```console +$ chezmoi apply +``` The above commands can be combined into a single init, checkout, and apply: - chezmoi init --apply --verbose https://github.com/username/dotfiles.git +```console +$ chezmoi init --apply --verbose https://github.com/username/dotfiles.git +``` ### Pull the latest changes from your repo and apply them You can pull the changes from your repo and apply them in a single command: - chezmoi update +```console +$ chezmoi update +``` This runs `git pull --rebase` in your source directory and then `chezmoi apply`. @@ -100,7 +112,9 @@ This runs `git pull --rebase` in your source directory and then `chezmoi apply`. Run: - chezmoi git pull -- --rebase && chezmoi diff +```console +$ chezmoi git pull -- --rebase && chezmoi diff +``` This runs `git pull --rebase` in your source directory and `chezmoi diff` then shows the difference between the target state computed from your @@ -108,7 +122,9 @@ source directory and the actual state. If you're happy with the changes, then you can run - chezmoi apply +```console +$ chezmoi apply +``` to apply them. @@ -118,9 +134,11 @@ chezmoi can automatically commit and push changes to your source directory to your repo. This feature is disabled by default. To enable it, add the following to your config file: - [git] - autoCommit = true - autoPush = true +```toml +[git] + autoCommit = true + autoPush = true +``` Whenever a change is made to your source directory, chezmoi will commit the changes with an automatically-generated commit message (if `autoCommit` is true) @@ -141,7 +159,9 @@ arguments to the newly installed chezmoi binary. If your dotfiles repo is `chezmoi init`, and running `chezmoi apply` can be done in a single line of shell: - sh -c "$(curl -fsLS git.io/chezmoi)" -- init --apply +```console +$ sh -c "$(curl -fsLS git.io/chezmoi)" -- init --apply +``` If your dotfiles repo has a different name to `dotfiles`, or if you host your dotfiles on a different service, then see the [reference manual for `chezmoi @@ -152,7 +172,9 @@ can install chezmoi, install your dotfiles, and then remove all traces of chezmoi, including the source directory and chezmoi's configuration directory, with a single command: - sh -c "$(curl -fsLS git.io/chezmoi)" -- init --one-shot +```console +$ sh -c "$(curl -fsLS git.io/chezmoi)" -- init --one-shot +``` ## Manage different types of file @@ -161,7 +183,9 @@ with a single command: If you want chezmoi to create a directory, but ignore its contents, say `~/src`, first run: - mkdir -p $(chezmoi source-path)/src +```console +$ mkdir -p $(chezmoi source-path)/src +``` This creates the directory in the source state, which means that chezmoi will create it (if it does not already exist) when you run `chezmoi apply`. @@ -171,7 +195,9 @@ file in the directory in the source state that will be seen by git (so git does not ignore the directory) but ignored by chezmoi (so chezmoi does not include it in the target state): - touch $(chezmoi source-path)/src/.keep +```console +$ touch $(chezmoi source-path)/src/.keep +``` chezmoi automatically creates `.keep` files when you add an empty directory with `chezmoi add`. @@ -181,13 +207,17 @@ chezmoi automatically creates `.keep` files when you add an empty directory with Create a file called `.chezmoiremove` in the source directory containing a list of patterns of files to remove. When you run - chezmoi apply --remove +```console +$ chezmoi apply --remove +``` chezmoi will remove anything in the target directory that matches the pattern. As this command is potentially dangerous, you should run chezmoi in verbose, dry-run mode beforehand to see what would be removed: - chezmoi apply --remove --dry-run --verbose +```console +$ chezmoi apply --remove --dry-run --verbose +``` `.chezmoiremove` is interpreted as a template, so you can remove different files on different machines. Negative matches (patterns prefixed with a `!`) or @@ -210,7 +240,9 @@ template to re-generate the full contents of the file from the current state. For example, Kubernetes configurations include a current context that can be substituted with: - current-context: {{ output "kubectl" "config" "current-context" | trim }} +``` +current-context: {{ output "kubectl" "config" "current-context" | trim }} +``` ### Populate `~/.ssh/authorized_keys` with your public SSH keys from GitHub @@ -219,9 +251,11 @@ populating your `~/.ssh/authorized_keys`. Put the following in your `~/.local/share/chezmoi/dot_ssh/authorized_keys.tmpl`, where `username` is your GitHub username: - {{ range (gitHubKeys "username") -}} - {{ .Key }} - {{ end -}} +``` +{{ range (gitHubKeys "username") -}} +{{ .Key }} +{{ end -}} +``` ## Integrate chezmoi with your editor @@ -229,7 +263,9 @@ GitHub username: Put the following in your `.vimrc`: - autocmd BufWritePost ~/.local/share/chezmoi/* ! chezmoi apply --source-path % +```vim +autocmd BufWritePost ~/.local/share/chezmoi/* ! chezmoi apply --source-path % +``` ## Include dotfiles from elsewhere @@ -241,9 +277,11 @@ because chezmoi uses its own format for the source state and Oh My Zsh is not distributed in this format. Instead, you can use the `import` command to import a snapshot from a tarball: - curl -s -L -o oh-my-zsh-master.tar.gz https://github.com/robbyrussell/oh-my-zsh/archive/master.tar.gz - mkdir -p $(chezmoi source-path)/dot_oh-my-zsh - chezmoi import --strip-components 1 --destination ${HOME}/.oh-my-zsh oh-my-zsh-master.tar.gz +```console +$ curl -s -L -o oh-my-zsh-master.tar.gz https://github.com/robbyrussell/oh-my-zsh/archive/master.tar.gz +$ mkdir -p $(chezmoi source-path)/dot_oh-my-zsh +$ chezmoi import --strip-components 1 --destination ${HOME}/.oh-my-zsh oh-my-zsh-master.tar.gz +``` Add `oh-my-zsh-master.tar.gz` to `.chezmoiignore` if you run these commands in your source directory so that chezmoi doesn't try to copy the tarball anywhere. @@ -264,24 +302,32 @@ example for VSCode's `settings.json` on Linux: Copy the configuration file to your source directory: - cp ~/.config/Code/User/settings.json $(chezmoi source-path) +```console +$ cp ~/.config/Code/User/settings.json $(chezmoi source-path) +``` Tell chezmoi to ignore this file: - echo settings.json >> $(chezmoi source-path)/.chezmoiignore +```console +$ echo settings.json >> $(chezmoi source-path)/.chezmoiignore +``` Tell chezmoi that `~/.config/Code/User/settings.json` should be a symlink to the file in your source directory: - mkdir -p $(chezmoi source-path)/private_dot_config/private_Code/User - echo -n "{{ .chezmoi.sourceDir }}/settings.json" > $(chezmoi source-path)/private_dot_config/private_Code/User/symlink_settings.json.tmpl +```console +$ mkdir -p $(chezmoi source-path)/private_dot_config/private_Code/User +$ echo -n "{{ .chezmoi.sourceDir }}/settings.json" > $(chezmoi source-path)/private_dot_config/private_Code/User/symlink_settings.json.tmpl +``` The prefix `private_` is used because the `~/.config` and `~/.config/Code` directories are private by default. Apply the changes: - chezmoi apply -v +```console +$ chezmoi apply -v +``` Now, when the program modifies its configuration file it will modify the file in the source state instead. @@ -294,12 +340,17 @@ version [`github.com/robbyrussell/oh-my-zsh`](https://github.com/robbyrussell/oh-my-zsh) to `~/.oh-my-zsh` run: - curl -s -L -o oh-my-zsh-master.tar.gz https://github.com/robbyrussell/oh-my-zsh/archive/master.tar.gz - chezmoi import --strip-components 1 --destination ~/.oh-my-zsh oh-my-zsh-master.tar.gz +```console +$ curl -s -L -o oh-my-zsh-master.tar.gz https://github.com/robbyrussell/oh-my-zsh/archive/master.tar.gz +$ mkdir -p $(chezmoi source-path)/dot_oh-my-zsh +$ chezmoi import --strip-components 1 --destination ~/.oh-my-zsh oh-my-zsh-master.tar.gz +``` Note that this only updates the source state. You will need to run - chezmoi apply +```console +$ chezmoi apply +``` to update your destination directory. @@ -317,20 +368,26 @@ needed. For example, your home `~/.gitconfig` on your personal machine might look like: - [user] - email = "me@home.org" +```toml +[user] + email = "me@home.org" +``` Whereas at work it might be: - [user] - email = "firstname.lastname@company.com" +```toml +[user] + email = "firstname.lastname@company.com" +``` To handle this, on each machine create a configuration file called `~/.config/chezmoi/chezmoi.toml` defining variables that might vary from machine to machine. For example, for your home machine: - [data] - email = "me@home.org" +```toml +[data] + email = "me@home.org" +``` Note that all variable names will be converted to lowercase. This is due to a feature of a library used by chezmoi. @@ -347,17 +404,23 @@ Then, add `~/.gitconfig` to chezmoi using the `--autotemplate` flag to turn it into a template and automatically detect variables from the `data` section of your `~/.config/chezmoi/chezmoi.toml` file: - chezmoi add --autotemplate ~/.gitconfig +``` +$ chezmoi add --autotemplate ~/.gitconfig +``` You can then open the template (which will be saved in the file `~/.local/share/chezmoi/dot_gitconfig.tmpl`): - chezmoi edit ~/.gitconfig +``` +$ chezmoi edit ~/.gitconfig +``` The file should look something like: - [user] - email = {{ .email | quote }} +```toml +[user] + email = {{ .email | quote }} +``` To disable automatic variable detection, use the `--template` or `-T` option to `chezmoi add` instead of `--autotemplate`. @@ -365,17 +428,21 @@ To disable automatic variable detection, use the `--template` or `-T` option to Templates are often used to capture machine-specific differences. For example, in your `~/.local/share/chezmoi/dot_bashrc.tmpl` you might have: - # common config - export EDITOR=vi +``` +# common config +export EDITOR=vi - # machine-specific configuration - {{- if eq .chezmoi.hostname "work-laptop" }} - # this will only be included in ~/.bashrc on work-laptop - {{- end }} +# machine-specific configuration +{{- if eq .chezmoi.hostname "work-laptop" }} +# this will only be included in ~/.bashrc on work-laptop +{{- end }} +``` For a full list of variables, run: - chezmoi data +``` +$ chezmoi data +``` For more advanced usage, you can use the full power of the [`text/template`](https://pkg.go.dev/text/template) language. chezmoi includes @@ -386,7 +453,9 @@ managers](https://github.com/twpayne/chezmoi/blob/master/docs/REFERENCE.md#templ Templates can be executed directly from the command line, without the need to create a file on disk, with the `execute-template` command, for example: - chezmoi execute-template '{{ .chezmoi.os }}/{{ .chezmoi.arch }}' +``` +$ chezmoi execute-template "{{ .chezmoi.os }}/{{ .chezmoi.arch }}" +``` This is useful when developing or debugging templates. @@ -395,7 +464,9 @@ retrieved with chezmoi's template functions. For example, if you have a file stored in 1Password with the UUID `uuid` then you can retrieve it with the template: - {{- onepasswordDocument "uuid" -}} +``` +{{- onepasswordDocument "uuid" -}} +``` The `-`s inside the brackets remove any whitespace before or after the template expression, which is useful if your editor has added any newlines. @@ -413,10 +484,12 @@ machines, or to exclude certain files completely, you can create that chezmoi should ignore, and are interpreted as templates. An example `.chezmoiignore` file might look like: - README.md - {{- if ne .chezmoi.hostname "work-laptop" }} - .work # only manage .work on work-laptop - {{- end }} +``` +README.md +{{- if ne .chezmoi.hostname "work-laptop" }} +.work # only manage .work on work-laptop +{{- end }} +``` The use of `ne` (not equal) is deliberate. What we want to achieve is "only install `.work` if hostname is `work-laptop`" but chezmoi installs everything by @@ -425,8 +498,10 @@ unless the hostname is `work-laptop`". Patterns can be excluded by prefixing them with a `!`, for example: - f* - !foo +``` +f* +!foo +``` will ignore all files beginning with an `f` except `foo`. @@ -437,11 +512,13 @@ any variable. For example, if you want `~/.bashrc` to be different on Linux and macOS you would create a file in the source state called `dot_bashrc.tmpl` containing: - {{ if eq .chezmoi.os "darwin" -}} - # macOS .bashrc contents - {{ else if eq .chezmoi.os "linux" -}} - # Linux .bashrc contents - {{ end -}} +``` +{{ if eq .chezmoi.os "darwin" -}} +# macOS .bashrc contents +{{ else if eq .chezmoi.os "linux" -}} +# Linux .bashrc contents +{{ end -}} +``` However, if the differences between the two versions are so large that you'd prefer to use completely separate files in the source state, you can achieve @@ -449,24 +526,32 @@ this using a symbolic link template. Create the following files: `symlink_dot_bashrc.tmpl`: - .bashrc_{{ .chezmoi.os }} +``` +.bashrc_{{ .chezmoi.os }} +``` `dot_bashrc_darwin`: - # macOS .bashrc contents +``` + # macOS .bashrc contents +``` `dot_bashrc_linux`: - # Linux .bashrc contents +``` +# Linux .bashrc contents +``` `.chezmoiignore` - {{ if ne .chezmoi.os "darwin" }} - .bashrc_darwin - {{ end }} - {{ if ne .chezmoi.os "linux" }} - .bashrc_linux - {{ end }} +``` +{{ if ne .chezmoi.os "darwin" }} +.bashrc_darwin +{{ end }} +{{ if ne .chezmoi.os "linux" }} +.bashrc_linux +{{ end }} +``` This will make `~/.bashrc` a symlink to `.bashrc_darwin` on `darwin` and to `.bashrc_linux` on `linux`. The `.chezmoiignore` configuration ensures that only @@ -478,12 +563,14 @@ The same thing can be achieved using the include function. `dot_bashrc.tmpl` - {{ if eq .chezmoi.os "darwin" }} - {{ include ".bashrc_darwin" }} - {{ end }} - {{ if eq .chezmoi.os "linux" }} - {{ include ".bashrc_linux" }} - {{ end }} +``` +{{ if eq .chezmoi.os "darwin" }} +{{ include ".bashrc_darwin" }} +{{ end }} +{{ if eq .chezmoi.os "linux" }} +{{ include ".bashrc_linux" }} +{{ end }} +``` ### Create a config file on a new machine automatically @@ -495,9 +582,11 @@ initial config file. Specifically, if you have `.chezmoi.toml.tmpl` that looks like this: - {{- $email := promptString "email" -}} - [data] - email = {{ $email | quote }} +``` +{{- $email := promptString "email" -}} +[data] + email = {{ $email | quote }} +``` Then `chezmoi init` will create an initial `chezmoi.toml` using this template. `promptString` is a special function that prompts the user (you) for a value. @@ -505,7 +594,9 @@ Then `chezmoi init` will create an initial `chezmoi.toml` using this template. To test this template, use `chezmoi execute-template` with the `--init` and `--promptString` flags, for example: - chezmoi execute-template --init --promptString email=me@home.org < ~/.local/share/chezmoi/.chezmoi.toml.tmpl +```console +$ chezmoi execute-template --init --promptString email=me@home.org < ~/.local/share/chezmoi/.chezmoi.toml.tmpl +``` ### Re-create your config file @@ -513,32 +604,38 @@ If you change your config file template, chezmoi will warn you if your current config file was not generated from that template. You can re-generate your config file by running: - chezmoi init +```console +$ chezmoi init +``` If you are using any `prompt*` template functions in your config file template you will be prompted again. However, you can avoid this with the following example template logic: - {{- $email := get . "email" -}} - {{- if not $email -}} - {{- $email = promptString "email" -}} - {{- end -}} +``` +{{- $email := get . "email" -}} +{{- if not $email -}} +{{- $email = promptString "email" -}} +{{- end -}} - [data] - email = {{ $email | quote }} +[data] + email = {{ $email | quote }} +``` This will cause chezmoi to first try to re-use the existing `$email` variable and fallback to `promptString` only if it is not set. For boolean variables you can use: - {{- $var := false -}} - {{- if (hasKey . "var") -}} - {{- $var = get . "var" -}} - {{- end -}} +``` +{{- $var := false -}} +{{- if (hasKey . "var") -}} +{{- $var = get . "var" -}} +{{- end -}} - [data] - var = $var +[data] + var = $var +``` ### Handle different file locations on different systems with the same contents @@ -558,12 +655,14 @@ Linux. Both template files should contain `{{- template "file.conf" -}}`. Finally, tell chezmoi to ignore files where they are not needed by adding lines to your `.chezmoiignore` file, for example: - {{ if ne .chezmoi.os "darwin" }} - Library/Application Support/App/file.conf - {{ end }} - {{ if ne .chezmoi.os "linux" }} - .config/app/file.conf - {{ end }} +``` +{{ if ne .chezmoi.os "darwin" }} +Library/Application Support/App/file.conf +{{ end }} +{{ if ne .chezmoi.os "linux" }} +.config/app/file.conf +{{ end }} +``` ### Create an archive of your dotfiles @@ -579,7 +678,9 @@ them by inspecting their permissions. Private files and directories are stored in `~/.local/share/chezmoi` as regular, public files with permissions `0644` and the name prefix `private_`. For example: - chezmoi add ~/.netrc +``` +$ chezmoi add ~/.netrc +``` will create `~/.local/share/chezmoi/private_dot_netrc` (assuming `~/.netrc` is not world- or group- readable, as it should be). This file is still private @@ -601,31 +702,41 @@ expose data as a template function. Log in and get a session using: - eval $(op signin .1password.com ) +``` +$ eval $(op signin .1password.com ) +``` The output of `op get item ` is available as the `onepassword` template function. chezmoi parses the JSON output and returns it as structured data. For example, if the output of `op get item ""` is: - { - "uuid": "", - "details": { - "password": "xxx" - } +```json +{ + "uuid": "", + "details": { + "password": "xxx" } +} +``` Then you can access `details.password` with the syntax: - {{ (onepassword "").details.password }} +``` +{{ (onepassword "").details.password }} +``` Login details fields can be retrieved with the `onepasswordDetailsFields` function, for example: - {{- (onepasswordDetailsFields "uuid").password.value }} +``` +{{- (onepasswordDetailsFields "uuid").password.value }} +``` Documents can be retrieved with: - {{- onepasswordDocument "uuid" -}} +``` +{{- onepasswordDocument "uuid" -}} +``` Note the extra `-` after the opening `{{` and before the closing `}}`. This instructs the template language to remove and whitespace before and after the @@ -640,25 +751,33 @@ function. Log in to Bitwarden using: - bw login +```console +$ bw login +``` Unlock your Bitwarden vault: - bw unlock +```console +$ bw unlock +``` Set the `BW_SESSION` environment variable, as instructed. The structured data from `bw get` is available as the `bitwarden` template function in your config files, for example: - username = {{ (bitwarden "item" "example.com").login.username }} - password = {{ (bitwarden "item" "example.com").login.password }} +``` +username = {{ (bitwarden "item" "example.com").login.username }} +password = {{ (bitwarden "item" "example.com").login.password }} +``` Custom fields can be accessed with the `bitwardenFields` template function. For example, if you have a custom field named `token` you can retrieve its value with: - {{ (bitwardenFields "item" "example.com").token.value }} +``` +{{ (bitwardenFields "item" "example.com").token.value }} +``` ### Use gopass @@ -667,7 +786,9 @@ chezmoi includes support for [gopass](https://www.gopass.pw/) using the gopass C The first line of the output of `gopass show ` is available as the `gopass` template function, for example: - {{ gopass "" }} +``` +{{ gopass "" }} +``` ### Use KeePassXC @@ -676,20 +797,26 @@ KeePassXC CLI (`keepassxc-cli`) to expose data as a template function. Provide the path to your KeePassXC database in your configuration file: - [keepassxc] - database = "/home/user/Passwords.kdbx" +```toml +[keepassxc] + database = "/home/user/Passwords.kdbx" +``` The structured data from `keepassxc-cli show $database` is available as the `keepassxc` template function in your config files, for example: - username = {{ (keepassxc "example.com").UserName }} - password = {{ (keepassxc "example.com").Password }} +``` +username = {{ (keepassxc "example.com").UserName }} +password = {{ (keepassxc "example.com").Password }} +``` Additional attributes are available through the `keepassxcAttribute` function. For example, if you have an entry called `SSH Key` with an additional attribute called `private-key`, its value is available as: - {{ keepassxcAttribute "SSH Key" "private-key" }} +``` +{{ keepassxcAttribute "SSH Key" "private-key" }} +``` ### Use Keychain or Windows Credentials Manager @@ -699,26 +826,34 @@ Windows Credentials Manager (on Windows) via the Set values with: - $ chezmoi secret keyring set --service= --user= - Value: xxxxxxxx +```console +$ chezmoi secret keyring set --service= --user= +Value: xxxxxxxx +``` The value can then be used in templates using the `keyring` function which takes the service and user as arguments. For example, save a GitHub access token in keyring with: - $ chezmoi secret keyring set --service=github --user= - Value: xxxxxxxx +```console +$ chezmoi secret keyring set --service=github --user= +Value: xxxxxxxx +``` and then include it in your `~/.gitconfig` file with: - [github] - user = {{ .github.user | quote }} - token = {{ keyring "github" .github.user | quote }} +``` +[github] + user = {{ .github.user | quote }} + token = {{ keyring "github" .github.user | quote }} +``` You can query the keyring from the command line: - chezmoi secret keyring get --service=github --user= +```console +$ chezmoi secret keyring get --service=github --user= +``` ### Use LastPass @@ -728,11 +863,15 @@ data as a template function. Log in to LastPass using: - lpass login +```console +$ lpass login +``` Check that `lpass` is working correctly by showing password data: - lpass show --json +``` console +$ lpass show --json +``` where `` is a [LastPass Entry Specification](https://lastpass.github.io/lastpass-cli/lpass.1.html#_entry_specification). @@ -743,13 +882,17 @@ template function. The value will be an array of objects. You can use the the field you want. For example, to extract the `password` field from first the "GitHub" entry, use: - githubPassword = {{ (index (lastpass "GitHub") 0).password | quote }} +``` +githubPassword = {{ (index (lastpass "GitHub") 0).password | quote }} +``` chezmoi automatically parses the `note` value of the Lastpass entry as colon-separated key-value pairs, so, for example, you can extract a private SSH key like this: - {{ (index (lastpass "SSH") 0).note.privateKey }} +``` +{{ (index (lastpass "SSH") 0).note.privateKey }} +``` Keys in the `note` section written as `CamelCase Words` are converted to `camelCaseWords`. @@ -757,7 +900,9 @@ Keys in the `note` section written as `CamelCase Words` are converted to If the `note` value does not contain colon-separated key-value pairs, then you can use `lastpassRaw` to get its raw value, for example: - {{ (index (lastpassRaw "SSH Private Key") 0).note }} +``` +{{ (index (lastpassRaw "SSH Private Key") 0).note }} +``` ### Use pass @@ -767,7 +912,9 @@ pass CLI. The first line of the output of `pass show ` is available as the `pass` template function, for example: - {{ pass "" }} +``` +{{ pass "" }} +``` ### Use Vault @@ -779,13 +926,17 @@ The vault CLI needs to be correctly configured on your machine, e.g. the `VAULT_ADDR` and `VAULT_TOKEN` environment variables must be set correctly. Verify that this is the case by running: - vault kv get -format=json +``` +$ vault kv get -format=json +``` The structured data from `vault kv get -format=json` is available as the `vault` template function. You can use the `.Field` syntax of the `text/template` language to extract the data you want. For example: - {{ (vault "").data.data.password }} +``` +{{ (vault "").data.data.password }} +``` ### Use a custom password manager @@ -817,17 +968,23 @@ it afterwards. Specify the encryption key to use in your configuration file (`chezmoi.toml`) with the `gpg.recipient` key: - encryption = "gpg" - [gpg] - recipient = "..." +```toml +encryption = "gpg" +[gpg] + recipient = "..." +``` Add files to be encrypted with the `--encrypt` flag, for example: - chezmoi add --encrypt ~/.ssh/id_rsa +```console +$ chezmoi add --encrypt ~/.ssh/id_rsa +``` chezmoi will encrypt the file with: - gpg --armor --recipient ${gpg.recipient} --encrypt +```bash +gpg --armor --recipient ${gpg.recipient} --encrypt +``` and store the encrypted file in the source state. The file will automatically be decrypted when generating the target state. @@ -836,17 +993,23 @@ decrypted when generating the target state. Specify symmetric encryption in your configuration file: - encryption = "gpg" - [gpg] - symmetric = true +```toml +encryption = "gpg" +[gpg] + symmetric = true +``` Add files to be encrypted with the `--encrypt` flag, for example: - chezmoi add --encrypt ~/.ssh/id_rsa +```console +$ chezmoi add --encrypt ~/.ssh/id_rsa +``` chezmoi will encrypt the file with: - gpg --armor --symmetric +```bash +gpg --armor --symmetric +``` ### Encrypt whole files with age @@ -858,20 +1021,26 @@ re-encrypt it afterwards. Generate a key using `age-keygen`: - $ age-keygen -o $HOME/key.txt - Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p +```console +$ age-keygen -o $HOME/key.txt +Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p +``` Specify age encryption in your configuration file, being sure to specify at least the identity and one recipient: - encryption = "age" - [age] - identity = "/home/user/key.txt" - recipient = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p" +```toml +encryption = "age" +[age] + identity = "/home/user/key.txt" + recipient = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p" +``` Add files to be encrypted with the `--encrypt` flag, for example: - chezmoi add --encrypt ~/.ssh/id_rsa +```console +$ chezmoi add --encrypt ~/.ssh/id_rsa +``` chezmoi supports multiple recipients and recipient files, and multiple identities. @@ -882,18 +1051,23 @@ Typically, `~/.config/chezmoi/chezmoi.toml` is not checked in to version control and has permissions 0600. You can store tokens as template values in the `data` section. For example, if your `~/.config/chezmoi/chezmoi.toml` contains: - [data] - [data.github] +```toml +[data] + [data.github] user = "" token = "" +``` Your `~/.local/share/chezmoi/private_dot_gitconfig.tmpl` can then contain: - {{- if (index . "github") }} - [github] - user = {{ .github.user | quote }} - token = {{ .github.token | quote }} - {{- end }} +``` +{{- if (index . "github") }} +[github] + user = {{ .github.user | quote }} + token = {{ .github.token | quote }} +{{- end }} +``` + Any config files containing tokens in plain text should be private (permissions `0600`). @@ -931,13 +1105,17 @@ useful for disabling scripts. Change to the source directory and create a file called `run_once_install-packages.sh`: - chezmoi cd - $EDITOR run_once_install-packages.sh +```console +$ chezmoi cd +$ $EDITOR run_once_install-packages.sh +``` In this file create your package installation script, e.g. - #!/bin/sh - sudo apt install ripgrep +```sh +#!/bin/sh +sudo apt install ripgrep +``` The next time you run `chezmoi apply` or `chezmoi update` this script will be run. As it has the `run_once_` prefix, it will not be run again unless its @@ -946,13 +1124,15 @@ contents change, for example if you add more packages to be installed. This script can also be a template. For example, if you create `run_once_install-packages.sh.tmpl` with the contents: - {{ if eq .chezmoi.os "linux" -}} - #!/bin/sh - sudo apt install ripgrep - {{ else if eq .chezmoi.os "darwin" -}} - #!/bin/sh - brew install ripgrep - {{ end -}} +``` +{{ if eq .chezmoi.os "linux" -}} +#!/bin/sh +sudo apt install ripgrep +{{ else if eq .chezmoi.os "darwin" -}} +#!/bin/sh +brew install ripgrep +{{ end -}} +``` This will install `ripgrep` on both Debian/Ubuntu Linux systems and macOS. @@ -969,10 +1149,12 @@ stored in `dconf.ini` in your source directory then you can make `chezmoi apply` only load them when the contents of `dconf.ini` has changed by adding the following script as `run_once_dconf-load.sh.tmpl`: - #!/bin/bash +``` +#!/bin/bash - # dconf.ini hash: {{ include "dconf.ini" | sha256sum }} - dconf load / {{ joinPath .chezmoi.sourceDir "dconf.ini" | quote }} +# dconf.ini hash: {{ include "dconf.ini" | sha256sum }} +dconf load / {{ joinPath .chezmoi.sourceDir "dconf.ini" | quote }} +``` As the SHA256 sum of `dconf.ini` is included in a comment in the script, the contents of the script will change whenever the contents of `dconf.ini` are @@ -993,14 +1175,16 @@ chezmoi by creating a `run_once_` script. For example, create a file in your source directory called `run_once_before_install-packages-darwin.sh.tmpl` containing: - {{- if (eq .chezmoi.os "darwin") -}} - #!/bin/bash - - brew bundle --no-lock --file=/dev/stdin </dotfiles` then you can install chezmoi and your dotfiles with the single command: - sh -c "$(curl -fsLS git.io/chezmoi)" -- init --apply +```console +$ sh -c "$(curl -fsLS git.io/chezmoi)" -- init --apply +``` -Or on systems with Powershell, you can use this command: +Or on systems with Powershell, you can use one of the following command: - # To install in ./bin - (iwr -UseBasicParsing https://git.io/chezmoi.ps1).Content | powershell -c - +``` +# To install in ./bin +(iwr -UseBasicParsing https://git.io/chezmoi.ps1).Content | powershell -c - - # To install in another location - '$params = "-BinDir ~/other"', (iwr https://git.io/chezmoi.ps1).Content | powershell -c - +# To install in another location +'$params = "-BinDir ~/other"', (iwr https://git.io/chezmoi.ps1).Content | powershell -c - - # For information about other options, run - '$params = "-?"', (iwr https://git.io/chezmoi.ps1).Content | powershell -c - +# For information about other options, run +'$params = "-?"', (iwr https://git.io/chezmoi.ps1).Content | powershell -c - +``` ## One-line package install @@ -89,6 +97,8 @@ page](https://github.com/twpayne/chezmoi/releases/latest). Download, build, and install chezmoi for your system: - go install github.com/twpayne/chezmoi@latest +```console +$ go install github.com/twpayne/chezmoi@latest +``` Building chezmoi requires Go 1.16 or later. diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 390a9216113..3af4eb22f37 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -19,7 +19,9 @@ Assuming that you have already [installed chezmoi](https://github.com/twpayne/chezmoi/blob/master/docs/INSTALL.md), initialize chezmoi with: - chezmoi init +```console +$ chezmoi init +``` This will create a new git repository in `~/.local/share/chezmoi` where chezmoi will store its source state. By default, chezmoi only modifies files in the @@ -28,24 +30,32 @@ can automate this for you if you want. Manage your first file with chezmoi: - chezmoi add ~/.bashrc +```console +$ chezmoi add ~/.bashrc +``` This will copy `~/.bashrc` to `~/.local/share/chezmoi/dot_bashrc`. Edit the source state: - chezmoi edit ~/.bashrc +```console +$ chezmoi edit ~/.bashrc +``` This will open `~/.local/share/chezmoi/dot_bashrc` in your `$EDITOR`. Make some changes and save the file. See what changes chezmoi would make: - chezmoi diff +```console +$ chezmoi diff +``` Apply the changes: - chezmoi -v apply +```console +$ chezmoi -v apply +``` All chezmoi commands accept the `-v` (verbose) flag to print out exactly what changes they will make to the file system, and the `-n` (dry run) flag to not @@ -54,16 +64,20 @@ see exactly what changes would be made. Next, open a shell in the source directory, to commit your changes: - chezmoi cd - git add . - git commit -m "Initial commit" +```console +$ chezmoi cd +$ git add . +$ git commit -m "Initial commit" +``` [Create a new repository on GitHub](https://github.com/new) called `dotfiles` and then push your repo: - git remote add origin git@github.com:username/dotfiles.git - git branch -M main - git push -u origin main +```console +$ git remote add origin git@github.com:username/dotfiles.git +$ git branch -M main +$ git push -u origin main +``` chezmoi can also be used with [GitLab](https://gitlab.com), or [BitBucket](https://bitbucket.org), [Source Hut](https://sr.ht/), or any other @@ -71,34 +85,46 @@ git hosting service. Finally, exit the shell in the source directory to return to where you were: - exit +```console +$ exit +``` ## Using chezmoi across multiple machines On a second machine, initialize chezmoi with your dotfiles repo: - chezmoi init https://github.com/username/dotfiles.git +```console +$ chezmoi init https://github.com/username/dotfiles.git +``` This will check out the repo and any submodules and optionally create a chezmoi config file for you. It won't make any changes to your home directory until you run: - chezmoi apply +```console +$ chezmoi apply +``` If your dotfiles repo is `https://github.com/username/dotfiles.git` then the above two commands can be combined into just: - chezmoi init --apply username +```console +$ chezmoi init --apply username +``` On any machine, you can pull and apply the latest changes from your repo with: - chezmoi update +```console +$ chezmoi update +``` ## Next steps For a full list of commands run: - chezmoi help +```console +$ chezmoi help +``` chezmoi has much more functionality. Good starting points are adding more dotfiles, and using templates to manage files that vary from machine to machine diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index d4c7cc53e0a..84875ff58dc 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -479,9 +479,11 @@ config file formats. #### `.chezmoi..tmpl` examples - {{ $email := promptString "email" -}} - data: - email: {{ $email | quote }} +``` +{{ $email := promptString "email" -}} +data: + email: {{ $email | quote }} +``` ### `.chezmoiignore` @@ -503,24 +505,26 @@ ignored on different machines. #### `.chezmoiignore` examples - README.md - - *.txt # ignore *.txt in the target directory - */*.txt # ignore *.txt in subdirectories of the target directory - backups/** # ignore backups folder in chezmoi directory and all its contents - # but not in subdirectories of subdirectories; - # so a/b/c.txt would *not* be ignored - backups/** # ignore all contents of backups folder in chezmoi directory - # but not backups folder itself - - {{- if ne .email "firstname.lastname@company.com" }} - # Ignore .company-directory unless configured with a company email - .company-directory # note that the pattern is not dot_company-directory - {{- end }} - - {{- if ne .email "me@home.org }} - .personal-file - {{- end }} +``` +README.md + +*.txt # ignore *.txt in the target directory +*/*.txt # ignore *.txt in subdirectories of the target directory +backups/** # ignore backups folder in chezmoi directory and all its contents + # but not in subdirectories of subdirectories; + # so a/b/c.txt would *not* be ignored +backups/** # ignore all contents of backups folder in chezmoi directory + # but not backups folder itself + +{{- if ne .email "firstname.lastname@company.com" }} +# Ignore .company-directory unless configured with a company email +.company-directory # note that the pattern is not dot_company-directory +{{- end }} + +{{- if ne .email "me@home.org }} +.personal-file +{{- end }} +``` ### `.chezmoiremove` @@ -543,11 +547,15 @@ data. Given: - .chezmoitemplates/foo - {{ if true }}bar{{ end }} +`.chezmoitemplates/foo`: +``` +{{ if true }}bar{{ end }} +``` - dot_config.tmpl - {{ template "foo" . }} +`dot_config.tmpl`: +``` +{{ template "foo" . }} +``` The target state of `.config` will be `bar`. @@ -560,7 +568,9 @@ the current version is too old. #### `.chezmoiversion` examples - 1.5.0 +``` +1.5.0 +``` ## Commands @@ -617,10 +627,12 @@ directory, create a symlink template with `.chezmoi.sourceDir` or #### `add` examples - chezmoi add ~/.bashrc - chezmoi add ~/.gitconfig --template - chezmoi add ~/.vim --recursive - chezmoi add ~/.oh-my-zsh --exact --recursive +```console +$ chezmoi add ~/.bashrc +$ chezmoi add ~/.gitconfig --template +$ chezmoi add ~/.vim --recursive +$ chezmoi add ~/.oh-my-zsh --exact --recursive +``` ### `apply` [*target*...] @@ -640,9 +652,11 @@ applying changes after editing. #### `apply` examples - chezmoi apply - chezmoi apply --dry-run --verbose - chezmoi apply ~/.bashrc +```console +$ chezmoi apply +$ chezmoi apply --dry-run --verbose +$ chezmoi apply ~/.bashrc +``` ### `archive` @@ -663,9 +677,11 @@ Compress the output with gzip. #### `archive` examples - chezmoi archive | tar tvf - - chezmoi archive --output=dotfiles.tar - chezmoi archive --format=zip --output=dotfiles.zip +```console +$ chezmoi archive | tar tvf - +$ chezmoi archive --output=dotfiles.tar +$ chezmoi archive --format=zip --output=dotfiles.zip +``` ### `cat` *target*... @@ -676,7 +692,9 @@ written. #### `cat` examples - chezmoi cat ~/.bashrc +```console +$ chezmoi cat ~/.bashrc +``` ### `cd` @@ -687,7 +705,9 @@ will finally fall back to an OS-specific default. #### `cd` examples - chezmoi cd +```console +$ chezmoi cd +``` ### `chattr` *attributes* *target*... @@ -714,9 +734,11 @@ comma (`,`). #### `chattr` examples - chezmoi chattr template ~/.bashrc - chezmoi chattr noempty ~/.profile - chezmoi chattr private,template ~/.netrc +```console +$ chezmoi chattr template ~/.bashrc +$ chezmoi chattr noempty ~/.profile +$ chezmoi chattr private,template ~/.netrc +``` ### `completion` *shell* @@ -725,8 +747,10 @@ Generate shell completion code for the specified shell (`bash`, `fish`, #### `completion` examples - chezmoi completion bash - chezmoi completion fish --output=~/.config/fish/completions/chezmoi.fish +```console +$ chezmoi completion bash +$ chezmoi completion fish --output=~/.config/fish/completions/chezmoi.fish +``` ### `data` @@ -738,8 +762,10 @@ Set the output format. #### `data` examples - chezmoi data - chezmoi data --format=yaml +```console +$ chezmoi data +$ chezmoi data --format=yaml +``` ### `diff` [*target*...] @@ -751,8 +777,10 @@ be piped into it. #### `diff` examples - chezmoi diff - chezmoi diff ~/.bashrc +```console +$ chezmoi diff +$ chezmoi diff ~/.bashrc +``` ### `docs` [*regexp*] @@ -761,9 +789,11 @@ is case insensitive. If no pattern is given, print `REFERENCE.md`. #### `docs` examples - chezmoi docs - chezmoi docs faq - chezmoi docs howto +```console +$ chezmoi docs +$ chezmoi docs faq +$ chezmoi docs howto +``` ### `doctor` @@ -771,7 +801,9 @@ Check for potential problems. #### `doctor` examples - chezmoi doctor +```console +$ chezmoi doctor +``` ### `dump` [*target*...] @@ -788,8 +820,10 @@ Only include entries of type *types*. #### `dump` examples - chezmoi dump ~/.bashrc - chezmoi dump --format=yaml +```console +$ chezmoi dump ~/.bashrc +$ chezmoi dump --format=yaml +``` ### `edit` [*target*...] @@ -802,9 +836,11 @@ Apply target immediately after editing. Ignored if there are no targets. #### `edit` examples - chezmoi edit ~/.bashrc - chezmoi edit ~/.bashrc --apply - chezmoi edit +```console +$ chezmoi edit ~/.bashrc +$ chezmoi edit ~/.bashrc --apply +$ chezmoi edit +``` ### `edit-config` @@ -812,7 +848,9 @@ Edit the configuration file. #### `edit-config` examples - chezmoi edit-config +```console +$ chezmoi edit-config +``` ### `execute-template` [*template*...] @@ -852,10 +890,12 @@ Simulate the `stdinIsATTY` function by returning *bool*. #### `execute-template` examples - chezmoi execute-template '{{ .chezmoi.sourceDir }}' - chezmoi execute-template '{{ .chezmoi.os }}' / '{{ .chezmoi.arch }}' - echo '{{ .chezmoi | toJson }}' | chezmoi execute-template - chezmoi execute-template --init --promptString email=me@home.org < ~/.local/share/chezmoi/.chezmoi.toml.tmpl +```console +$ chezmoi execute-template '{{ .chezmoi.sourceDir }}' +$ chezmoi execute-template '{{ .chezmoi.os }}' / '{{ .chezmoi.arch }}' +$ echo '{{ .chezmoi | toJson }}' | chezmoi execute-template +$ chezmoi execute-template --init --promptString email=me@home.org < ~/.local/share/chezmoi/.chezmoi.toml.tmpl +``` ### `forget` *targets* @@ -863,7 +903,9 @@ Remove *targets* from the source state, i.e. stop managing them. #### `forget` examples - chezmoi forget ~/.bashrc +```console +$ chezmoi forget ~/.bashrc +``` ### `git` [*arg*...] @@ -872,9 +914,11 @@ occur after `--` to prevent chezmoi from interpreting them. #### `git` examples - chezmoi git add . - chezmoi git add dot_gitconfig - chezmoi git -- commit -m "Add .gitconfig" +```console +$ chezmoi git add . +$ chezmoi git add dot_gitconfig +$ chezmoi git -- commit -m "Add .gitconfig" +``` ### `help` [*command*...] @@ -947,11 +991,13 @@ Guess an SSH repo URL instead of an HTTPS repo. #### `init` examples - chezmoi init user - chezmoi init user --apply - chezmoi init user --apply --purge - chezmoi init user/dots - chezmoi init gitlab.com/user +```console +$ chezmoi init user +$ chezmoi init user --apply +$ chezmoi init user --apply --purge +$ chezmoi init user/dots +$ chezmoi init gitlab.com/user +``` ### `import` *filename* @@ -980,9 +1026,11 @@ Strip *n* leading components from paths. #### `import` examples - curl -s -L -o oh-my-zsh-master.tar.gz https://github.com/robbyrussell/oh-my-zsh/archive/master.tar.gz - mkdir -p $(chezmoi source-path)/dot_oh-my-zsh - chezmoi import --strip-components 1 --destination ~/.oh-my-zsh oh-my-zsh-master.tar.gz +```console +$ curl -s -L -o oh-my-zsh-master.tar.gz https://github.com/robbyrussell/oh-my-zsh/archive/master.tar.gz +$ mkdir -p $(chezmoi source-path)/dot_oh-my-zsh +$ chezmoi import --strip-components 1 --destination ~/.oh-my-zsh oh-my-zsh-master.tar.gz +``` ### `manage` *targets* @@ -998,11 +1046,13 @@ Only include entries of type *types*. #### `managed` examples - chezmoi managed - chezmoi managed --include=files - chezmoi managed --include=files,symlinks - chezmoi managed -i d - chezmoi managed -i d,f +```console +$ chezmoi managed +$ chezmoi managed --include=files +$ chezmoi managed --include=files,symlinks +$ chezmoi managed -i d +$ chezmoi managed -i d,f +``` ### `merge` *target*... @@ -1016,7 +1066,9 @@ instead. #### `merge` examples - chezmoi merge ~/.bashrc +```console +$ chezmoi merge ~/.bashrc +``` ### `purge` @@ -1029,8 +1081,10 @@ Remove without prompting. #### `purge` examples - chezmoi purge - chezmoi purge --force +```console +$ chezmoi purge +$ chezmoi purge --force +``` ### `remove` *targets* @@ -1047,7 +1101,9 @@ templates, and all entries that are not files are ignored. #### `re-add` examples - chezmoi re-add +```console +$ chezmoi re-add +``` ### `rm` *targets* @@ -1063,12 +1119,16 @@ separate them with `--` to prevent chezmoi from interpreting them. To get a full list of available commands run: - chezmoi secret help +```console +$ chezmoi secret help +``` #### `secret` examples - chezmoi secret keyring set --service=service --user=user --value=password - chezmoi secret keyring get --service=service --user=user +```console +$ chezmoi secret keyring set --service=service --user=user --value=password +$ chezmoi secret keyring get --service=service --user=user +``` ### `source-path` [*target*...] @@ -1077,8 +1137,10 @@ print the source directory. #### `source-path` examples - chezmoi source-path - chezmoi source-path ~/.bashrc +```console +$ chezmoi source-path +$ chezmoi source-path ~/.bashrc +``` ### `state` @@ -1086,12 +1148,14 @@ Manipulate the persistent state. #### `state` examples - chezmoi state data - chezmoi state delete --bucket=bucket --key=key - chezmoi state dump - chezmoi state get --bucket=bucket --key=key - chezmoi state set --bucket=bucket --key=key --value=value - chezmoi state reset +```console +$ chezmoi state data +$ chezmoi state delete --bucket=bucket --key=key +$ chezmoi state dump +$ chezmoi state get --bucket=bucket --key=key +$ chezmoi state set --bucket=bucket --key=key --value=value +$ chezmoi state reset +``` ### `status` @@ -1108,7 +1172,9 @@ Only include entries of type *types*. #### `status` examples - chezmoi status +```console +$ chezmoi status +``` ### `unmanage` *target*... @@ -1120,7 +1186,9 @@ List all unmanaged files in the destination directory. #### `unmanaged` examples - chezmoi unmanaged +```console +$ chezmoi unmanaged +``` ### `update` @@ -1132,7 +1200,9 @@ Only update entries of type *types*. #### `update` examples - chezmoi update +```console +$ chezmoi update +``` ### `upgrade` @@ -1160,8 +1230,10 @@ Only include entries of type *types*. #### `verify` examples - chezmoi verify - chezmoi verify ~/.bashrc +```console +$ chezmoi verify +$ chezmoi verify ~/.bashrc +``` ## Editor configuration @@ -1179,7 +1251,9 @@ and `0o077` respectively. For machine-specific control of umask, set the `umask` configuration variable in chezmoi's configuration file, for example: - umask = 0o22 +```toml +umask = 0o22 +``` ## Template execution @@ -1202,8 +1276,10 @@ chezmoi executes templates using `text/template`'s `missingkey=error` option, which means that misspelled or missing keys will raise an error. This can be overridden by setting a list of options in the configuration file, for example: - [template] - options = ["missingkey=zero"] +```toml +[template] + options = ["missingkey=zero"] +``` For a full list of options, see [`Template.Option`](https://pkg.go.dev/text/template?tab=doc#Template.Option). @@ -1248,8 +1324,10 @@ will only invoke `bw` once. #### `bitwarden` examples - username = {{ (bitwarden "item" "").login.username }} - password = {{ (bitwarden "item" "").login.password }} +``` +username = {{ (bitwarden "item" "").login.username }} +password = {{ (bitwarden "item" "").login.password }} +``` ### `bitwardenAttachment` *filename* *itemid* @@ -1263,7 +1341,9 @@ only invoke `bw` once. #### `bitwardenAttachment` examples - {{- (bitwardenAttachment "" "") -}} +``` +{{- (bitwardenAttachment "" "") -}} +``` ### `bitwardenFields` [*arg*...] @@ -1276,34 +1356,34 @@ output from `bw get`: ```json { - "object": "item", - "id": "bf22e4b4-ae4a-4d1c-8c98-ac620004b628", - "organizationId": null, - "folderId": null, - "type": 1, - "name": "example.com", - "notes": null, - "favorite": false, - "fields": [ - { - "name": "text", - "value": "text-value", - "type": 0 + "object": "item", + "id": "bf22e4b4-ae4a-4d1c-8c98-ac620004b628", + "organizationId": null, + "folderId": null, + "type": 1, + "name": "example.com", + "notes": null, + "favorite": false, + "fields": [ + { + "name": "text", + "value": "text-value", + "type": 0 + }, + { + "name": "hidden", + "value": "hidden-value", + "type": 1 + } + ], + "login": { + "username": "username-value", + "password": "password-value", + "totp": null, + "passwordRevisionDate": null }, - { - "name": "hidden", - "value": "hidden-value", - "type": 1 - } - ], - "login": { - "username": "username-value", - "password": "password-value", - "totp": null, - "passwordRevisionDate": null - }, - "collectionIds": [], - "revisionDate": "2020-10-28T00:21:02.690Z" + "collectionIds": [], + "revisionDate": "2020-10-28T00:21:02.690Z" } ``` @@ -1311,16 +1391,16 @@ the return value will be the map ```json { - "hidden": { - "name": "hidden", - "type": 1, - "value": "hidden-value" - }, - "token": { - "name": "token", - "type": 0, - "value": "token-value" - } + "hidden": { + "name": "hidden", + "type": 1, + "value": "hidden-value" + }, + "token": { + "name": "token", + "type": 0, + "value": "token-value" + } } ``` @@ -1329,7 +1409,9 @@ the same arguments will only invoke `bw get` once. #### `bitwardenFields` examples - {{ (bitwardenFields "item" "").token.value }} +``` +{{ (bitwardenFields "item" "").token.value }} +``` ### `gitHubKeys` *user* @@ -1360,9 +1442,11 @@ token](https://docs.github.com/en/github/authenticating-to-github/creating-a-per #### `gitHubKeys` examples - {{ range (gitHubKeys "user") }} - {{- .Key }} - {{ end }} +``` +{{ range (gitHubKeys "user") }} +{{- .Key }} +{{ end }} +``` ### `gopass` *gopass-name* @@ -1374,7 +1458,9 @@ with the same *gopass-name* will only invoke `gopass` once. #### `gopass` examples - {{ gopass "" }} +``` +{{ gopass "" }} +``` ### `include` *filename* @@ -1393,9 +1479,11 @@ only execute the `ioreg -a -l` command once. #### `ioreg` examples - {{ if (eq .chezmoi.os "darwin") }} - {{ $serialNumber := index ioreg "IORegistryEntryChildren" 0 "IOPlatformSerialNumber" }} - {{ end }} +``` +{{ if (eq .chezmoi.os "darwin") }} +{{ $serialNumber := index ioreg "IORegistryEntryChildren" 0 "IOPlatformSerialNumber" }} +{{ end }} +``` ### `joinPath` *element*... @@ -1407,7 +1495,9 @@ first non-empty element is a UNC path. #### `joinPath` examples - {{ joinPath .chezmoi.homeDir ".zshrc" }} +``` +{{ joinPath .chezmoi.homeDir ".zshrc" }} +``` ### `keepassxc` *entry* @@ -1423,8 +1513,10 @@ key-value pairs and cached so calling `keepassxc` multiple times with the same #### `keepassxc` examples - username = {{ (keepassxc "example.com").UserName }} - password = {{ (keepassxc "example.com").Password }} +``` +username = {{ (keepassxc "example.com").UserName }} +password = {{ (keepassxc "example.com").Password }} +``` ### `keepassxcAttribute` *entry* *attribute* @@ -1435,7 +1527,9 @@ prompting, password storage, and result caching. #### `keepassxcAttribute` examples - {{ keepassxcAttribute "SSH Key" "private-key" }} +``` +{{ keepassxcAttribute "SSH Key" "private-key" }} +``` ### `keyring` *service* *user* @@ -1450,9 +1544,11 @@ user's keyring. #### `keyring` examples - [github] - user = {{ .github.user | quote }} - token = {{ keyring "github" .github.user | quote }} +``` +[github] + user = {{ .github.user | quote }} + token = {{ keyring "github" .github.user | quote }} +``` ### `lastpass` *id* @@ -1467,8 +1563,10 @@ from `lastpass` is cached so calling `lastpass` multiple times with the same #### `lastpass` examples - githubPassword = {{ (index (lastpass "GitHub") 0).password | quote }} - {{ (index (lastpass "SSH") 0).note.privateKey }} +``` +githubPassword = {{ (index (lastpass "GitHub") 0).password | quote }} +{{ (index (lastpass "SSH") 0).note.privateKey }} +``` ### `lastpassRaw` *id* @@ -1479,7 +1577,9 @@ further parsing is done on the `note` field. #### `lastpassRaw` examples - {{ (index (lastpassRaw "SSH Private Key") 0).note }} +``` +{{ (index (lastpassRaw "SSH Private Key") 0).note }} +``` ### `lookPath` *file* @@ -1495,9 +1595,11 @@ caution when using it in your templates. #### `lookPath` examples - {{ if lookPath "diff-so-fancy" }} - # diff-so-fancy is in $PATH - {{ end }} +``` +{{ if lookPath "diff-so-fancy" }} +# diff-so-fancy is in $PATH +{{ end }} +``` ### `onepassword` *uuid* [*vault-uuid*] @@ -1512,8 +1614,10 @@ performance. #### `onepassword` examples - {{ (onepassword "").details.password }} - {{ (onepassword "" "").details.password }} +``` +{{ (onepassword "").details.password }} +{{ (onepassword "" "").details.password }} +``` ### `onepasswordDocument` *uuid* [*vault-uuid*] @@ -1528,8 +1632,10 @@ performance. #### `onepasswordDocument` examples - {{- onepasswordDocument "" -}} - {{- onepasswordDocument "" "" -}} +``` +{{- onepasswordDocument "" -}} +{{- onepasswordDocument "" "" -}} +``` ### `onepasswordDetailsFields` *uuid* [*vault-uuid*] @@ -1542,42 +1648,42 @@ elements of `details.fields` are returned as a map indexed by each field's ```json { - "uuid": "", - "details": { - "fields": [ - { + "uuid": "", + "details": { + "fields": [ + { + "designation": "username", + "name": "username", + "type": "T", + "value": "exampleuser" + }, + { + "designation": "password", + "name": "password", + "type": "P", + "value": "examplepassword" + } + ] + } +} +``` + +the return value will be the map: + +```json +{ + "username": { "designation": "username", "name": "username", "type": "T", "value": "exampleuser" - }, - { + }, + "password": { "designation": "password", "name": "password", "type": "P", "value": "examplepassword" - } - ], - } -} -``` - -the return value will be the map: - -```json -{ - "username": { - "designation": "username", - "name": "username", - "type": "T", - "value": "exampleuser" - }, - "password": { - "designation": "password", - "name": "password", - "type": "P", - "value": "examplepassword" - } + } } ``` @@ -1588,7 +1694,9 @@ can significantly improve performance. #### `onepasswordDetailsFields` examples - {{ (onepasswordDetailsFields "").password.value }} +``` +{{ (onepasswordDetailsFields "").password.value }} +``` ### `output` *name* [*arg*...] @@ -1600,7 +1708,9 @@ and fast. #### `output` examples - current-context: {{ output "kubectl" "config" "current-context" | trim }} +``` +current-context: {{ output "kubectl" "config" "current-context" | trim }} +``` ### `pass` *pass-name* @@ -1612,7 +1722,9 @@ the same *pass-name* will only invoke `pass` once. #### `pass` examples - {{ pass "" }} +``` +{{ pass "" }} +``` ### `promptBool` *prompt* @@ -1639,9 +1751,11 @@ generating the initial config file. #### `promptString` examples - {{ $email := promptString "email" -}} - [data] - email = {{ $email | quote }} +``` +{{ $email := promptString "email" -}} +[data] + email = {{ $email | quote }} +``` ### `secret` [*arg*...] @@ -1671,9 +1785,11 @@ templates. #### `stat` examples - {{ if stat (joinPath .chezmoi.homeDir ".pyenv") }} - # ~/.pyenv exists - {{ end }} +``` +{{ if stat (joinPath .chezmoi.homeDir ".pyenv") }} +# ~/.pyenv exists +{{ end }} +``` ### `stdinIsATTY` @@ -1684,12 +1800,14 @@ used. #### `stdinIsATTY` examples - {{ $email := "" }} - {{ if stdinIsATTY }} - {{ $email = promptString "email" }} - {{ else }} - {{ $email = "user@example.com" }} - {{ end }} +``` +{{ $email := "" }} +{{ if stdinIsATTY }} +{{ $email = promptString "email" }} +{{ else }} +{{ $email = "user@example.com" }} +{{ end }} +``` ### `vault` *key* @@ -1701,7 +1819,9 @@ times with the same *key* will only invoke `vault` once. #### `vault` examples - {{ (vault "").data.data.password }} +``` +{{ (vault "").data.data.password }} +``` ### `writeToStdout` *string*... @@ -1710,4 +1830,6 @@ generating the initial config file. #### `writeToStdout` examples - {{- writeToStdout "Hello, world\n" -}} +``` +{{- writeToStdout "Hello, world\n" -}} +``` diff --git a/docs/TEMPLATING.md b/docs/TEMPLATING.md index 92a4e8be655..73a53f47977 100644 --- a/docs/TEMPLATING.md +++ b/docs/TEMPLATING.md @@ -2,13 +2,23 @@ * [Introduction](#introduction) +* [Template data](#template-data) * [Creating a template file](#creating-a-template-file) +* [Editing a template file](#editing-a-template-file) +* [Testing templates](#testing-templates) +* [Template syntax](#template-syntax) + * [Removing whitespace](#removing-whitespace) * [Debugging templates](#debugging-templates) * [Simple logic](#simple-logic) + * [Boolean functions](#boolean-functions) + * [Integer functions](#integer-functions) * [More complicated logic](#more-complicated-logic) + * [Chaining operators](#chaining-operators) * [Helper functions](#helper-functions) * [Template variables](#template-variables) -* [Using .chezmoitemplates for creating similar files](#using-chezmoitemplates-for-creating-similar-files) +* [Using `.chezmoitemplates`](#using-chezmoitemplates) +* [Using `.chezmoitemplates` for creating similar files](#using-chezmoitemplates-for-creating-similar-files) + * [Passing multiple arguments](#passing-multiple-arguments) ## Introduction @@ -31,7 +41,9 @@ if either of the following is true: chezmoi provides a variety of template variables. For a full list, run - chezmoi data +```console +$ chezmoi data +``` These come from a variety of sources: @@ -47,24 +59,32 @@ There are several ways to create a template: * When adding a file for the first time, pass the `--template` argument, for example: - chezmoi add --template ~/.zshrc +```console +$ chezmoi add --template ~/.zshrc +``` * When adding a file for the first time, you can pass the `--autotemplate` argument, which tells chezmoi to make the file as a template and automatically replace variables that chezmoi knows about, for example: - chezmoi add --autotemplate ~/.zshrc +```console +$ chezmoi add --autotemplate ~/.zshrc +``` * If a file is already managed by chezmoi, but is not a template, you can make it a template by running, for example: - chezmoi chattr +template ~/.zshrc +```console +$ chezmoi chattr +template ~/.zshrc +``` * You can create a template manually in the source directory by giving it a `.tmpl` extension, for example: - chezmoi cd - $EDITOR dot_zshrc.tmpl +```console +$ chezmoi cd +$ $EDITOR dot_zshrc.tmpl +``` * Templates in `.chezmoitemplates` must be created manually, for example: @@ -77,7 +97,9 @@ There are several ways to create a template: The easiest way to edit a template is to use `chezmoi edit`, for example: - chezmoi edit ~/.zshrc +```console +$ chezmoi edit ~/.zshrc +``` This will open the source file for `~/.zshrc` in `$EDITOR`. When you quit the editor, chezmoi will check the template syntax. @@ -85,7 +107,9 @@ editor, chezmoi will check the template syntax. If you want the changes you make to be immediately applied after you quit the editor, use the `--apply` option, for example: - chezmoi edit --apply ~/.zshrc +```console +$ chezmoi edit --apply ~/.zshrc +``` ## Testing templates @@ -93,13 +117,17 @@ Templates can be tested with the `chezmoi execute-template` command which treats each of its arguments as a template and executes it. This can be useful for testing small fragments of templates, for example: - chezmoi execute-template '{{ .chezmoi.hostname }}' +```console +$ chezmoi execute-template '{{ .chezmoi.hostname }}' +``` If there are no arguments, `chezmoi execute-template` will read the template from the standard input. This can be useful for testing whole files, for example: - chezmoi cd - chezmoi execute-template < dot_zshrc.tmpl +```console +$ chezmoi cd +$ chezmoi execute-template < dot_zshrc.tmpl +``` ## Template syntax @@ -109,18 +137,22 @@ is copied literally. Variables are written literally, for example: - {{ .chezmoi.hostname }} +``` +{{ .chezmoi.hostname }} +``` Conditional expressions can be written using `if`, `else if`, `else`, and `end`, for example: - {{ if (eq .chezmoi.os "darwin") }} - # darwin - {{ else if (eq .chezmoi.os "linux" ) }} - # linux - {{ else }} - # other operating system - {{ end }} +``` +{{ if (eq .chezmoi.os "darwin") }} +# darwin +{{ else if (eq .chezmoi.os "linux" ) }} +# linux +{{ else }} +# other operating system +{{ end }} +``` For a full description of the template syntax, see the [`text/template` documentation](https://pkg.go.dev/text/template). @@ -135,11 +167,15 @@ A solution for this is to place a minus sign and a space next to the brackets. So `{{- ` for the left brackets and ` -}}` for the right brackets. Here's an example: - HOSTNAME= {{- .chezmoi.hostname }} +``` +HOSTNAME={{- .chezmoi.hostname }} +``` This will result in - HOSTNAME=myhostname +``` +HOSTNAME=myhostname +``` Notice that this will remove any number of tabs, spaces and even newlines and carriage returns. @@ -155,26 +191,32 @@ interpret any data coming from stdin or at the end of the command. It will then interpret all templates and output the result to stdout. For example with the command: - chezmoi execute-template '{{ .chezmoi.os }}/{{ .chezmoi.arch }}' +```console +$ chezmoi execute-template '{{ .chezmoi.os }}/{{ .chezmoi.arch }}' +``` chezmoi will output the current OS and architecture to stdout. You can also feed the contents of a file to this command by typing: - cat foo.txt | chezmoi execute-template +```console +$ cat foo.txt | chezmoi execute-template +``` ## Simple logic A very useful feature of chezmoi templates is the ability to perform logical operations. - # common config - export EDITOR=vi +``` +# common config +export EDITOR=vi - # machine-specific configuration - {{- if eq .chezmoi.hostname "work-laptop" }} - # this will only be included in ~/.bashrc on work-laptop - {{- end }} +# machine-specific configuration +{{- if eq .chezmoi.hostname "work-laptop" }} +# this will only be included in ~/.bashrc on work-laptop +{{- end }} +``` In this example chezmoi will look at the hostname of the machine and if that is equal to "work-laptop", the text between the `if` and the `end` will be included @@ -210,9 +252,11 @@ You can also create more complicated expressions. The `eq` command can accept multiple arguments. It will check if the first argument is equal to any of the other arguments. - {{ if eq "foo" "foo" "bar" }}hello{{end}} - {{ if eq "foo" "bar" "foo" }}hello{{end}} - {{ if eq "foo" "bar" "bar" }}hello{{end}} +``` +{{ if eq "foo" "foo" "bar" }}hello{{end}} +{{ if eq "foo" "bar" "foo" }}hello{{end}} +{{ if eq "foo" "bar" "bar" }}hello{{end}} +``` The first two examples will output `hello` and the last example will output nothing. @@ -223,9 +267,11 @@ The operators `or` and `and` can also accept multiple arguments. You can perform multiple checks in one if statement. - {{ if (and (eq .chezmoi.os "linux") (ne .email "me@home.org")) }} - ... - {{ end }} +``` +{{ if (and (eq .chezmoi.os "linux") (ne .email "me@home.org")) }} +... +{{ end }} +``` This will check if the operating system is Linux and the configured email is not the home email. The brackets are needed here, because otherwise all the @@ -254,12 +300,16 @@ are currently on. A list of the variables defined by chezmoi can be found There are, however more variables than that. To view the variables available on your system, execute: - chezmoi data +```console +$ chezmoi data +``` This outputs the variables in JSON format by default. To access the variable `chezmoi.kernel.osrelease` in a template, use - {{ .chezmoi.kernel.osrelease }} +``` +{{ .chezmoi.kernel.osrelease }} +``` This way you can also access the variables you defined yourself. @@ -276,15 +326,17 @@ data explicitly. For example: - .chezmoitemplates/part.tmpl: - {{ if eq .chezmoi.os "linux" }} - # linux config - {{ else }} - # non-linux config - {{ end }} - - dot_file.tmpl: - {{ template "part.tmpl" . }} +``` +.chezmoitemplates/part.tmpl: +{{ if eq .chezmoi.os "linux" }} +# linux config +{{ else }} +# non-linux config +{{ end }} + +dot_file.tmpl: +{{ template "part.tmpl" . }} +``` ## Using `.chezmoitemplates` for creating similar files @@ -294,32 +346,40 @@ be inserted in other template files, for example: Create `.local/share/chezmoi/.chezmoitemplates/alacritty`: - some: config - fontsize: {{ . }} - more: config +``` +some: config +fontsize: {{ . }} +more: config +``` Notice the file name doesn't have to end in `.tmpl`, as all files in the directory `.chezmoitemplates` are interpreted as templates. Create other files using the template `.local/share/chezmoi/small-font.yml.tmpl` - {{- template "alacritty" 12 -}} +``` +{{- template "alacritty" 12 -}} +``` `.local/share/chezmoi/big-font.yml.tmpl` - {{- template "alacritty" 18 -}} +``` +{{- template "alacritty" 18 -}} +``` Here we're calling the shared `alacritty` template with the font size as the `.` value passed in. You can test this with `chezmoi cat`: - $ chezmoi cat ~/small-font.yml - some: config - fontsize: 12 - more: config - $ chezmoi cat ~/big-font.yml - some: config - fontsize: 18 - more: config +```console +$ chezmoi cat ~/small-font.yml +some: config +fontsize: 12 +more: config +$ chezmoi cat ~/big-font.yml +some: config +fontsize: 18 +more: config +``` ### Passing multiple arguments @@ -343,14 +403,18 @@ them in the file `.config/chezmoi/.chezmoi.toml`: Use the variables in `.local/share/chezmoi/.chezmoitemplates/alacritty`: - some: config - fontsize: {{ .fontsize }} - font: {{ .font }} - more: config +``` +some: config +fontsize: {{ .fontsize }} +font: {{ .font }} +more: config +``` And connect them with `.local/share/chezmoi/small-font.yml.tmpl`: - {{- template "alacritty" .alacritty.small -}} +``` +{{- template "alacritty" .alacritty.small -}} +``` At the moment, this means that you'll have to duplicate the alacritty data in the config file on every machine, but a feature will be added to avoid this. @@ -360,4 +424,6 @@ the config file on every machine, but a feature will be added to avoid this. Using the same alacritty configuration as above, you can pass the arguments to it with a dictionary, for example `.local/share/chezmoi/small-font.yml.tmpl`: - {{- template "alacritty" dict "fontsize" 12 "font" "DejaVu Sans Mono" -}} +``` +{{- template "alacritty" dict "fontsize" 12 "font" "DejaVu Sans Mono" -}} +```