dbrownell-dotter 0.10.1

Project:

Package:

Development:

Contents

• Overview
• Installation
• Development
• Additional Information
• License

Overview

dbrownell_Dotter is a declarative dotfile management tool that helps you install, synchronize, and manage configuration files across your system. It supports:

• File installation via copying, symlinking, or template rendering
• Jinja2 templating for dynamic configuration files
• Variable substitution from command-line arguments or environment variables
• Regex-based substitutions for modifying existing files in-place
• Command execution for install steps that cannot be expressed as file content
• Reverse synchronization to push manual changes back to source files
• Post-install instructions displayed once the install process completes without errors

Configuration is defined in YAML or JSON5 files, making it easy to version control and share your dotfile setup. See davidbrownell/dotfiles for an example of such a configuration.

How to use dbrownell_Dotter

Basic Commands

Install dotfiles:

uvx dbrownell_Dotter Install <config_file(s)> [OPTIONS]

Reverse sync changes back to source:

uvx dbrownell_Dotter ReverseSync <config_file(s)> [OPTIONS]

Common options:

• --var key=value - Pass template variables (can be used multiple times)
• --dry-run - Preview changes without modifying files
• --verbose - Show verbose output
• --debug - Show debug information

Variables

Variables can be used in configuration files and jinja templates.

Configuration File Format

variable_definitions:
  username: "Your username (ex: `john`)"
  email: "Your email address (ex: `john@example.com`)"

entries:
  # Simple file copy/link
  - source: my_config.txt
    dest: ~/.config/myapp/config.txt

  # Jinja2 template (auto-detected by .jinja, .jinja2, or .j2 extension)
  - source: bashrc.jinja
    dest: ~/.bashrc

  # Regex substitution on existing file
  - dest: /etc/myapp/config.conf
    substitutions:
      - pattern: "^EMAIL=.*$"
        replacement: "EMAIL={{ email }}"

  # Set the execute flag on the destination (only valid when the destination is a file)
  - source: my_script.sh
    dest: ~/bin/my_script.sh
    make_executable: true

  # Commands run when the entry is encountered, so entries that follow may rely on the changes
  # that they make
  - name: Configuring git
    commands:
      - git config --global user.name "{{ username }}"
      - git config --global user.email "{{ email }}"
      - git config --global core.autocrlf input

  # Instructions displayed once the install process completes without errors
  - post_install_instructions: |
      Run `chsh -s $(which zsh)` to make zsh the default shell for {{ username }}.

The commands associated with an entry are written to a single temporary script that runs when the entry is encountered, so state established by one command is visible to those that follow it. The entry fails as soon as one of its commands fails.

Examples

Install with variables:

uvx dbrownell_Dotter Install config.yaml --var username=john --var email=john@example.com

Preview changes before installing:

uvx dbrownell_Dotter Install config.yaml --dry-run

Sync manual edits back to source files:

uvx dbrownell_Dotter ReverseSync config.yaml --var username=john

Installation

Note that these steps are not required when invoking dbrownell_Dotter via uvx.

Verifying Signed Artifacts

Artifacts are signed and verified using py-minisign and the public key in the file ./minisign_key.pub.

To verify that an artifact is valid, visit the latest release and download the .minisign signature file that corresponds to the artifact, then run the following command, replacing <filename> with the name of the artifact to be verified:

uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>'); print('The file has been verified.')"

Development

Please visit Contributing and Development for information on contributing to this project.

Additional Information

Additional information can be found at these locations.

License

dbrownell_Dotter is licensed under the MIT license.