scripts: add unnecessary descriptions

README.md

@@ -79,7 +79,7 @@ This feature is only enabled in Niri. Swww also manages wallpapers of the Hyprla
 
 ## Wallpaper & Colortheme
 
-The most suitable primary color (or so-called flavor) will be chosen from the [Catppuccin Mocha](https://catppuccin.com/palette/) palette and applied to various apps automatically after changing wallpaper. And also:
+The most suitable primary color (or so-called flavor) will be chosen from the [Catppuccin Mocha](https://catppuccin.com/palette/) palette and applied to various apps automatically after changing wallpaper. See also:
 
 - [wallpaper-carousel](https://github.com/Uyanide/Wallpaper_Carousel) to select wallpaper, which implements an Image Carousel with Qt Widgets.
 - [backgrounds collection](https://github.com/Uyanide/backgrounds) for personal use.
@@ -106,33 +106,3 @@ including:
 - Sour Gummy
 - Noto Sans
 - ...
-
-## Some of the Scripts
-
-> [!TIP]
->
-> Most scripts are placed in the [config/scripts](https://github.com/Uyanide/dotfiles/tree/main/config/scripts) folder.
-
-- `config-switch`
-
-  updats configurations of several apps according to the current (or given as parameter) desktop environment. e.g. Niri currently doesn't support blurred windows, so terminal emulators such as Kitty and Ghostty could reduce transparency for better appearences.
-
-- `change-colortheme`
-
-  changes the colortheme of a number of pre-configured apps. This is done by calling certain scripts that are usually called `apply-color`.
-
-- `wallpaper-daemon` & `change-wallpaper`
-
-  provides wallpaper for both Hyprland and Niri (background and backdrop). It can also automatically set the wallpaper to a blurred version when there is a window in focus, however, this is currently only implemented in Niri.
-
-- `ssh-init`
-
-  ensures there is only one valid ssh-agent running at the same time. Useful when creating ssh-agent somewhere else than the login shell scripts or across sessions.
-
-- `screenshot-script`
-
-  takes a screenshot, and sends a notification asking whether to edit it by clicking on it. Works on both Hyprland and Niri.
-
-- `record-script`
-
-  records the screen based on wf-recorder and using av1_nvenc as the video encoder. The default codec parameters will generate a fairly large video file (80 Mbps), a later transcoding is definitly required in such case.

config-stow

@@ -92,14 +92,14 @@ def main():
 
     if args.package == "hyprland":
         try:
-            switch("Hypr")
+            switch("Hyprland")  # "Hyprland" as defined by hyprland
             _log("INFO", "Switched session to hyprland.")
         except subprocess.CalledProcessError as e:
             _log("ERROR", f"Failed to switch session: {e}")
 
     elif args.package == "niri":
         try:
-            switch("niri")
+            switch("niri")  # "niri" as defined by niri
             _log("INFO", "Switched session to niri.")
         except subprocess.CalledProcessError as e:
             _log("ERROR", f"Failed to switch session: {e}")

config/ghostty/.config/.alt/ghostty-niri/ghostty-default

@@ -1 +0,0 @@
-.alt/ghostty-default

config/ghostty/.config/.alt/ghostty-niri/ghostty-niri

@@ -1 +0,0 @@
-.alt/ghostty-niri

config/kitty/.config/.alt/kitty-niri/kitty-default

@@ -1 +0,0 @@
-.alt/kitty-default

config/kitty/.config/.alt/kitty-niri/kitty-niri

@@ -1 +0,0 @@
-.alt/kitty-niri

config/scripts/.local/scripts/change-colortheme

@@ -1,5 +1,12 @@
 #!/usr/bin/env python3
 
+# Description:
+#   Change color theme for various applications based on an image, color, or user selection.
+#   This is done by running application-specific scripts located in the config directory.
+#
+# Requirements:
+#   - colorthief (python3 package) # too lazy to implement color extraction myself :D
+
 import os
 import sys
 from pathlib import Path

config/scripts/.local/scripts/change-wallpaper

@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 
-# Required tools:
+# Description:
+#   Change the desktop wallpaper and generate a blurred version.
+#
+# Requirs:
 # - zenity (for file selection dialog)
 # - imagemagick (for image processing)
 # - swww (wallpaper daemon)

config/scripts/.local/scripts/config-switch

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Updates configurations of several apps according to the current (or given as parameter) desktop environment.
+
 if [ -z "$1" ]; then
     desktop="$XDG_CURRENT_DESKTOP"
 else

config/scripts/.local/scripts/fetch-weather

@@ -1,5 +1,14 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Fetch and cache current weather data using OpenWeather API for use in eww widgets.
+#
+# Requirements:
+# - Environment variables:
+#   - OPENWEATHER_API_KEY
+#   - OPENWEATHER_LAT
+#   - OPENWEATHER_LON
+
 ## Collect data
 cache_dir="$HOME/.cache/eww/weather"
 cache_weather_stat=${cache_dir}/weather-stat

config/scripts/.local/scripts/hypr-sdrbrightness

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 
-# new_brightness="$1"
-# [ -z "$1" ] && new_brightness=1
-# sed -i "/sdrbrightness/c\    sdrbrightness = $new_brightness" <filename>
+# Description:
+#   Adjust the SDR brightness setting in Hyprland's monitor configuration file.
+#   Useful for adjusting brightness when HDR is enabled.
 
 import sys
 import os

config/scripts/.local/scripts/issu

@@ -1,5 +1,9 @@
 #!/bin/sh
 
+# Description:
+#   Detect if the current user is a root or sudo user. Exits with code 0 if true, 1 otherwise.
+#   This script is required by some other scripts such as `smb-mount` and `wsl-mount`.
+
 if [ "$(id -u)" -eq 0 ]; then
     exit 0
 fi

config/scripts/.local/scripts/lyrics-widgets

@@ -1,5 +1,14 @@
 #!/bin/sh
 
+# Description:
+#   Toggle the visibility of lyrics widgets in eww.
+#   - Ensure only one of the two widgets (lyrics or lyrics-single) is open at a time.
+#   - Cycle through the following states:
+#     1. Both widgets closed -> Open 'lyrics'
+#     2. 'lyrics' open -> Close 'lyrics' and open 'lyrics-single' (if waybar is running)
+#     3. 'lyrics-single' open -> Close 'lyrics-single'
+#     4. Both widgets open -> Close both
+
 LYRICS=$(eww active-windows | grep "lyrics:")
 LYRICS_SINGLE=$(eww active-windows | grep "lyrics-single:")
 

config/scripts/.local/scripts/mpv-hdr

@@ -1,5 +1,8 @@
 #!/bin/sh
 
+# Description:
+#   Launch mpv with HDR support enabled
+
 export ENABLE_HDR_WSI=1
 
 mpv --vo=gpu-next --target-colorspace-hint --gpu-api=vulkan --gpu-context=waylandvk "$@"

config/scripts/.local/scripts/mpv-sm

@@ -1,5 +1,8 @@
 #!/bin/sh
 
+# Description:
+#   Launch mpv with smooth motion interpolation enabled
+
 export NVPRESENT_ENABLE_SMOOTH_MOTION=1
 
 mpv --vo=gpu-next --gpu-api=vulkan --gpu-context=waylandvk --video-sync=audio "$@"

config/scripts/.local/scripts/pacman-reflector

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Quick snippet of reflector.
+
 [ -z "$COUNTRY" ] && COUNTRY="Germany"
 
 sudo cp -f /etc/pacman.d/mirrorlist /etc/pacman.d/mirrorlist.bak || exit 1

config/scripts/.local/scripts/record-script

@@ -1,5 +1,13 @@
 #!/usr/bin/env bash
-# https://github.com/end-4/dots-hyprland/blob/main/.config/ags/scripts/record-script.sh
+
+# Description:
+#   Script to record screen.
+#   Inspired by https://github.com/end-4/dots-hyprland
+#
+# Requirements:
+# - wf-recorder
+# - slurp
+
 
 [ -z "$codec" ] && codec="av1_nvenc"
 [ -z "$pixel_format" ] && pixel_format="p010le"

config/scripts/.local/scripts/rofi-cliphist

@@ -1,5 +1,7 @@
 #!/bin/sh
 
+# Description:
+#   Quick snippet for cliphist + rofi + wl-copy
 
 cliphist list | rofi -dmenu -config ~/.config/rofi/dmenu.rasi -display-columns 2 -i | \
     cliphist decode | wl-copy

config/scripts/.local/scripts/rofi-emoji

@@ -1,5 +1,8 @@
 #!/bin/bash
-# https://github.com/end-4/dots-hyprland/blob/main/.local/bin/fuzzel-emoji
+
+# Description:
+#   Quick snippet for rofi + emoji + wl-copy
+#   Source: https://github.com/end-4/dots-hyprland
 
 sed '1,/^### DATA ###$/d' $0 | rofi -dmenu -config ~/.config/rofi/dmenu.rasi -i | cut -d ' ' -f 1 | tr -d '\n' | wl-copy
 exit

config/scripts/.local/scripts/screenshot-script

@@ -1,5 +1,15 @@
 #!/usr/bin/env python3
 
+# Description:
+#   A screenshot utility script for Hyprland and Niri desktop environments.
+#   Takes screenshots (full, area, window) and provides an option to edit them immediately
+#
+# Requirements:
+# - hyprshot (for Hyprland)
+# - - (niri has screenshot functionality built-in)
+# - gradia (for editing)
+# - glib bindings for python
+
 import argparse
 import subprocess
 import time

config/scripts/.local/scripts/smb-mount

@@ -1,5 +1,12 @@
 #!/bin/sh
 
+# Description:
+#   Quick snippet for smb mounting via cifs
+#
+# Requirements:
+# - cifs-utils
+# - ./issu
+
 issu && {
     echo "Do not run this script in sudo mode."
     exit 1

config/scripts/.local/scripts/smb-unmount

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# Description:
+#   Quick snippet for smb unmounting
+
 [ -z "$SMB_MOUNT_POINT" ] && SMB_MOUNT_POINT="/mnt/smb"
 
 if sudo umount "$SMB_MOUNT_POINT" && sudo rmdir "$SMB_MOUNT_POINT"; then

config/scripts/.local/scripts/ssh-init

@@ -1,9 +1,13 @@
 #!/bin/sh
 # shellcheck disable=SC1091,SC1090
 
-# `eval "$(ssh-init)"` to set up environment
-# variables for ssh agent in the current shell.
-# TIPS: `bass "$(ssh-init)"` case in fish
+# Description:
+#   Initialize ssh-agent and set up environment variables for use in the current shell.
+#
+# Usage:
+#   `eval "$(ssh-init)"` to set up environment
+#   variables for ssh agent in the current shell.
+#   TIPS: `bass "$(ssh-init)"` case in fish
 
 mkdir -p "$HOME/.local/state"
 agent_file="$HOME/.local/state/ssh-agent"

config/scripts/.local/scripts/wallpaper-daemon

@@ -1,5 +1,14 @@
 #!/usr/bin/env python3
 
+# Description:
+#   A wallpaper daemon script that integrates with swww and Niri/Hyprland to
+#   automatically switch between normal and blurred wallpapers based on window focus.
+#
+# Requirements:
+# - swww (or awww case you are from the future)
+# - niri/hyprland (obviously)
+# - watchdog (python3 package)
+
 import socket
 import json
 import subprocess

config/scripts/.local/scripts/waybar-toggle

@@ -1,5 +1,13 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Script to toggle Waybar (start/stop/restart).
+#   Also manages the lyrics widget state.
+#
+# Requirements:
+# - waybar
+# - eww (for lyrics widget)
+
 lyrics_widget_closed=0
 
 function close() {

config/scripts/.local/scripts/waydroid-reload

@@ -1,15 +1,16 @@
 #!/usr/bin/env bash
 
-function checkReturn {
-    echo "Executing: $*"
-    if ! "$@"; then
-        echo "Error runnning command"
-        exit 1
-    fi
-}
+# Description:
+#   Quick snippet to reload and restart Waydroid.
+#
+# Requirements:
+# - waydroid
+# - sudo privileges
 
-checkReturn waydroid session stop
-# checkReturn sudo waydroid upgrade # since I'm not using the default image
-checkReturn sudo waydroid init -f
-checkReturn sudo systemctl restart waydroid-container
-checkReturn waydroid show-full-ui
+set -e
+
+waydroid session stop
+# sudo waydroid upgrade # since I'm not using the default image
+sudo waydroid init -f
+sudo systemctl restart waydroid-container
+waydroid show-full-ui

config/scripts/.local/scripts/workspace-new

@@ -1,5 +1,12 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Create and switch to a new workspace in Hyprland.
+#   e.g. if current workspaces are 1,2,4, this will create and switch to workspace 5.
+#
+# Requirements:
+# - hyprctl
+
 # get highest workspace ID
 max_id=$(hyprctl workspaces | grep '^workspace ID ' | awk '{print $3}' | sort -n | tail -1)
 

config/scripts/.local/scripts/wp-vol

@@ -1,5 +1,13 @@
 #!/bin/sh
 
+# Description:
+#   Show current volume level with notification.
+#   Made for mako, and is one of mako's official examples.
+#
+# Requirements:
+# - wpctl
+# - notify-send
+
 # Get the volume level and convert it to a percentage
 volume=$(wpctl get-volume @DEFAULT_AUDIO_SINK@)
 volume=$(echo "$volume" | awk '{print $2}')

config/scripts/.local/scripts/wsl-mount

@@ -1,5 +1,17 @@
 #!/bin/sh
 
+# Description:
+#   Mount a WSL VHDX file to a specified mount point using guestmount.
+#
+# Requirements:
+# - libguestfs-tools
+# - sudo privileges
+#
+# Memo:
+# - set `LIBGUESTFS_DEBUG=1 LIBGUESTFS_TRACE=1` to show details when guestmount fails.
+# - A common issue is that the VHDX file has logs that needs to be "replayed".
+#   This can be done using `qemu-img check -r all <VHDX_PATH>`
+
 issu && {
     echo "Do not run this script in sudo mode."
     exit 1

config/scripts/.local/scripts/wsl-unmount

@@ -1,5 +1,8 @@
 #!/bin/sh
 
+# Description:
+#   Quick snippet for unmounting WSL filesystems and removing the mount point.
+
 [ -z "$1" ] && mount_point="/mnt/wsl" || mount_point="$1"
 
 sudo umount "$mount_point" || {

config/scripts/.local/scripts/xdph-nuclear

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+
+# Description:
+#   Restart xdg-desktop-portal and xdg-desktop-portal-hyprland to fix screen sharing issues.
+#   From hyprland documentation.
+
 sleep 1
 killall -e xdg-desktop-portal-hyprland
 killall -e xdg-desktop-portal-wlr

config/scripts/.local/snippets/apply-color-helper

@@ -1,3 +1,9 @@
+# Description:
+#   Helper script to apply color schemes.
+#   - Parse and validate parameters.
+#   - Provide useful aliases and functions.
+#   Should be sourced, not executed directly.
+
 [ "$(basename "$0")" = "apply-color-helper" ] && {
      echo "This script is meant to be sourced, not executed directly."
      exit 1
@@ -10,6 +16,17 @@ colorName="$2"
 [ -z "$3" ] && exit 1
 colorHex="$3"
 
+# remove leading '#' if present
+if [[ $colorHex == \#* ]]; then
+    colorHex="${colorHex#\#}"
+fi
+
+# check if hex
+if ! [[ $colorHex =~ ^[0-9A-Fa-f]{6}$ ]]; then
+    log_error "Invalid color hex: $colorHex"
+    exit 1
+fi
+
 function log_error {
     printf "\033[0;31mError:\033[0m $1\n" >&2
 }
@@ -29,18 +46,6 @@ function color_ansi {
     printf "\033[38;2;%d;%d;%dm" $r $g $b
 }
 
-
-# remove leading '#' if present
-if [[ $colorHex == \#* ]]; then
-    colorHex="${colorHex#\#}"
-fi
-
-# check if hex
-if ! [[ $colorHex =~ ^[0-9A-Fa-f]{6}$ ]]; then
-    log_error "Invalid color hex: $colorHex"
-    exit 1
-fi
-
 function log_success {
     log_info "Applied palette \033[1;34m${palette}\033[0m with primary color $(color_ansi $colorHex)${colorName} (#${colorHex})\033[0m to \033[1;34m$1\033[0m"
 }

config/scripts/.local/snippets/set_display

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Select which GPU to use for rendering for Hyprland and Niri.
+
 # AMD -> Nvidia -> Intel
 prefer_order=(amd nvidia intel)
 

config/wlogout/.config/.alt/wlogout-niri/wlogout-default

@@ -1 +0,0 @@
-.alt/wlogout-default

config/wlogout/.config/.alt/wlogout-niri/wlogout-niri

@@ -1 +0,0 @@
-.alt/wlogout-niri