My Dot-Files

Table of Contents

• Summary
  • Repository Structure
  • Dot-files
  • User Scripts (bin/)
  • System / Admin Scripts (system-scripts/)
  • Repository Tooling (tools/)
• Shell Functions
  • Print
  • Shell Functions
  • Predicates
  • Queries
  • Arrays
  • Command
  • Math
  • Internet
  • Multimedia
• Appendix

Summary

My core configuration (dot) files, shell functions and utility scripts.

Repository Structure

dotfiles/        Actual dotfiles symlinked to $HOME (zsh, bash, vim, X11, etc.)
bin/             User utility scripts (added to PATH via ~/bin/)
system-scripts/  System/admin scripts (some require root)
lib/             Shared shell libraries (commons.sh)
tools/           Repo tooling: link.sh, fix-modelines.py, etc.
docs/            Documentation and TODO
_archive/        Archived scripts pending review (not in PATH)

• ZSH is the leading shell.

• Bash configs exist for rare cases in which zsh is not available, they are not regularly maintained and usually outdated (consolidation is however a backlog topic).

• Portability is a core goal: the dotfiles/ + bin/ + lib/ + tools/link.sh approach is intentionally dependency-free and should work without additional packages or root access.

• Restricted-host support matters: basic setup should still be usable on systems with only bash available (no zsh, no extra tooling).

• If not clearly ZSH related, all alias, function, etc. files should be Bash compatible (but not always POSIX compliant).

• All files use the " \{\{\{( .*)?$" (or {{{ }}} in short) folding comment pattern (use e.g. emacs, VS Code, eclipse)

ℹ️	See docs/TODO.adoc for the full task/improvement list.

Dot-files

File / Folder	App	Description
dotfiles/.zshenv	ZSH	Common ZSH login shell environment (variables).
dotfiles/.zlogout	ZSH	Common ZSH logout cleanup
dotfiles/.zshrc	ZSH	Common ZSH config
dotfiles/.zsh.d/zshrc-freebsd.zsh dotfiles/.zsh.d/zshrc-motoko.zsh dotfiles/.zsh.d/zshrc-puppet.zsh dotfiles/.zsh.d/zshrc-saito.zsh dotfiles/.zsh.d/zshrc-11001001_org.zsh	ZSH	OS, distribution, and/or host specific ZSH configs.
dotfiles/.zsh.d/aliases.zsh	SH	Common aliases
dotfiles/.zsh.d/aliases-freebsd.zsh dotfiles/.zsh.d/aliases-linux.zsh dotfiles/.zsh.d/aliases-linux_wsl.zsh	SH	OS, distribution, and/or host specific aliases.
dotfiles/.zsh.d/functions/functions.zsh	SH	Common shell functions.
dotfiles/.bashrc	Bash	Common Bash config (rarely maintained).
dotfiles/.xsession	X, Wayland	Used by the display manager. Loads .profile and .xinitrc.
dotfiles/.xinitrc	X, Wayland	Loaded from inside .xsession or when starting xinit.
dotfiles/.xsession.d/common dotfiles/.xsession.d/default dotfiles/.xsession.d/saito	X, Wayland	Common, default and host specific xsession initialization scripts loaded from inside .xinitrc. The common script is always loaded, the host specific script .xsession.d/{hostname} is loaded if existing, else the fallback default is loaded.
dotfiles/.Xresources dotfiles/.Xresources.d/saito	X, Wayland	Common and host specific X Resources. The .Xresources file is loaded from inside .xsession.d/common. If a host specific .Xresources.d/{hostname} exists, it is merged into the common resources.
dotfiles/.imwheelrc	IMWheel	General and app specific mouse button/wheel mappings.
dotfiles/.vimrc	VIM	VIM configuration
dotfiles/.config/mpv/config dotfiles/.config/mpv/input.conf	mpv	MPV configuration and key bindings.
dotfiles/.mplayer/config dotfiles/.mplayer/input.conf	MPlayer	Old MPlayer configuration and key bindings (switched to mpv).

