Previewing multi-platform template results on a single platform (with limitations)

[bradenhilton]

I've been brainstorming ways of previewing templates whose results differ based on the current platform (OS/arch etc.).

The best I've come up with so far, which I'm somewhat disappointed I didn't think of earlier, is to use top-level template variables in place of the .chezmoi.* values:

{{- $os := "CHANGE ME" -}}
{{- $arch := "CHANGE ME" -}}

{{- if eq "darwin" $os -}}
darwin...
{{- else if eq "linux" $os -}}
linux...
{{- else if eq "windows" $os -}}
windows...
{{- end }}

To preview the template result for a given platform, simply change the values of the top-level variables and execute the template with execute-template.

In the absence of a better editor solution (extension, plugin etc.), you can use execute-template to output the template result to a temporary file. If your editor supports multiple buffers/panes, you can put this side-by-side with the template and re-run the execute-template command when the template is saved for almost real-time previewing.

A major limitation of this approach is it doesn't work well in templates that use OS-specific commands/tools in output, or OS-specific chezmoi data like .chezmoi.osRelease or .chezmoi.windowsVersion. There are some workarounds but none of them are particularly elegant.

One such workaround would be to wrap these calls in a condition, e.g.:

{{- $preview := true -}}

{{ if $preview -}}
placeholder values...
{{- else -}}
real values... (output, .chezmoi.osRelease, .chezmoi.windowsVersion etc.)
{{- end }}

When you are happy with your template, you can simply change the top-level template variable values appropriately, e.g.:

{{- $os := .chezmoi.os -}}
{{- $arch := .chezmoi.arch -}}
{{- $preview := false -}}

[Lockszmith-GH]

I understand the template and what it does, didn't fully understand what you were trying to solve though.
Could you elaborate with an example?

[bradenhilton]

I was experiencing an issue with a multi-platform template on Linux, where I was only using .chezmoi.os in my conditions, which it turns out was caused by a whitespace control character on the delimiters, but, as I primarily use Windows at the moment (and author as much of my dotfiles as I can get away with on there), I missed it until I went to test it in a Linux VM. If I had been aware of a solution like this before that happened, I could have quickly checked each permutation and the issue would have been obvious.

Subtle gotchas like that are where I see this method being especially useful.

[halostatue]

…so you’re saying we need a unit test framework for our templates? :D

[twpayne]

You can also use environment variables and the cat command which might give a lighter UX.

In your template (say dot_file.sh) write:

#/bin/sh

{{- $os := or (env "TEST_OS") .chezmoi.os -}}
echo "Running on {{ $os }}"

And then override OS by running:

$ TEST_OS=windows chezmoi cat .file

[bradenhilton]

Thanks for mentioning this. I agree that it is better UX in the vast majority of cases, but I do see a few issues.

Firstly, chezmoi cat can't be used to quickly test a template in .chezmoitemplates without creating a target file template first, IIRC. Of course, the goal of a template in .chezmoitemplates would be to eventually use it in a target file template anyway, but sometimes I like to create the .chezmoitemplates file first before I even think about the target.

I was wondering if adding a file argument to execute-template would help here, if only to provide a cross-platform method for reading the contents of the file. cat can be used on UNIX-like operating systems (and PowerShell, but it's an alias for Get-Content, which it's possible to remove or reassign to something completely unrelated) and something like type is typically used in cmd.exe. I haven't considered if there are any edge cases yet, would unresolved edge cases (or even the overlap with the cat command) completely block something like that?

Secondly, temporarily setting an environment variable for a single command is only that frictionless if you use a sane operating system 😀

As far as I can tell, the concept of a temporary environment variable for a single command doesn't really exist on Windows, in either cmd.exe or PowerShell. At a minimum it requires explicitly unsetting the environment variable after the command.

See

https://superuser.com/questions/223104/setting-and-using-variable-within-same-command-line-in-windows-cmd-exe

and

https://stackoverflow.com/questions/1420719/powershell-setting-an-environment-variable-for-a-single-command-only

for more info, though I can't guarantee you will emerge on the other side as the same person.

[twpayne]

I was wondering if adding a file argument to execute-template would help here, if only to provide a cross-platform method for reading the contents of the file. cat can be used on UNIX-like operating systems (and PowerShell, but it's an alias for Get-Content, which it's possible to remove or reassign to something completely unrelated) and something like type is typically used in cmd.exe. I haven't considered if there are any edge cases yet, would unresolved edge cases (or even the overlap with the cat command) completely block something like that?

Good idea! Implemented in #4391.