dbrownell-dotter 0.7.0

Tools to distribute dotfiles to multiple locations when provisioning a new machine.

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
• Reverse synchronization to push manual changes back to source files

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.

Variable Type	Format
Environment Variable	${VAR_NAME}
Command Line Variable	{{ VAR_NAME }}

Configuration File Format

variable_definitions:
  username: "Your username (ex: `john`)"
  email: "Your email address (ex: `[e-mail]`)"

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
  - source: null
    dest: /etc/myapp/config.conf
    substitutions:
      - pattern: "^EMAIL=.*$"
        replacement: "EMAIL={{ email }}"

Examples

Install with variables:

uvx dbrownell_Dotter Install config.yaml --var username=john --var email=[e-mail]

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.

Installation Method	Command
Via uv	uv add dbrownell_Dotter
Via pip	pip install dbrownell_Dotter

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.

Title	Document	Description
Code of Conduct	CODE_OF_CONDUCT.md	Information about the norms, rules, and responsibilities we adhere to when participating in this open source community.
Contributing	CONTRIBUTING.md	Information about contributing to this project.
Development	DEVELOPMENT.md	Information about development activities involved in making changes to this project.
Governance	GOVERNANCE.md	Information about how this project is governed.
Maintainers	MAINTAINERS.md	Information about individuals who maintain this project.
Security	SECURITY.md	Information about how to privately report security issues associated with this project.

License

dbrownell_Dotter is licensed under the MIT license.