#dotfiles #cli #dotfile #dotfiles-manager

app punktf

A cross-platform multi-target dotfiles manager

4 releases (stable)

Uses new Rust 2021

new 1.0.2 Sep 29, 2022
1.0.1 Sep 8, 2021
1.0.0 Aug 23, 2021
0.1.0 Jul 24, 2021

#34 in Configuration

21 downloads per month

MIT/Apache

195KB
4.5K SLoC

punktf - A cross-platform multi-target dotfiles manager

MIT License GitHub Issues Continuous Integration rust docs Crates.io Homebrew AUR Chocolatey

Yet another dotfile manager?!

Well, yes, but hear me out: This project was driven by the personal need of having to manage several dotfiles for different machines/targets. You want the same experience everywhere: On your Windows workstation along with an Ubuntu WSL instance, your Debian server and your private Arch installation. This tool fixes that problem while being cross-platform and blazingly fast. You won't need multiple sets of dotfile configurations ever again!

Features:

  • Compile and deploy your dotfiles with one command across different platforms
  • Use handlebar-like instructions to insert variables and compile sections conditionally
  • Define pre- and post-hooks to customize the behavior with your own commands
  • Create multiple profiles for different targets
  • Works on Windows and Linux

Installation

Homebrew

Install punktf using Homebrew on Linux:

brew install michidk/tools/punktf

AUR

Install punktf from AUR on Arch Linux.

To install it use your favorite AUR capable package manager (e.g. yay, pikaur):

NOTE: As this builds punktf from source an up-to-date rust installation is needed.

yay punktf

or

pikaur -S punktf

Chocolatey

Install punktf using Chocolatey on Windows:

choco install punktf

Cargo & Crates.io

Install punktf using cargo and crates.io on Windows and Linux:

cargo install punktf

Building from source

To install punktf from source the following is needed:

  • An up-to-date rust installation
  • An installed nightly toolchain
# Clone
git clone https://github.com/Shemnei/punktf
cd punktf

# Build (cargo)
cargo build --release

Usage

Commands

To deploy a profile, use the deploy subcommand:

# deploy 'windows' profile
`punktf` deploy windows

# deploy (custom source folder)
`punktf` --source /home/demo/mydotfiles deploy windows

Adding the -h/--help flag to a given subcommand, will print usage instructions.

Source Folder

The punktf source folder is the folder containing the dotfiles and punktf profiles. We recommend setting the PUNKTF_SOURCE environment variable so that the dotfiles can be compiled using punktf deploy <profile>.

punktf searches for the source folder in the following order:

  1. Paths specified with -s/--source
  2. Paths specified by an environment variable PUNKTF_SOURCE
  3. The current working directory of the shell

The source folder should contain two sub-folders:

  • profiles\: Contains the punktf profile definitions (.yaml or .json)
  • dotfiles\: Contains folders and the actual dotfiles

Example punktf source folder structure:

+ profiles
  + windows.yaml
  + base.yaml
  + arch.json
  + dotfiles
    + .gitconfig
    + init.vim.win
    + base
      + demo.txt
    + linux
      + .bashrc
    + windows
      + alacritty.yml

Target

Determines where punktf will deploy files too. It can be set with:

  1. Variable target in the punktf profile file
  2. Environment variable PUNKTF_TARGET

Profiles

Profiles define which dotfiles should be used. They can be a .json or .yaml file.

Example punktf profile:

variables:
  OS: "windows"

target: "C:\\Users\\Demo"

dotfiles:
  - path: "base"
  - path: "windows/alacritty.yml"
    target:
      path: "C:\\Users\\Demo\\AppData\\Local\\alacritty.yml"
    merge: Ask

All properties are explained in the wiki.

Templates

Please refer to the wiki for the templating syntax.

Dotfile Repositories using punktf

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~7.5MB
~140K SLoC