dotpatina

dotpatina is a rust application for managing system dotfiles and configuration.

Installation

dotpatina can be installed from its crate at crates.io.

cargo install dotpatina

Verify Installation

# View dotpatina version
❱ dotpatina --version

# View dotpatina usage info
❱ dotpatina --help
The patina CLI renders files from templates and sets of variables as defined in patina toml files

Usage: dotpatina [OPTIONS] <COMMAND>

Commands:
  render  Render a patina to stdout
  apply   Render and apply a patina
  help    Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  Increase logging verbosity
  -q, --quiet...    Decrease logging verbosity
  -h, --help        Print help
  -V, --version     Print version

Usage

dotpatina takes templated configuration files (using handlebars templating), rendering configuration files, and applying them to target locations on the file system. This information is provided by a Patina toml file.

Patina File

This is an example Patina file for git tooling.

# Metadata fields describe the Patina
name = "git-patina"
description = "A Patina for git tooling"

# Variables are free-form and can be defined for the whole Patina.
# Or, variables can be loaded from separate files from the command line.
[vars]
editor = "vim"

# A list of files define a template and target file.
# The template is a handlebar template (or plain file) that is processed.
# The target is the system location to store the rendered template.
[[files]]
template = "gitconfig.hbs"
target = "../../output/.gitconfig"

[[files]]
template = "lazygit.config.yml"
target = "../../output/lazygit.config"

Variables Files

Variables can be stored in separate toml files. Variables are free-form and overlay on top of the base Patina variables.

This is useful when variables need to change based on the machine Patinas are being applied to.

[user]
name = "User Name"
email = "user@email.com"

Template Files

Patina templates are defined using handlebars templates. Or, they can be raw files if no templating is required.

Handlebar Template

Templating uses the Handlebars templating language.

Templates are rendered using the variables provided directly in the Patina file and passed as separate variables files. In this example, editor is provided in the Patina file but user.email and user.name are provided in a separate variables file.

gitconfig.hbs

[user]
    email = <{{ user.email }}>
    name = <{{ user.name }}>
[pager]
    branch = false
[core]
	editor = {{ editor }}
[pull]
	rebase = false
[init]
	defaultBranch = main
[fetch]
	prune = true

Raw File

Raw files without templating work as well.

lazygit.config.yml

gui:
  showBottomLine: false
  showCommandLog: false
  showPanelJumps: false
  border: rounded
  showNumstatInFilesView: true

customCommands:
  - key: "U"
    command: "git submodule update --init --recursive"
    context: "files, localBranches, status"
    description: "Update submodules"
    stream: true

Render a Patina

dotpatina supports rendering Patina files to stdout for previewing.

Provide a path to a Patina toml file that defines files and variables used for rendering. Separate variables toml files can be provided to overlay variable customizations.

dotpatina render patina.toml --vars vars.toml

Applying a Patina

Applying a Patina is how rendered files get written to the file system.

dotpatina apply patina.toml --vars vars.toml

A diff view is presented with each apply command to show only lines that will change. This could be due to changing the template, or using a different set of variables.

dotpatina apply patina.toml --vars other-vars.toml