Usage

These dotfiles are managed with GNU stow, so you'll need it installed. Python 3.11+ is required for the installer script.

Basic Installation

Clone the repository and run the installer:

./install install              # Install all packages
./install install git zsh      # Install specific packages
./install install --tag cli    # Install all CLI packages

Commands

Command	Description
install	Install packages
reinstall	Reinstall packages (force override)
uninstall	Uninstall packages
check	Check installation status and conflicts
list	List all packages
list-tags	List all available tags
status	Show installation status of all packages

Tag-based Management

Packages can be managed using tags for easy grouping:

./install install --tag shell                 # Install all shell packages
./install install --tag x11 --tag gui         # Install packages matching ANY tag
./install list --tag x11 --tag wayland --and  # Packages with BOTH tags
./install uninstall --tag wayland             # Uninstall all Wayland packages

Cross-Platform Support

Packages are tagged with supported platforms. By default, only packages compatible with your OS are installed:

./install install              # Only installs packages for current OS
./install list --platform      # Show platform info for all packages
./install --os macos list      # Simulate macOS (for testing)
./install --os macos status    # See what's available on macOS

Flag	Description
--os	Target OS (linux, macos, windows)
--arch	Target architecture (x86_64, arm64)
--platform	Show OS/arch info in list output
--all, -a	Show all packages including unavailable ones
--include-unavailable	Install even if platform doesn't match

Package Metadata

Each package has a .package.toml file with metadata:

enabled = true  # set false to skip package
description = "example description"
tags = ["tag1", "tag2"]
os = ["linux", "macos"]  # supported platforms (empty = all)
arch = []  # architecture restrictions (empty = all)
condition = "<shell command>"

Components

• Desktop:

  • bspwm: A tiling window manager based on binary space partitioning
  • dunst: Lightweight notification daemon for X11
  • mako: Lightweight notification daemon for Wayland
  • picom: A lightweight compositor for X11
  • polybar: A fast and easy-to-use status bar
  • sxhkd: Simple X hotkey daemon
  • swww: Efficient animated wallpaper daemon for wayland
  • swaybg: Wallpaper tool for Wayland compositors
  • xwallpaper: Wallpaper setting utility for X11
  • feh: Image viewer and wallpaper setter

• Shell:

  • zsh: The Z Shell
  • bash: The Bourne Again SHell

• Applications:

  • GUI:
    • dmenu: Dynamic menu for X11
    • fastfetch: Fast system information tool
    • imv: Image viewer for X11/Wayland
    • kitty: Fast, feature-rich, GPU-based terminal emulator
    • mpv: Free and open source media player
    • pqiv: Powerful image viewer with minimal UI
    • thunar: Modern file manager for Xfce
    • zathura: Document viewer with vim-like interface
  • CLI:
    • bandwhich: Network utilization monitor
    • bat: A cat clone with syntax highlighting
    • beets: Music library manager and MusicBrainz tagger
    • bottom: Graphical process/system monitor
    • brightnessctl: Backlight and LED control
    • cava: Console-based audio visualizer
    • delta: A syntax-highlighting pager for git
    • eza: Modern replacement for ls
    • fd: Simple, fast and user-friendly alternative to find
    • fzf: Command-line fuzzy finder
    • gh: GitHub's official command line tool
    • glow: Terminal markdown viewer
    • handlr: A better xdg-utils implementation with regex support
    • hexyl: Command-line hex viewer
    • hub: Extension to command-line git
    • hyperfine: Command-line benchmarking tool
    • jq: Command-line JSON processor
    • maim: Screenshot utility for X11
    • mimeo: Open files by MIME-type and handle associated applications
    • mmv: Mass rename utility
    • mopidy: Extensible music server
    • navi: Interactive command-line cheatsheet
    • rmpc: Rusty Music Player Client - a modern MPD client
    • neovim: Hyperextensible Vim-based text editor
    • newsboat: Terminal RSS/Atom feed reader
    • pipewire: Low-latency audio/video router and processor
    • playerctl: MPRIS media player controller
    • ripgrep: Fast grep alternative
    • slop: Select Operation - region selector for X11
    • surfraw: CLI to search engines
    • tealdeer: A fast tldr client in Rust
    • tmux: Terminal multiplexer
    • trash-cli: CLI interface to FreeDesktop.org trash
    • udiskie: Automounter for removable media
    • ueberzug: X11 image display for terminals
    • vivid: LS_COLORS generator
    • xdotool: Command-line X11 automation tool
    • xh: Friendly and fast HTTP tool
    • xsecurelock: X11 screen lock utility
    • yq: YAML processor
    • yt-dlp: Command-line program to download videos

• Theming:

  • oomox: Theme generator for GTK and icons
  • papirus-icon-theme: SVG icon theme base
  • GTK/Qt Themes:
    • bnw: Custom black and white theme generated with oomox
  • Icon Themes:
    • bnw: Custom monochrome variant of Papirus
  • Cursor Theme:
    • Bibata: Modern material-based cursor theme
  • Supported Environments:
    • GTK 2.0/3.0/4.0: Complete theme support
    • Qt 5/6: Theme integration via qt5ct and qt6ct

Keybinding layout

All the global keybindings use the Super/Win key as the main modifier. You can use these layout diagrams to familiarize yourself with the key bindings, or you can customize them to fit your liking!

Tiling WM keybindings

Screenshots

• Default desktop - clean

  (to be added)

• Default desktop - floating window with alternate bar

  (to be added)

• Default desktop - busy

  (to be added)

• Menu interaction

  (to be added)

• Sample GTK application (file manager)

  (to be added)