█████╗  █████╗ ███████╗██╗  ██╗██╗   ██╗████████╗ ██████╗ ███████╗██╗  ██╗
██╔══██╗██╔══██╗██╔════╝██║  ██║██║   ██║╚══██╔══╝██╔═══██╗██╔════╝██║  ██║
███████║███████║███████╗███████║██║   ██║   ██║   ██║   ██║███████╗███████║
██╔══██║██╔══██║╚════██║██╔══██║██║   ██║   ██║   ██║   ██║╚════██║██╔══██║
██║  ██║██║  ██║███████║██║  ██║╚██████╔╝   ██║   ╚██████╔╝███████║██║  ██║
╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝ ╚═════╝    ╚═╝    ╚═════╝ ╚══════╝╚═╝  ╚═╝

Arch Linux · Omarchy · Hyprland — my daily driver, versioned.

▶️ Live Demo

Demo Video

---

$ cat table_of_contents.txt

• Screenshots
• Features
• Included Configurations
• Installation
• Updating an Existing Installation
• 🩺 Diagnose & Repair
• Zsh Is Required
• About ~/.local/bin/env
• What install.sh Actually Does
• What bootstrap.sh Actually Does
• Repository Structure
• Requirements
• Backups & Rollback
• Wallpaper Credits
• License

---

📸 Screenshots

Hero shot: Hyprland + Omarchy shell + wallhaven

Ghostty + Fastfetch + Starship	Editor workflow in VS Code

LazyVim	Yazi file manager	Idle screensaver

✨ Features

🖥️ WM	Hyprland on Omarchy (Quickshell-based shell)
🎨 Theme	wallhaven, applied system-wide via Aether
⚡ System Info	Fastfetch
⭐ Prompt	Starship
📝 Editors	Neovim (LazyVim) & VS Code
📂 File Manager	Yazi
🐚 Shell	Zsh (fish in foot)
👻 Terminal	Ghostty / Alacritty / Kitty / Foot
📊 Monitor	Btop
🚀 Bar / Launcher / OSD	Omarchy shell (Quickshell)
🖼️ Wallpapers	Curated collection included

---

📦 Included Configurations

alacritty · atuin · btop · fastfetch · fish · foot · ghostty · hyprland
kitty · lazydocker · lazygit · mise · mpv · neovim · omarchy · starship
tmux · voxtype · VS Code · yazi · zellij · zsh

---

📥 Installation

Option A — One-shot bootstrap (fresh machine)

curl -fsSL https://raw.githubusercontent.com/Aashutosh31/dotfiles/main/bootstrap.sh | bash

Handles everything: installs git/yay if missing, clones the repo, and runs the installer.

Option B — Manual (already have the repo cloned, or want to review first)

git clone https://github.com/Aashutosh31/dotfiles.git
cd dotfiles
chmod +x install.sh
./install.sh

After installation, if Hyprland is running, reload the config to apply changes:

hyprctl reload

Then open a new terminal — the installer makes sure zsh is your login shell, and a shell change only applies to new login sessions.

---

🔁 Updating an Existing Installation

install.sh is safe to re-run at any time — that is the update mechanism:

cd ~/dotfiles
git pull
./install.sh

• Every file it overwrites is backed up first to ~/.dotfiles-backup/<timestamp>/.
• It never deletes your config directories and never removes files that only exist on your system.
• It does not perform a system upgrade (no pacman -Syu) — on Omarchy, upgrades belong to omarchy update, which the installer never bypasses. It only installs packages from packages/ that are missing.
• If something in your shell environment is still off afterwards, see Diagnose & Repair below.

---

🩺 Diagnose & Repair

Two companion scripts let you fix problems without reinstalling everything.

doctor.sh — read-only health check

./doctor.sh

Checks, without touching anything:

Check	Severity
Required packages installed (zsh, starship, zoxide, atuin, yazi, mise, plugins, …)	FAIL if missing
Commands resolvable on $PATH	FAIL if missing
/bin/zsh + /usr/bin/zsh exist, zsh listed in /etc/shells	FAIL if missing
Login shell is zsh	FAIL otherwise
~/.local/bin/env + env.fish present	FAIL if missing
zsh-autosuggestions / zsh-syntax-highlighting plugin files	FAIL if missing
Installed shell configs match the repo	WARN on drift
Broken symlinks under ~/.config	WARN

Exit code is non-zero when any required component is missing, so you can use it in scripts or CI.

repair.sh — fix an existing installation

./repair.sh

Safe and idempotent — run it as many times as you like; unchanged state prints [SKIP]. It:

1. Installs only required packages that are actually missing.
2. Ensures zsh is installed and listed in /etc/shells.
3. Sets your login shell to zsh — only if it isn't already (never repeats chsh), printing a clear message and reminding you to start a new session.
4. Recreates ~/.local/bin/env / env.fish when they are missing (see below).
5. Re-applies only the shell-related configs (.zshrc, .XCompose, starship, fish, mise, atuin) — each backed up before being overwritten.

It never runs a system upgrade, never deletes home/config data, and exits non-zero if anything could not be fixed.

---

🐚 Zsh Is Required

This setup requires Zsh. The shell environment depends on zsh-specific features:

• zsh options & completion (setopt, autoload -Uz compinit)
• zoxide integration (z, cd=z)
• atuin history integration (eval "$(atuin init zsh)")
• zsh-autosuggestions & zsh-syntax-highlighting
• Starship prompt
• all existing aliases/functions in .zshrc

