💻 Aman's Dotfiles

A production-grade, cross-platform collection of dotfiles and environment configurations. Built for speed, portability, and robust fallback handling across Debian/Ubuntu, macOS, Alpine, Windows (WSL/Git Bash), Android (Termux), and Ephemeral Containers (DevPod/Docker).

✨ Features

• Mise-First Architecture: Relegates native package managers (apt, brew) to basic lifelines, relying entirely on mise to dynamically provision exact versions of CLI tools (Neovim, Starship, Eza, FZF, Zoxide, Yazi, Bat, Node.js, Python, Terraform, kubectl, Helm) across every OS via environment-specific config.toml files.
• Corporate Proxy Immune: Features a custom Windows-to-Linux interop script (sync_certs) that automatically extracts Zscaler Root CAs from the Windows registry and injects them into the WSL trust store to prevent SSL handshake failures without disabling TLS verification globally.
• Zero-Touch & Interactive Bootstrapper: A single setup script orchestrates repository cloning, linking, and tool installation. Run it interactively via a CLI menu, or fully unattended using flags (--auto, --env=container). A piped-execution guard automatically applies --auto when stdin is not a tty (e.g., curl | bash), and both setup and install_tools run in strict mode to fail fast on bootstrap errors.
• The Ultimate Editor: A fully customized, transparent LazyVim setup featuring the Nordic theme, pre-configured for DevOps workflows (Terraform, Python, YAML, JSON).
• Smart Environment Detection: Uses a 3-tier detection system (Flags → Interactive Prompt → Wayland/X11 Heartbeat) to automatically decide whether to stow heavy GUI desktop apps (Kitty, Sway, Qutebrowser, Zathura) or keep the environment headless.
• Idempotent Stow Runway: Safely clears the runway for GNU Stow by detecting existing physical configurations and moving them to timestamped backup directories under ~/.local/state/dotfiles/backups/, keeping only the 5 most recent runs.
• Git Identity Switcher: The gtog shell function handles seamless switching between personal and work Git identities — including SSH key selection, remote URL mode (SSH vs. HTTPS), and credential routing — without leaving the terminal.
• Nord Everywhere: Unified Nord color palette applied consistently across Kitty, Sway WM, Tmux (via nord-tmux), Qutebrowser, Starship prompt, Neovim, Yazi, and Zathura.

---

� Repository Structure

~/.dotfiles/
├── setup                        # Bootstrap orchestrator (interactive + --auto/--env flags)
├── install_tools                # Universal tool installer (apt/brew/apk/pkg/winget + Mise)
├── link                         # Manual symlink fallback when GNU Stow is unavailable
├── tilingshell-settings.txt     # GNOME TilingShell extension config (dconf export)
├── debian-custom-keybindings.ini # 34 GNOME custom shortcuts (dconf export)
├── debian-wm-keybindings.ini    # GNOME window manager keybindings
├── etc-copy-paste-hang-sol/     # sysctl.conf fix for clipboard hang issues in WSL
│
├── bash/                        # .profile, .bashrc, .bash_aliases
├── code/                        # VS Code settings.json, keybindings.json, snippets/
├── fastfetch/                   # Fastfetch system info configuration
├── fonts/                       # JetBrainsMono Nerd Font + NotoColorEmoji TTFs
├── git/                         # .gitconfig (delta, SSH signing, work includeIf) + .ssh/config
├── kitty/                       # Kitty terminal - Nord theme, splits, custom kittens
├── mise/                        # Mise config.toml per environment (linux/container/windows/mac)
├── nvim/                        # LazyVim + Nordic theme, DevOps extras
├── qutebrowser/                 # config.py (JS-off-by-default, Nord theme) 
├── scripts/                     # 21 utility scripts (sync_certs, upgrade, cleanup, define, …)
├── starship/                    # starship.toml - Nord powerline prompt
├── sway/                        # Sway WM config (Nord, gaps, floating rules, wofi)
├── tmux/                        # .tmux.conf (C-s prefix, nord-tmux, Alt+hjkl panes)
├── windows-terminal/            # settings.json (copied, not symlinked)
├── yazi/                        # Yazi file manager config, theme, keymap, plugins
└── zathura/                     # zathurarc PDF viewer config

---

🧰 Tools Managed by Mise

Tool	Environment
Neovim, Starship, FZF, Zoxide, Eza, Bat, Yazi, Node.js, Python, usage, Topgrade	All (universal)
ripgrep, fd, Python 3.12	Linux
Terraform, kubectl, Helm, AWS CLI	Container/DevPod
Neovim, Eza, FZF (disabled — use winget)	Windows

