Files and shell configuration

A set can carry files as well as packages. Each one names a source in the repository and where it belongs on the machine:

[[files]]
source = "files/gitconfig"
target = "~/.gitconfig"

Files are rendered, not copied. The source is a template, so the same file can differ per machine where it needs to.

Your shell configuration

.zshrc is a special case: it is not one file in the repository but the concatenation of the shell/*.zsh fragments of every active set, in filename order.

sets/core/shell/10-path.zsh
sets/core/shell/99-dotfix-status.zsh
sets/web/shell/20-node.zsh

Numbering the fragments is what gives you control over order. Small, separately named files also make it obvious which set contributed what.

Because the result is assembled, there is no single file to write an edited .zshrc back to. dotfix says so rather than guessing — edit the fragment instead.

Anything that should never be shared

The generated .zshrc ends by sourcing ~/.zshrc.local if that file exists:

[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local

That file is yours alone — it is not in the repository and dotfix never reads or writes it. Put the things that belong to this machine and nowhere else there: a work-only proxy, a path to a client’s toolchain, an experiment you have not decided about. Because it is sourced last, it also wins over anything a set contributed.

Bringing an existing .zshrc in

On a Mac you have been using, your .zshrc already exists and dotfix did not write it. It shows up as a local edit and is left alone:

~ /Users/you/.zshrc  (generated — edited locally)

Adopting it means deciding what belongs where: a 10-path.zsh fragment for your PATH, a 50-aliases.zsh for aliases, and so on. That split is a judgement about which machines want which part, so dotfix does not do it for you.

Caution

Until you have moved your shell configuration into fragments, do not apply the generated .zshrc over it. dotfix will not do this on its own — a file it did not write is never overwritten without being asked.

A file you edited by hand

Any managed file you change locally is reported the same way. You then have two honest options: write your version back into the repository, or take the repository’s version and lose the local change. dotfix asks which; it never picks for you.

Next steps

• Secrets — how a config file references a password without storing it.
• Sets — where fragments live.