install.sh and repair.sh both ensure: zsh installed → /bin/zsh present and listed in /etc/shells → login shell set to /bin/zsh (only when needed). After the change you must start a new login session/terminal for it to take effect. Don't try to source ~/.zshrc from Bash — it uses zsh-only builtins and will error.

---

About ~/.local/bin/env

The last line of .zshrc sources ~/.local/share/../bin/env (= ~/.local/bin/env). That file is created by uv's standalone installer (curl -LsSf https://astral.sh/uv/install.sh | sh), not by mise, Omarchy, pacman, or this repo. On a fresh machine where uv was never installed standalone, the file doesn't exist and every zsh startup ends with:

/home/<you>/.local/share/../bin/env: No such file or directory

install.sh and repair.sh recreate this file — byte-for-byte identical to uv's template — whenever it is missing, so the shell always starts cleanly even before uv itself is installed.

---

🔍 What install.sh Actually Does

Click to expand the step-by-step breakdown

1. Resolves the repo path — works regardless of where you run it from ($REPO = script's own directory).
2. Installs missing official packages — ensures everything in packages/pacman.txt is present, using Omarchy's omarchy-pkg-add helper when available (falling back to pacman -S --needed). This does not perform a full system upgrade — on Omarchy, system upgrades belong to omarchy update, which the installer never bypasses.
3. Installs AUR packages — if yay is present, installs everything in packages/aur.txt non-interactively (--answerclean None --answerdiff None). Skips gracefully if yay isn't found.
4. Creates a timestamped backup at ~/.dotfiles-backup/<YYYY><MM><DD>-<HHMMSS>/ — see Backups & Rollback below.
5. Backs up and replaces each config — for every tool in the list (alacritty, atuin, btop, fastfetch, fish, foot, ghostty, hypr, kitty, lazydocker, lazygit, mise, mpv, nvim, omarchy, tmux, voxtype, yazi, zellij):
   • if a matching config exists in this repo, each file in your current ~/.config/<tool> is backed up individually, then replaced in-place (safe to run while a desktop session is live — the directory is never deleted).
6. Installs starship at ~/.config/starship.toml, the wallhaven theme background into ~/.config/omarchy/themes/wallhaven/, and the custom About screen launcher to ~/.local/bin/omarchy-launch-about.
7. Backs up and replaces dotfiles — ~/.zshrc and ~/.XCompose get the same backup-then-overwrite treatment.
8. Sets up the shell environment (Stage 4) — makes sure copying .zshrc actually results in a usable shell:
   • adds zsh to /etc/shells if missing,
   • sets your login shell to zsh only if it isn't already (never re-runs chsh unnecessarily; prints a clear message when it changes and reminds you that a new login session is needed),
   • recreates ~/.local/bin/env + env.fish if they're missing (uv-installer template — see About ~/.local/bin/env),
   • verifies every command .zshrc depends on resolves, warning about any that don't.
9. Prints the backup location so you always know exactly where your previous setup went.

Nothing is deleted without a backup first. Every overwrite is preceded by a copy (cp -a) into the timestamped backup folder. Configs are installed via per-file in-place replacement so a running desktop session never sees a missing or partially-written config directory.

---

🥾 What bootstrap.sh Actually Does

Click to expand

Bootstrap is for a brand-new machine that doesn't have this repo (or possibly git/yay) yet:

1. Verifies you're on Arch — checks for pacman, exits cleanly otherwise (no Arch, no dice).
2. Installs Git if missing.
3. Installs yay if missing — clones and builds it from the AUR via makepkg -si.
4. Clones or updates the repo — clones fresh to ~/dotfiles if it doesn't exist, or git pulls if it does.
5. Makes scripts executable — install.sh and everything in scripts/.
6. Hands off to install.sh to do the actual config installation described above.

In short: bootstrap.sh gets a bare Arch install to the point where install.sh can run — then runs it.

---

📂 Repository Structure

.
├── alacritty/
├── atuin/
├── btop/
├── doctor.sh       # read-only installation health check
├── fastfetch/
├── fish/
├── foot/
├── ghostty/
├── home/          # ~/.zshrc, ~/.XCompose
├── hypr/          # Hyprland Lua config (Quattro)
├── kitty/
├── lazydocker/
├── lazygit/
├── mise/
├── mpv/
├── nvim/
├── repair.sh      # safe, idempotent in-place repair
├── vscode/
├── omarchy/       # shell, bar plugin, theme, hooks, theme.name
├── bootstrap.sh   # one-shot installer for fresh machines
├── packages/       # pacman.txt, aur.txt
├── scripts/       # omarchy-launch-about, lib/shell-env.sh
├── starship/
├── tmux/
├── voxtype/
├── wallpapers/
├── yazi/
└── zellij/

---

🛠 Requirements

• Arch Linux
• Omarchy
• Zsh (installed and set as login shell automatically by install.sh / repair.sh — required for this setup to function)
• yay (auto-installed by bootstrap.sh if missing)
• Git

---

🔄 Backups & Rollback

Every run of install.sh creates a fresh timestamped snapshot before touching anything:

~/.dotfiles-backup/20260701-143022/

To roll back a specific config manually:

cp -a ~/.dotfiles-backup/<timestamp>/.config/<tool> ~/.config/

📜 License

MIT License

built in the terminal, for the terminal