.dotfiles

Welcome to ivuorinen's .dotfiles repository. It's a hodgepodge of scripts and configurations, tests and mistakes I'm not aware of yet. As I find more interesting tools, configs and other stuff, this repository will live accordingly.

Please for the love of everything good do not use these 1:1 as your own dotfiles, fork or download the repository as a zip and go from there with your own configs.

It would be nice if you'd add an issue linking to your fork or repo so I can see what interesting stuff you've done with it. Sharing is caring.

Setup

First time setup

1. Clone this repository to $HOME/.dotfiles
2. git submodule update --init --recursive
3. ./install
4. ???
5. Profit

Updates

cd $HOME/.dotfiles && git pull && ./install

To refresh symlinks only, including the hosts/<host>/ overlay links (faster, skips package installs and provisioning):

cd $HOME/.dotfiles && git pull && ./install --links

The looks

Interesting files and locations

Interesting folders

Path	Description
.github	GitHub Repository configuration files, meta.
hosts/{hostname}/	Configs that should apply to that host only.
local/bin	Helper scripts that I've collected or wrote.
scripts	Setup scripts.

Host specific configuration

Configurations under hosts/<hostname> are applied only when running on the matching machine. Each host folder contains its own install.conf.yaml that is processed by Dotbot during installation.

dotfile folders

Repo	Destination	Description
base/	.*	$HOME level files.
config/	.config/	Configurations for applications.
local/	.local/	XDG Base folder: bin, share and man
ssh/	.ssh/	SSH Configurations.

dfm - the dotfiles manager

.local/bin/dfm is a shell script that has some tools that help with dotfiles management.

Running dfm gives you a list of available commands.

Documentation

dfm docs lists every file under docs/ with its first header as the description; dfm docs <file> renders one (via glow, falling back to bat, then cat). dfm helpers docs-* regenerates the generated docs.

dfm docs                     # list all docs
dfm docs aliases             # show the shell aliases doc
dfm docs tmux-keybindings    # show tmux keybindings
dfm docs mise                # show the mise tool guide

dfm helpers docs-all      # regenerate every doc
dfm helpers docs-aliases  # regenerate docs/aliases.md
dfm helpers docs-tmux     # tmux keybindings only
dfm helpers docs-nvim     # nvim keybindings only
dfm helpers docs-wezterm  # wezterm keybindings only

The docs/ folder also contains other reference files (folder layout, command catalogue) that are maintained directly rather than via dfm.

Configuration

The folder structure follows XDG Base Directory Specification where possible.

XDG Variables

Env	Default	Short description
$XDG_BIN_HOME	$HOME/.local/bin	Local binaries
$XDG_CONFIG_HOME	$HOME/.config	User-specific configs
$XDG_DATA_HOME	$HOME/.local/share	User-specific data files
$XDG_STATE_HOME	$HOME/.local/state	App state that should persist between restarts

Please see docs/folders.md for more information.

Managing submodules

This repository uses Git submodules for external dependencies. After cloning, run:

git submodule update --init --recursive

To pull submodule updates later use:

git submodule update --remote --merge

The helper script add-submodules.sh documents how each submodule is added and configured. Submodules are automatically updated by the update-submodules.yml workflow.

Testing

Shell scripts under local/bin are validated with Bats. Run yarn test to execute every test file. Bats is installed as a development dependency, so run yarn install first if needed.