Host / OS specific zsh files

Custom host / OS specific ZSH configurations, aliases, functions, xsessions and xresources can be created and they are dynamically loaded in case of a match. This provides a convenient way to enrich the environment in case of a specific host / os without messing around with the core files.

This is the sequence in which zshrc’s, aliases and functions are loaded from within .zshrc:

 # top of zshrc (always loaded)
 .zsh.d/functions.zsh
 .zsh.d/aliases.zsh

 # bottom of zshrc (loaded in given sequence if host/os matches)
 .zsh.d/functions-${OS}.zsh
 .zsh.d/functions-${HOST}.zsh
 .zsh.d/functions-${HOST}-${OS}.zsh
 .zsh.d/functions-${HOST}-${OS}_wsl.zsh

 .zsh.d/aliases-${OS}.zsh
 .zsh.d/aliases-${HOST}.zsh
 .zsh.d/aliases-${HOST}-${OS}.zsh
 .zsh.d/aliases-${HOST}-${OS}_wsl.zsh

 .zsh.d/zshrc-${OS}.zsh
 .zsh.d/zshrc-${HOST}.zsh
 .zsh.d/zshrc-${HOST}-${OS}.zsh
 .zsh.d/zshrc-${HOST}-${OS}_wsl.zsh

The special suffix _wsl is used on Windows Subsystem Linux, this allows the -linux files to be loaded in addition to (followed by) a WSL specific -linux_wsl file.

Some examples can be seen in the Dot-files list above.

User Scripts (bin/)

File	Description
bin/media-keys	Script to be used from within X (e.g. media key mappings) for media player control (play/pause, prev/next song) and pulse audio volume control (+/-5% and toggle mute) optionally showing an OSD.
bin/apt-update	Quietly update apt package indexes and store a timestamp.
bin/exif-move-to-rating-dirs	Organize image files into a directory hierarchy based on EXIF star ratings (0-5) and color labels. Features smart caching, directory mapping with regex patterns, and move/copy modes. See bin/exif-move-to-rating-dirs.d/README.adoc for full documentation.
bin/smfetch	Fetch RTMP and direct HTTP media links from broadcaster pages using wget and rtmpdump.
bin/aria2c-d	aria2c downloader wrapper.
bin/diff-ini	Diff INI files.
bin/ff-copy	Firefox copy utility.
bin/ff-copy-mpv-bookmarks	Copy MPV bookmarks from Firefox.
bin/getbyext	Get files by extension from a given URL using wget.
bin/gif-cycle	GIF frame cycling utility.
bin/gif-delay	GIF frame delay inspector/modifier.
bin/git-fix-chmod	Fix Git file permissions (chmod).
bin/image-concat	Concatenate images.
bin/mpv-find	Find media files and play with mpv.
bin/rsync-parallel-backup	Parallel rsync backup.
bin/rsynclt	rsync with limited throughput.
bin/wget-p	Parallel file fetching wrapper for wget.
bin/while-read	Execute a command for each line read from stdin.
bin/xsuspend	Suspend the X session.

System / Admin Scripts (system-scripts/)

Scripts intended for system administrators or privileged operations (some require root).

File	Description
system-scripts/backup	System backup script with exclusion list; supports full and incremental backups.
system-scripts/bedtime-shutdown/bedtime-shutdown.sh	Force system shutdown at a configured bedtime with grace periods, desktop notifications, and emergency overrides. See system-scripts/bedtime-shutdown/README.adoc for full documentation.
system-scripts/dbbackup	Backup script for MySQL and PostgreSQL databases.
system-scripts/fail2ban-summary-mail	Send a weekly Fail2Ban summary email from recent log data (intended for cron).
system-scripts/nextcloud-maintenance	Run routine Nextcloud maintenance tasks (DB indices, repair, integrity checks, app updates). Intended for cron with cronic.
system-scripts/openvpn-client-cfg	Generate OpenVPN client configuration bundles from server PKI assets; manage static IPs, CCD, and certificate revocation.

