Skip to content
/ punktf Public

⚡ A cross-platform multi-target dotfiles manager

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Notifications You must be signed in to change notification settings

Shemnei/punktf

Repository files navigation

punktf - A multi-target dotfiles manager

MIT License 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

Packaging status

Install punktf using Homebrew on Linux:

brew install michidk/tools/punktf

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

Install punktf using Scoop on Windows:

scoop bucket add shemnei https://github.com/Shemnei/scoop-bucket

scoop install punktf

Install punktf using Chocolatey on Windows:

choco install punktf

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 --profile windows

# deploy (custom source folder)
punktf deploy --source /home/demo/mydotfiles --profile 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

links:
  - source_path: "C:\\Users\\Demo\\Dotfiles\\test.txt"
    target_path: "C:\\Users\\Demo\\test.txt"

All properties are explained in the wiki.

Templates

Please refer to the wiki for the templating syntax.

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.