---

🚀 Installation & Setup

Option 1: The Zero-Touch Bootstrapper (Recommended)

If you are on a fresh machine, VM, or DevContainer, you don't even need to clone the repository manually. Just run this single command.

It will securely download the setup engine, automatically clone the repo to ~/.dotfiles, install all mise toolchains, and link your configurations in one shot:

curl -sL https://raw.githubusercontent.com/Aman1337g/dotfiles/main/setup | bash

Automated / CI Mode:

To bypass the interactive GUI prompts (perfect for DevPod postCreateCommand hooks), pass the automation flags directly to the piped script:

curl -sL https://raw.githubusercontent.com/Aman1337g/dotfiles/main/setup | bash -s -- --auto --env=container

Option 2: Manual Installation

If you prefer to review the scripts and run the pipeline manually, follow this exact order. (Note: You must link your dotfiles before installing tools so Mise can read your config.toml).

1. Clone the Repository

git clone https://github.com/Aman1337g/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

2. Link the Configurations

# Standard Linux / macOS / WSL (Requires GNU Stow)
# Core (headless-safe):
stow bash git nvim tmux starship fastfetch mise scripts yazi zathura code fonts

# GUI extras (only on a machine with a display):
stow kitty sway qutebrowser

# Alternative: Windows Git Bash Fallback (No Stow Required)
./link

3. Install Core Tools & Dependencies Runs the universal installer to grab system lifelines (curl, git), sync corporate certificates (if on WSL), and trigger mise to build the polyglot toolchain. The installer now relies on proper certificate trust instead of any global insecure curl bypass, so bootstrap failures surface immediately if trust is not configured correctly.

./install_tools

For desktop Linux setups, install the optional GUI packages as part of the same step:

./install_tools --gui

4. Reload Your Shell

source ~/.profile && source ~/.bashrc

After reload:

z <dir>   # zoxide directory jump
yz        # launch Yazi in the current directory

Note on Windows Terminal: windows-terminal/settings.json is copied (not symlinked) by the link script to: %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json because UWP apps break symlinks on auto-save.

---

❓ FAQs (GNU Stow Guide)

Q1 - What does "stow --adopt" do?

The --adopt option in GNU Stow handles existing files in the target directory that would conflict with symlinks Stow is trying to create. Instead of failing or overwriting, it moves those files into the Stow package directory—effectively “adopting” them.

How it works

Scenario You already have ~/.bashrc, and you want Stow to manage your Bash config. Normally, Stow would refuse to overwrite it.

Using --adopt

When you run:

cd ~/.dotfiles
stow --adopt bash

Stow will:

1. Move ~/.bashrc → ~/.dotfiles/bash/.bashrc
2. Create a symlink: ~/.bashrc → ~/.dotfiles/bash/.bashrc

This preserves your existing config while bringing it under Stow management.

Q2 - If I run "stow --adopt bash", will my existing .bashrc overwrite my desired config?

Yes. stow --adopt moves the existing file into your package directory, replacing whatever is already there. So your current system config will overwrite your repo version.

You’ll need to manually merge or restore your preferred configuration afterward.

Suggested workflow

1. Back up your current config

cp ~/.bashrc ~/.bashrc.bak

2. Adopt existing file

cd ~/.dotfiles
stow --adopt bash

3. Restore or merge your desired config

cp ~/.bashrc.bak ~/.dotfiles/bash/.bashrc
rm ~/.bashrc.bak
stow -R bash

For more complex setups, consider using a diff/merge tool instead of overwriting.

Q3 - Why use "stow -R" if symlinks already reflect changes automatically?

You're right: if a symlink exists, editing the source file updates the target automatically. However, stow -R (restow) is useful in several situations:

When to use stow -R

1. Repository restructuring If you move files or directories, restowing updates the symlinks.

2. Fixing broken or missing symlinks Recreates links that were deleted or corrupted.

3. Adding new files Ensures all files in the package are properly linked.

4. Ensuring consistency Rebuilds symlinks based on the current repo state.

Command

cd ~/.dotfiles
stow -R bash

This removes existing symlinks and recreates them cleanly.

Q4 - What if I add a new file and run "stow" instead of "stow -R"?

Running stow bash (without -R) will still create symlinks for any new files.

Behavior comparison

• stow bash

  • Creates symlinks only for files that don’t already have them
  • Leaves existing symlinks untouched

• stow -R bash

  • Removes all symlinks for the package
  • Recreates them from scratch

Conclusion

• Use stow → when adding new files
• Use stow -R → when restructuring or fixing issues

In most cases, plain stow is sufficient.