Personal dotfiles for Linux, mainly Arch, and macOS.
Includes config for Bash, Zsh, Fish, Git, tmux, kitty, mise, KDE/GTK theming, OpenRGB, REAPER, and related tools, plus a reference snapshot of a Hyprland setup.
Neovim configuration now lives in a separate repository: zkm/nvim-config. Starship is the prompt for bash, zsh and fish.
git clone https://github.com/zkm/dotfiles ~/.dotfiles
cd ~/.dotfiles
./setup.shsetup.sh is intentionally destructive for managed dotfiles.
Before it creates fresh symlinks, it removes these files and directories in your home directory:
- Shell:
~/.bashrc,~/.bash_profile,~/.bash_aliases,~/.zshrc,~/.zprofile,~/.zlogin,~/.zsh,~/.p10k.zsh - Aliases:
~/.aliasesand~/.aliases.local - Other:
~/.gitconfig,~/.gemrc,~/.tmux.conf,~/.dircolors,~/.bin
It also replaces each of these in ~/.config with a link to the repo's copy, deleting whatever was there:
fish,mise,starship.toml,kitty,wezterm,ghostty,alacritty,mako,fastfetch
Back up anything important first. To keep machine-only aliases, put them in ~/.dotfiles/aliases.local (bash/zsh) or ~/.dotfiles/config/fish/aliases.local.fish (fish). Both are gitignored, and setup links the first one to ~/.aliases.local.
setup.sh does the following:
- Detects your shell mode.
- Interactive terminals: asks for
bash,zshorfish, defaulting to your current shell. - Non-interactive (
SHELL_MODE=auto, the default): keeps your current shell if it's zsh or fish, otherwise uses bash. - Force a shell:
SHELL_MODE=bash ./setup.sh,SHELL_MODE=zsh ./setup.shorSHELL_MODE=fish ./setup.sh - The chosen shell is installed if needed and set as your login shell with
chsh.
- Interactive terminals: asks for
- Installs core packages:
- macOS: Homebrew + packages
- Linux:
pacman,dnf,apt,yumoremerge(Gentoo) - Installs
starshipwhen available and uses it as the default prompt backend. - Linux: tries to install
papirus-icon-theme(best effort; skipped if unavailable)
- Creates directories used by shortcuts (
~/Documents/work,~/Developer, OpenRGB dirs). - Symlinks repo-managed dotfiles into
$HOME.- Includes bash files (
~/.bashrc,~/.bash_profile,~/.bash_aliases) and zsh files. - Includes
~/.config/fish(see Fish below). - Includes app config such as
~/.config/kitty,~/.config/miseand~/.config/starship.tomlwhen present in-repo.
- Includes bash files (
- Syncs custom desktop assets when present:
Icons/dark-side->~/.local/share/icons/dark-sideWallpapers->~/Pictures/Wallpapers
- Uses repo-managed shell configs to initialize
pyenv,rbenv, andmisewhen installed. - Uses Starship as the prompt. The init hooks are already in
bashrc,zshrcandconfig/fish/config.fish. - Optionally installs Powerlevel10k only when
PROMPT_BACKEND=p10kand zsh mode is active. - Installs fonts (MesloLGS Nerd Font + Fira Code Nerd Font, with local file fallback).
- Sets the default Terminal.app profile on macOS to
Pro. - Tries to install browsers (Firefox and Chrome/Chromium).
- Tries to install Visual Studio Code.
- Arch Linux: bootstraps
yayif needed and installsvisual-studio-code-binfrom AUR.
- Installs Docker:
- macOS: installs Docker Desktop (Homebrew cask)
- Linux: installs Docker engine + compose plugin/package, enables the service, and adds your user to the
dockergroup
- Optionally installs OpenRGB and REAPER.
The full catalog lives in aliases for bash and zsh, and in config/fish/conf.d/10-aliases.fish plus config/fish/functions/ for fish. The shortcuts below work in all three shells.
| Shortcut | What it does |
|---|---|
work / dev |
Go to common working directories |
j <name> |
Jump to frequently used directories with zoxide |
l, ll, la, lt, tree |
List files quickly with eza when available |
ff <pattern> |
Find files with fd |
search <pattern> |
Search recursively with rg |
fcd |
Pick a directory with fzf and change into it |
fvim |
Pick one or more files with fzf and open them in vim |
| Shortcut | What it does |
|---|---|
v |
Open nvim |
vim / vi |
Open nvim or fall back to vim |
catp <file> |
Show plain file output, using bat when installed |
preview <file> |
Preview a file with line numbers and syntax highlighting when available |
json |
Pretty-print JSON with jq |
| Shortcut | What it does |
|---|---|
imgcat <file> |
Display images directly in Kitty |
imgpick |
Pick an image with fzf and preview it in Kitty |
img <file> |
Run imgcat with a shorter command |
| Shortcut | What it does |
|---|---|
g, gst, gd, gl |
Run common Git commands |
gco, gb, gc, gcm, gp, gps |
Check out, branch, commit, pull, and push |
tl, ta, tn, tk |
List, attach, create, and kill tmux sessions |
| Shortcut | What it does |
|---|---|
reload |
Restart the current shell |
bt |
Launch btop |
neofetch |
Run fastfetch when available, or fall back to neofetch |
docker-start, docker-stop, docker-restart, docker-status, docker-log |
Manage the Docker daemon |
web-start, web-stop, web-restart, web-status |
Manage nginx, php-fpm, and mariadb together |
plex-start, plex-stop, plex-status |
Manage the Plex service |
| Shortcut | What it does |
|---|---|
rgb-blizzard, rgb-matrix, rgb-rainbow, rgb-off |
Start or stop OpenRGB lighting effects |
rgb-stop |
Stop running RGB scripts and turn the lights off |
sync-local-music, syncipod, dryrun-music, sync-music |
Run music library sync workflows |
config/fish is linked to ~/.config/fish and is a full port of the bash/zsh setup:
config.fish: PATH, mise, Starship, fzf key bindings (Ctrl-R,Ctrl-T,Alt-C) and the motd banner.conf.d/10-aliases.fishandfunctions/: the alias catalog, including zoxide'sj. Longer helpers (Navidrome, RAID, OpenRGB, Docker) are fish functions.- Plugins are managed by fisher and listed in
fish_plugins: autopair.fish and done (a desktop notification when a long command finishes). The plugin files are committed, so they work right after setup. Runfisher updateto refresh them. - Machine-specific aliases go in
~/.config/fish/aliases.local.fish, which is gitignored. fish_variables(fish's own universal-variable state) is gitignored too.
Powerlevel10k is zsh-only, so PROMPT_BACKEND=p10k has no effect in fish.
gitconfig keeps credentials in memory for 8 hours (credential.helper = cache) instead of writing them to a plaintext ~/.git-credentials. GitHub uses gh auth git-credential.
For a persistent store, add the helper for your OS to ~/.gitconfig.local, which gitconfig includes and git doesn't track:
# Linux with a Secret Service (KWallet, gnome-keyring)
[credential]
helper = /usr/lib/git-core/git-credential-libsecretOn macOS, Apple's and Homebrew's git already use the keychain (osxkeychain). The libsecret helper's path differs by distro, so check where your git package installs it.
- macOS: Docker Desktop is installed if missing. Launch Docker Desktop once after setup to initialize the daemon.
- Linux: setup tries to enable and start Docker with
systemctl, then adds your user to thedockergroup. - Linux group changes usually require logging out and back in before running Docker without
sudo.
Quick checks:
docker --version
docker info
docker compose versionIf docker info fails on macOS:
- Open Docker Desktop and wait until it shows as running.
If Linux says permission denied on /var/run/docker.sock:
sudo usermod -aG docker "$USER"
newgrp docker
docker infoIf the daemon is not running on Linux:
sudo systemctl enable --now docker
sudo systemctl status dockerThese installs are optional.
If you run ./setup.sh interactively, setup will prompt:
- Install OpenRGB? [y/N]
- Install REAPER? [y/N]
If you run setup non-interactively, use environment flags.
Install both:
INSTALL_MEDIA_TOOLS=1 ./setup.shInstall only one:
INSTALL_OPENRGB=1 ./setup.sh
INSTALL_REAPER=1 ./setup.shNotes:
- macOS: tries the Homebrew casks
openrgbandreaper. - Arch: installs
openrgbvia pacman; triesreaperviayay(AUR). - apt/dnf/yum systems: try to install
openrgb; REAPER is usually installed manually.
- GTK configs are primarily Linux-targeted. KDE Plasma dotfiles (
dolphinrc,kdeglobals, etc.) are not managed by this repo — they change too often from live desktop state to be worth tracking in git. - Package install paths are tuned mostly for Arch first, with
dnf/apt/yumfallbacks. - On Debian Bookworm (including Raspberry Pi OS Bookworm),
fastfetchmay be unavailable in default APT repositories. Setup now treats it as optional and continues. - Shell startup shows a motd-forge banner instead of running
fastfetch/neofetchautomatically (those are still available manually via theneofetchalias).setup.shinstalls the gem withgem install motd_forgeif agemcommand is onPATH; otherwise install Ruby (e.g. viarbenv) first and run that command yourself. - bash, zsh and fish are all supported, with the same aliases in each.
- Hyprland:
config/hypr(CachyOS's Lua-based config) andconfig/waybarare reference snapshots and setup doesn't install them. CachyOS manages that config through its own packages, so linking it from here would fight package upgrades. Edit~/.config/hyprdirectly and copy changes back into the repo.update_waybar.shcopies the Waybar config into~/.config/waybar. - Tested environments are listed below.
- Uses Homebrew for package/app installation.
- Installs fonts into
~/Library/Fonts. - Sets Apple Terminal default/startup profile to
Pro. - Linux desktop theming files are present in-repo but mostly not applied by macOS tooling.
Run:
./uninstall.shThis removes symlinks that point to this repo, cleans up shell init lines added by setup, and removes optional components installed by setup, including the Powerlevel10k clone and installed font copies.
Create a timestamped snapshot of your current files:
./local/bin/backup_current_files.sh [source_dir] [backup_dir]Examples:
# Snapshot current directory into ./backups/<timestamp>
./local/bin/backup_current_files.sh
# Snapshot ~/.config into ~/Backups/config-snapshots/<timestamp>
./local/bin/backup_current_files.sh ~/.config ~/Backups/config-snapshotsNotes:
- Each run creates a new snapshot directory named like
20260322_101530. - Directory structure is preserved inside each snapshot.
- If the backup directory is inside the source directory, it is automatically excluded.
- Arch Linux + KDE Plasma 6.6.5
- Fedora Linux 44 + GNOME 50.1
- Gentoo + KDE Plasma
- Ubuntu + GNOME
- Linux Mint + Cinnamon
- Debian + GNOME
- Rocky Linux + GNOME
- CachyOS + GNOME 50
- CachyOS + Hyprland (fish as login shell)
- macOS (Homebrew-based path)
The repo ignores generated and runtime artifacts, including:
- OpenRGB logs/cache/venv and backup JSON files
- fish's
fish_variablesand the local-onlyaliases.local.fish - pipx launcher symlinks in
local/bin - REAPER license/registration artifacts
- Runtime logs and editor temp files
This keeps the repo focused on reusable configuration instead of machine-specific runtime files.