Repository Tooling (tools/)

File	Description
tools/link.sh	Symlink all files in dotfiles/ to the user’s home directory. Missing directories are created in the process. Existing files that would be overwritten are moved to a backup location.
tools/permissions.sh	Update dotfile repo file permissions.
tools/fix-modelines.py	Normalize and deduplicate editor modelines (Emacs, Vim, VS Code, ShellCheck) across shell scripts.
tools/fix-style.sh	Apply style fixes to shell scripts.
README.adoc	This file.

Shell Functions

Some of the shell functions contained in .zsh.d/functions.zsh will be described in the following chapters.

Print

Function	Description
p_usg USAGE..	Print a Usage text.
p_msg MSG..	Print an info message.
p_war MSG..	Print a warning message.
p_err MSG..	Print an error message (stderr).
p_dbg DBG_LVL SHOW_AT_LVL MSG..	Print a debug msg if the given debug level is reached. A global debug level can be set via the DBG_LVL variable, in this case p_dbg will use the higher level max(arg-level, global-level), meaning whichever is larger. As a result the global level can be used to globally raise, but never to lower the locally used debug level. So simply set the DBG_LVL argument to 0 if only the global level should be considered.
p_yes p_no	Print yes in green and no in red color.
py_print [-i import] PY_CODE..	Route the given code through the python3 print function. Use -i to import additional packages.

Colors

Function	Description
p_colortable	Print 256 ansi color table.
tputs STYLE..	Execute multiple tput commands in sequence. Example:
tp STYLE..	Set one or more tput colors and text effects by (short) name. All values are looked up from a map (no need to run an external process).

Shell Functions

Function	Description
func_name	Returns the current function’s name: ${FUNCNAME[0]} on bash, ${funcstack[1]} on zsh.
func_caller	Returns the function’s caller name (if caller is a function): ${FUNCNAME[1]} on bash, ${funcstack[2]} on zsh.

Predicates

Function	Description
is_zsh	true if zsh session, else: false
is_bash	true if bash session, else: false
is_su	true if root (super user) session, else: false
is_sudo	true if in sudo mode, else: false
is_sudo_cached	true if sudo has cached credentials, else: false
is_ssh	true if ssh session, else: false
is_int NUMBER..	true if all given numbers are integers (only digits), else: false. Ignores leading/trailing spaces, accepts leading +/- sign.
is_decimal NUMBER..	true if all given numbers are decimals (only digits, MUST contain decimal separator '.'), else: false. Ignores leading/trailing spaces, accepts leading +/- sign.
is_number NUMBER..	true if all given numbers a either integers or decimals (only digits, CAN contain decimal separator '.'), else: false. Ignores leading/trailing spaces, accepts leading +/- sign.
is_positive NUMBER..	true if all numbers do NOT start with a -, else: false. Ignores leading/trailing spaces. Note: This doesn’t check if the arguments are numbers (it simply checks for a leading -, should always be used in combination with is_int/decimal/number).

Queries

Function	Description
q_yesno QUESTION	Print the QUESTION and asks for (y)es/(n)o input. Returns true if answer is yes, else: false.
q_overwrite FILE	Checks if the given file exists, if so asks wether to overwrite it via (y)es/(n)o input. Returns true only if FILE exists AND if answer is yes, else: false.

Arrays

Function	Description
join_by DELIMITER ARRAY..	Join array / arguments using the given delimiter. On ZSH consider using ${(j:del:)array}. Note that on zsh the same can be achived via ${(j:.:)ip}.

Command

