Personal config files for zsh, bash, fish, Ghostty, Neovim, git, COSMIC, Sway, starship, and keyd, managed by a single dependency-free Python script, dots.

Layout#

dotfiles/
├── dots                        # the manager itself - lives at the repo root
├── zsh/zshrc                   # ~/.zshrc
├── bash/bashrc                 # ~/.bashrc
├── fish/config.fish            # ~/.config/fish/config.fish
├── fish/fish_plugins           # ~/.config/fish/fish_plugins
├── ghostty/config.ghostty      # ~/.config/ghostty/config.ghostty
├── nvim/                       # ~/.config/nvim
├── git/gitconfig               # ~/.gitconfig
├── cosmic/xkb_config           # ~/.config/cosmic/com.system76.CosmicComp/v1/xkb_config
├── cosmic/custom-shortcuts     # ~/.config/cosmic/com.system76.CosmicSettings.Shortcuts/v1/custom
├── cosmic/system-actions       # ~/.config/cosmic/com.system76.CosmicSettings.Shortcuts/v1/system_actions
├── sway/                       # ~/.config/sway
├── starship/starship.toml      # ~/.config/starship.toml
├── keyd/default.conf           # /etc/keyd/default.conf
└── backups/                    # created automatically by `dots install`, gitignore-able

Commands#

./dots collect [--dry-run]   # system  -> repo   (copy current configs in)
./dots install [--dry-run]   # repo    -> system  (symlink configs into place)
./dots check                 # show install status of every tracked item
./dots diff [timestamp]      # compare a backup snapshot against the repo
./dots diff --list           # list available backup snapshots

collect and install print exactly what they're about to do under --dry-run, with no changes made — worth running first any time you're unsure what will happen.

First-time setup#

mkdir -p ~/dotfiles && cd ~/dotfiles
git init
# put `dots` in here, then:
chmod +x dots          # note: the executable bit may not survive
                        # download/transfer - this step is normal
./dots collect
git add -A
git commit -m "initial dotfiles"
git remote add origin <your-repo-url>
git push -u origin main

On a new machine#

git clone <your-repo-url> ~/dotfiles
cd ~/dotfiles
chmod +x dots
./dots install

Each tracked file/directory becomes a symlink pointing into the repo (e.g. ~/.config/nvim -> ~/dotfiles/nvim). Anything that was already sitting at that path gets moved into backups/<timestamp>/... inside the repo first — nothing is ever silently overwritten or deleted.

Keeping it in sync#

Once installed, your real configs are the repo files (via the symlinks), so editing ~/.config/sway/config day-to-day is editing the repo directly. Just remember to commit:

cd ~/dotfiles && git add -A && git commit -m "tweak sway config"

collect is mainly useful for the first run, or any time you've edited a file outside the symlink (e.g. restored from a backup) and want to pull it back into the repo.

Checking status / recovering from a backup#

./dots check          # what's linked, what's not, what differs
./dots diff --list    # see available backup snapshots
./dots diff            # diff the most recent backup against the repo
./dots diff 20260620-073535   # diff a specific snapshot

diff is for the case where install backed something up (because a real file was sitting where a symlink was about to go) and you want to see exactly what was in it versus what's there now.

Adding or removing tracked files#

Edit the DOTFILES_MAP dictionary near the top of dots.

Notes / things worth reviewing before your first commit#

cosmic/ tracks three specific files (keyboard layout, custom shortcuts, and system-action overrides) rather than the entire ~/.config/cosmic tree. COSMIC spreads state across many per-component subfolders; only these three have been singled out as worth versioning.
Consider adding backups/ to .gitignore — those are local safety snapshots, not really meant for version control.

Configure Feed