# dotpatina
[](https://crates.io/crates/dotpatina)
[](https://camerontaylor.dev/dotpatina/dotpatina/index.html)
[](https://github.com/axis7818/patina/actions/workflows/continuous-integration.yaml)
[](https://github.com/axis7818/patina/actions/workflows/continuous-deployment.yaml)
[](./LICENSE)
dotpatina is a rust application for managing system dotfiles and configuration.
## Installation
`dotpatina` can be installed from its crate at crates.io.
```sh
cargo install dotpatina
```
### Verify Installation
```sh
# 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.
```toml
# 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.
```toml
[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](https://handlebarsjs.com/guide/) 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`
```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`
```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.
```sh
dotpatina render patina.toml --vars vars.toml
```
### Applying a Patina
Applying a Patina is how rendered files get written to the file system.
```sh
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.
```sh
dotpatina apply patina.toml --vars other-vars.toml
```