Function	Description
cmd_delay DELAY COMMAND..	Execute a command with a delay (using sleep format, e.g. 3m for 3 minutes). Sleep timer example: cmd_delay 45m systemctl suspend.
while_read COMMAND..	Monitor input (read lines) and execute command in foreground using input as command argument. Example: while_read wget to download all entered urls.
while_read_bg COMMAND..	Monitor input (read lines) and execute command in background (job) using input as command argument. Example: while_read_bg wget to download all entered urls.
while_read_xclip [OPTION..] COMMAND..	Monitor X clipboard and execute command using clipboard content as command argument. Example: while_read_xclip -b -m '^https?://.*' tee -a links.txt "<<<'{}'" | wget -nv -c -i - to append all http(s) URLs read vom clipboard to a file named links.txt and download them using wget.

Math

Function	Description
calc EXPR..	A simple wrapper for dc. Set the decimal scale using the -s option (default: 0).
py_calc PY_CODE..	Routes PY_CODE through python3’s print function with from math import *. Apart from this additional import it’s basically the same as py_print so this is also possible (even without the math. prefix):

Internet

Function	Description
ytp URL..	Download media files using youtube-dl and aria2c (4 concurrent downloads, 4 threads per host) using the same output file names provide by youtube-dl using the following pattern: %(title)s [%(id)s].%(ext)s. Note that this is basically the same as the alias yt but using aria2c for parallel download instead of the integrated, single threaded downloader. When multiple formats are available, all yt* commands will favor free codecs starting with the highest quality streams _(rough codec/format priority: vp9/opus/vp8/vorbis/webm/ogg/*).
ytap URL..	The same as ytp above, but downloads audio stream only preferably to a ogg(opus/vorbis) file. Note that this is basically the same as the alias yta but using aria2c for parallel download.

Multimedia

Function	Description
mpv_find DIR [OPTION..] [-a MPV-ARG..]	Find any media file (default: .avi,.mkv,.mp4,.webm, regex match can be changed) and play them using mpv. Allows sorting, fs tree recursion, list-only (stdout, no playback), 'resuming' (from a given index), and passing additional arguments to mpv. Example: mpv_find -r -s -R -a --no-resume-playback will play all videos in the current, and all subfolders, in random order, ignoring mpv’s remsue-playback function.
to_mp3 INFILE [BITRATE [OUTFILE]]	Convert the given INFILE to mp3 using ffmpeg (INFILE may be any media file containing an audio stream processable by ffmpeg). A bitrate of 160k and default output file name {infilename}-audio.mp3 ise used if no specific options are provided.
to_opus [-b BITRATE] INFILE [OPUSENC_ARG..]	Convert the given INFILE to opus using opusenc (infile may be any media file containing audio readable by opusenc). If no arguments are provided it uses the default opusenc vbr bitrate of "64kbps per mono stream, 96kbps per coupled pair". The output file is {infilename}.opus _(currently not changeable).
ff_concat OUTFILE INFILE..	Concatenates all INFILEs into OUTFILE using ffmpeg.
ff_crop INFILE CROP [OUTFILE]	Crop INFILE video using the given ffmpeg crop format (e.g. 640:352:0:64) to the default outfil {infilename}_CROP.{infileext}. Requires imagemagick’s identify.

Images

Function	Description
gif_delay FILE	Returns all frame indexes of a gif FILE with their respective delays (speed). It is optionally possible to only list the delays --delay-only or to print only the (rounded) average 1/100 sec delay --average of all frames. In the --help examples are provided on how to change the speed of a gif file using imagemagick’s convert. Requires imagemagick’s identify.
image_concat FILE..	Concatenate images. TODO: Needs further improvement.
image_dimensions FILE..	Returns dimensions given images in format: {file-name}|{w}|{h}|{w}x{h}|{w*x}|{min(w,h)}|{max(w,h)} (width, height, pixels, shortest/longest edge, etc.). The delimiter | can be changed. Requires imagemagick’s identify.

Appendix

Icon pack by Icons8