.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. ./install
3. ???
4. Profit

Updates

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

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 state
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 generation

dfm docs generates Markdown documentation under the docs/ directory. The subcommands are:

dfm docs alias        # regenerate alias table
dfm docs folders      # document interesting folders
dfm docs keybindings  # update keybinding docs for tmux, nvim and others
dfm docs all          # run every docs task

The docs/ folder contains generated cheat sheets, keybindings and other reference files. New documentation can be added without modifying this README.

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.