Home

What is Tuckr?

Tuckr is a dotfile manager as well as a symlink farm. It aims to reduce the amount of work necessary to get up and running on a new machine. It takes inspiration from other existing dotfile managers such as chezmoi and yadm and borrows its core idea from GNU Stow's simplicity.

Since simplicity is one of the main goals of this project, the tool tries as much as possible to avoid any sort of configuration and instead is opinionated on how the dotfiles repo should be structured. This is intended to make learning how to use and setup everything intuitive at a glance and it also is how tuckr validates that everything is setup correctly.

How does Tuckr work?

Dotfiles directory

With tuckr all dotfiles have to be on a dotfile directory so that it can know about their existence and keep track of them. Tuckr aims to comply with system standards, so it uses the system's desired config directory, there's no way to use a custom config path (at least for now, or until I have been convinced that there should be alternative paths).

Tuckr looks up the following paths for dotfiles:

Platform	Config Path	Home Path
Linux/BSDs/etc	$HOME/.config/dotfiles	$HOME/.dotfiles
MacOS	$HOME/Library/Application Support/dotfiles	$HOME/.dotfiles
Windows	%HomePath%\AppData\Roaming/dotfiles	%HomePath%/.dotfiles

The dotfiles directory itself uses the following structure:

dotfiles
├── Configs # Stores all configuration files
├── Secrets # Stores encrypted files
└── Hooks # Stores scripts that configure the system

Dotfile validation

All dotfiles are stored inside a Configs directory where each directory in it is related to a certain group or program. Tuckr uses this to group the dotfiles and examine the state of these groups in the host machine. It achieves this by going through the file system and checking where symlinks point to:

• if it points to the related dotfile in the repo it's deemed as symlinked
• if it's not symlinked it's deemed as unsymlinked
• if it's a symlink but points to somewhere else it's put on not_owned to indicate that it's in conflict

All these checks are done right after the program's execution starts. Once the entire repo is mapped to either one of those states. The actual command execution starts.

Some commands work only on dotfiles with certain statuses, such as:

• add: works on not_symlinked and not_owned if conflicts are being resolved
• rm: works on symlinked only

Hooks

Hooks are just a basic finite state machine that decides when to symlink dotfiles along with running some scripts. It runs in 3 phases: Prehook -> Symlink -> Posthook

Both the prehook and posthook phases are script running phases, you can run anything in those phases as long as you have a script prefixed with either post_ or pre_. This is useful when you have to run a setup, then symlink the program and then run some sort of final configuration on said program.

Secrets

Secrets are encrypted files using the chacha20poly1305 encryption algorithm to securely store information sensitive configuration. This is useful for storing environment related stuff or any file related to one's system configuration that might be too sensitive to store plainly.

This exists only as convenience for those that just want to store some secrets quickly and don't care much about how it's being done (the command handles everything for you, all you have to know is the file name and the group name). If you have a specific set of requirements that ought to be met in production, this probably will not suffice.