DOCSEARCHbyAlgolia
Submit Docs

chezmoi

repository·master·Indexed 12 days ago

https://github.com/twpayne/chezmoi

A dotfile management tool written in Go that enables users to securely manage and synchronize configuration files across multiple machines. It supports Windows, whole-file encryption for private files, password manager integration, and templates with custom variables to handle machine-specific differences.

Tokens
134.7K
Snippets
574
Records
734
Agent score
95%

What's inside chezmoi

  1. What is chezmoi and when should you use it?

    master

    chezmoi is a tool for managing personal configuration files (dotfiles, such as ~/.gitconfig) across multiple machines. It is designed to keep different operating systems (Linux, macOS, Windows, FreeBSD, OpenBSD, Termux) and different user accounts (e.g., home vs. work) in sync while allowing for machine-specific customizations.

    Use chezmoi if:

    • You want to maintain a single source of truth (typically a git repository) for your dotfiles.
    • You need to manage secrets (passwords, tokens, private keys) securely.
    • You use multiple machines with different configurations but want to share core settings.

    Do not use chezmoi if:

    • You do not personalize your configuration.
    • You only ever use a single operating system with a single account.
    • Your dotfiles contain no secrets.

  2. Overview of chezmoi

    master
    chezmoi is a tool designed to manage your dotfiles (configuration files) across multiple, diverse machines securely. It allows you to maintain a single source of truth for your configurations and apply them to different environments.

  3. Advantages of using chezmoi over custom scripts or other managers

    master

    chezmoi provides battle-tested functionality that is often missing from custom shell scripts or lightweight managers (like GNU Stow or bare git repos), including:

    • Dry-run and diff modes to preview changes.
    • Script execution capabilities.
    • Conflict resolution.
    • Cross-platform support (including Windows).
    • Zero-dependency installation: It is distributed as a single, stand-alone, statically-linked binary. You can run it even without git installed.

  4. Why use a dotfile manager like chezmoi?

    master
    Dotfile managers provide a consistent development environment across multiple machines (home, work, ephemeral environments like Docker or GitHub Codespaces). They offer essential safety features such as an undo command and the ability to restore from backups, similar to how version control systems protect source code.

  5. Distinguish between static `.chezmoidata` and dynamic data

    master

    It is important to choose the correct mechanism for your data based on whether it is static or dynamic:

    • Static Data: Use .chezmoidata.$FORMAT files for data that is constant and does not require template execution. Note: These files cannot be templates themselves because they must be parsed before the template engine starts.
    • Dynamic Machine Data: For data that depends on the machine (e.g., hostname, OS version), use the data section of a .chezmoi.$FORMAT.tmpl configuration file.
    • Dynamic Environment Data: To read environment variables or command output within a template, use template functions like output, fromJson, or fromYaml.

  6. Understand the execution order of chezmoi special files

    master

    chezmoi uses several special files and directories to manage configuration, data, and external sources. These files are optional and are processed in a specific, deterministic order during an operation (like chezmoi apply).

    Understanding this order is critical for managing dependencies between files (e.g., ensuring data files are loaded before templates attempt to use them).

    Execution Order:

    1. .chezmoiroot: Sets the source state path.
    2. .chezmoi.$FORMAT.tmpl: Configures the chezmoi config file (used during init or apply --init).
    3. Data files: .chezmoidata.$FORMAT or .chezmoidata/ directories (loaded before templates).
    4. .chezmoitemplates/: Directories available for use in source templates.
    5. .chezmoiignore: Defines files/directories to ignore.
    6. .chezmoiremove: Defines files to be removed during an apply.
    7. External sources: .chezmoiexternal.$FORMAT or .chezmoiexternals/ (included as if they were in the source state).
    8. .chezmoiversion: Checked before operations to ensure version compatibility.

  8. Manage directories and symbolic links

    master

    Directories

    Directories are represented by regular directories in the source state. Supported attributes include:

    • exact_: Removes any entries in the target state that are not explicitly specified in the source state.
    • private_: Clears all group and world permissions.
    • readonly_: Clears all write permission bits.

    Symbolic Links

    Represented by files with the symlink_ prefix.

    • The file content is interpreted as the link target (trailing newlines are stripped).
    • Files with the .tmpl suffix are interpreted as templates.
    • If the resulting target is empty or whitespace-only, the symlink is removed.

  10. How scripts work in chezmoi

    master

    chezmoi supports scripts that execute during chezmoi apply. Scripts are any files in the source directory prefixed with run_ and are executed in alphabetical order.

    Script Types

    • run_ scripts: Executed every time you run chezmoi apply.
    • run_onchange_ scripts: Executed only if their content has changed since the last successful execution.
    • run_once_ scripts: Executed once for each unique version of the content. chezmoi tracks the SHA256 hash of the content (after template execution) in a database. The script won't run again unless the content changes.

    Execution Details

    • Ordering: Use before_ or after_ prefixes to control execution timing relative to file updates (e.g., run_once_before_install-package.sh).
    • Templates: Files with the .tmpl suffix are treated as templates. If a template resolves to only whitespace or an empty string, the script will not execute.
    • Environment: Scripts must include a #! shebang line or be an executable binary. The working directory is set to the first existing parent directory in the destination tree.
    • Special Directory: Scripts placed in a .chezmoiscripts directory at the root of the source directory are executed normally without creating a corresponding directory in the target state.
    • Modes: In verbose mode, script contents are printed before execution. In dry-run mode, scripts are not executed.

    Note: Scripts break the declarative approach and should be used sparingly. All scripts should be idempotent.

    run_onchange_install-packages.sh

  11. How hooks work in chezmoi

    master

    Hooks are commands executed before or after specific chezmoi events. Unlike standard scripts, hooks are always executed, even when running chezmoi with the --dry-run flag.

    Because they run automatically and potentially frequently, hooks must be:

    1. Fast: They should not block the main chezmoi execution flow significantly.
    2. Idempotent: Running them multiple times should have the same effect as running them once, avoiding side effects if the event is triggered repeatedly.

  12. Template syntax and whitespace control

    master

    Template actions are wrapped in {{ and }}.

    Removing Whitespace: To prevent template actions from leaving unwanted blank lines or spaces in your output, use a minus sign next to the brackets: {{- or -}}. This removes any number of tabs, spaces, or newlines surrounding the action.

    # Without whitespace control (might leave a newline)
HOSTNAME=
{{ .chezmoi.hostname }}

# With whitespace control (removes surrounding whitespace)
HOSTNAME={{- .chezmoi.hostname }}