From 02c46ebea76532e748e558ed2e5d1e217767bad6 Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Sun, 26 Jul 2026 03:47:25 -0400
Subject: [PATCH] docs(functions): merge manual-only examples and notes into
 headers

Folds the examples Section 5 carried but the headers did not into each
function's `# EXAMPLE`, and moves the three lines that only looked like
examples -- the two typo-abbreviation notes and rm's /usr/bin/rm fallback --
into `# NOTES`, the label already in use.

Also corrects gi's synopsis, which omitted -l, and documents yt-dlp's
--no-embed-thumbnail in `# ARGUMENTS`.
---
 functions/bd-pull.fish     | 1 +
 functions/cat.fish         | 1 +
 functions/cheat.fish       | 1 +
 functions/config-help.fish | 1 +
 functions/copy.fish        | 1 +
 functions/dng2avif.fish    | 1 +
 functions/du.fish          | 1 +
 functions/dusize.fish      | 1 +
 functions/edit.fish        | 2 ++
 functions/fish-deps.fish   | 3 +++
 functions/gi.fish          | 4 +++-
 functions/git-clean.fish   | 1 +
 functions/logs.fish        | 2 ++
 functions/ls.fish          | 2 ++
 functions/mkcd.fish        | 1 +
 functions/open-url.fish    | 3 +++
 functions/repo-open.fish   | 6 ++++++
 functions/rg.fish          | 2 ++
 functions/rm.fish          | 3 +++
 functions/spark.fish       | 1 +
 functions/y.fish           | 2 ++
 functions/yt-dlp.fish      | 1 +
 22 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/functions/bd-pull.fish b/functions/bd-pull.fish
index 7ccaa99..c634429 100644
--- a/functions/bd-pull.fish
+++ b/functions/bd-pull.fish
@@ -21,6 +21,7 @@
 #
 # EXAMPLE
 #   bd-pull myuser/myproject
+#   bd-pull rootiest/fish-config
 function bd-pull --description 'Pull new Gitea issues into local Beads and link them'
     if not set -q argv[1]; echo "Need repo owner/name"; return 1; end
     if not set -q GITEA_TOKEN; echo "\$GITEA_TOKEN not set"; return 1; end
diff --git a/functions/cat.fish b/functions/cat.fish
index e99e81b..6ce0bae 100644
--- a/functions/cat.fish
+++ b/functions/cat.fish
@@ -17,6 +17,7 @@
 #
 # EXAMPLE
 #   cat README.md
+#   cat ~/projects/myapp
 function cat --wraps='bat' --description 'Use bat for files, ls for directories, and raw cat for ANSI logs'
     # Opinionated guard (C1): fall back to bare command cat when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases
diff --git a/functions/cheat.fish b/functions/cheat.fish
index 3659f15..e13948c 100644
--- a/functions/cheat.fish
+++ b/functions/cheat.fish
@@ -17,6 +17,7 @@
 #
 # EXAMPLE
 #   cheat tar
+#   cheat git
 function cheat --wraps='cheat' --description 'alias cheat=cheat -c'
     if type -q cheat
         command cheat -c $argv
diff --git a/functions/config-help.fish b/functions/config-help.fish
index f1cdcf9..8daf406 100644
--- a/functions/config-help.fish
+++ b/functions/config-help.fish
@@ -42,6 +42,7 @@
 #   config-help --man
 #   config-help keys --man
 #   config-help --help
+#   config-help pkg --man
 #
 # NOTES
 #   The preferred invocation is `help config [...]` — this function is
diff --git a/functions/copy.fish b/functions/copy.fish
index ed593a1..e3ceb0e 100644
--- a/functions/copy.fish
+++ b/functions/copy.fish
@@ -17,6 +17,7 @@
 #
 # EXAMPLE
 #   copy ./mydir/ ~/backup
+#   copy ./mydir/ ~/backup    # copies mydir INTO backup, not backup/mydir/
 function copy
     set count (count $argv)
     if test "$count" = 2; and test -d "$argv[1]"
diff --git a/functions/dng2avif.fish b/functions/dng2avif.fish
index 4c90600..97d98b4 100644
--- a/functions/dng2avif.fish
+++ b/functions/dng2avif.fish
@@ -25,6 +25,7 @@
 #
 # EXAMPLE
 #   dng2avif photo.dng
+#   dng2avif -q 85 -s 5 -i shot.dng -o out.avif
 function dng2avif --description 'Convert DNG raw to 10-bit HDR AVIF'
     set -l options (fish_opt -s h -l help)
     set -a options (fish_opt -s i -l input -r)
diff --git a/functions/du.fish b/functions/du.fish
index e87a51b..0e0693c 100644
--- a/functions/du.fish
+++ b/functions/du.fish
@@ -20,6 +20,7 @@
 #
 # EXAMPLE
 #   du ~/Downloads
+#   du --disk
 function du --description 'Execute du'
     # Opinionated guard (C1): fall back to bare command du when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases
diff --git a/functions/dusize.fish b/functions/dusize.fish
index 1d12d7e..d188c2a 100644
--- a/functions/dusize.fish
+++ b/functions/dusize.fish
@@ -16,6 +16,7 @@
 #
 # EXAMPLE
 #   dusize ~/Downloads
+#   dusize ~/Videos
 function dusize --wraps='du' --description 'alias dusize=du'
     du -sh (test -n "$argv[1]"; and echo $argv[1]; or echo .)
 end
diff --git a/functions/edit.fish b/functions/edit.fish
index 5bb66c4..0fcd2c7 100644
--- a/functions/edit.fish
+++ b/functions/edit.fish
@@ -41,6 +41,8 @@
 #   edit --terminal --new todo.md
 #   edit --editor=code --clipboard
 #   edit --text="hello world"
+#   edit ~/.config/fish/config.fish
+#   edit --visual notes.txt
 function edit --description 'Open files in a terminal or GUI editor with fallbacks'
     set -l c_head (set_color --bold cyan)
     set -l c_cmd (set_color --bold white)
diff --git a/functions/fish-deps.fish b/functions/fish-deps.fish
index 34a4a97..0aac7d8 100644
--- a/functions/fish-deps.fish
+++ b/functions/fish-deps.fish
@@ -23,6 +23,9 @@
 #
 # EXAMPLE
 #   fish-deps sync
+#   fish-deps
+#   fish-deps install
+#   fish-deps update
 function fish-deps --description 'Manage fish shell dependencies'
     set -l subcmd $argv[1]
 
diff --git a/functions/gi.fish b/functions/gi.fish
index 98ca282..fefe20a 100644
--- a/functions/gi.fish
+++ b/functions/gi.fish
@@ -5,7 +5,7 @@
 #   04-git-and-version-control
 #
 # SYNOPSIS
-#   gi [-h] [-b] [-p] [-s] [targets...]
+#   gi [-h] [-b] [-p] [-s] [-l] [targets...]
 #
 # DESCRIPTION
 #   Generates .gitignore content by querying the gitignore.io API. Appends
@@ -27,6 +27,8 @@
 #
 # EXAMPLE
 #   gi python,venv
+#   gi -b -p
+#   gi -s node > .gitignore
 function gi --description 'Generate .gitignore files using the gitignore.io API'
     argparse h/help d/description l/list b/boilerplate p/prompt s/stdout -- $argv
     or return 1
diff --git a/functions/git-clean.fish b/functions/git-clean.fish
index 56718b9..98086eb 100644
--- a/functions/git-clean.fish
+++ b/functions/git-clean.fish
@@ -22,6 +22,7 @@
 #
 # EXAMPLE
 #   git-clean --force
+#   git-clean
 function git-clean --description 'Sync main, prune remotes, and delete orphaned branches'
     set -l options h/help f/force
     argparse $options -- $argv
diff --git a/functions/logs.fish b/functions/logs.fish
index c585392..b32ae91 100644
--- a/functions/logs.fish
+++ b/functions/logs.fish
@@ -21,6 +21,8 @@
 #
 # EXAMPLE
 #   logs -c paru
+#   logs
+#   logs -c scrollback
 function logs --description 'Browse terminal log files interactively with fzf'
     # Opinionated guard (C4): integrations disabled
     if not __fish_config_op_enabled __fish_config_op_integrations
diff --git a/functions/ls.fish b/functions/ls.fish
index f76ea5e..a094d4d 100644
--- a/functions/ls.fish
+++ b/functions/ls.fish
@@ -16,6 +16,8 @@
 #
 # EXAMPLE
 #   ls ~/projects
+#   ls
+#   ls -a ~/projects
 function ls --description 'List all files'
     # Opinionated guard (C1): fall back to bare command ls when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases
diff --git a/functions/mkcd.fish b/functions/mkcd.fish
index 2cffbee..b944419 100644
--- a/functions/mkcd.fish
+++ b/functions/mkcd.fish
@@ -24,6 +24,7 @@
 #
 # EXAMPLE
 #   mkcd ~/projects/myapp
+#   mkcd ~/projects/newapp/src
 function mkcd --description 'Create a directory (with parents) and cd into it'
     set -l c_head (set_color --bold cyan)
     set -l c_cmd  (set_color --bold white)
diff --git a/functions/open-url.fish b/functions/open-url.fish
index 2acf094..cb2969f 100644
--- a/functions/open-url.fish
+++ b/functions/open-url.fish
@@ -36,6 +36,9 @@
 # EXAMPLE
 #   open-url https://git.rootiest.dev/rootiest/fish-config
 #   open-url -v https://fish-config-docs.pages.dev/
+#
+# NOTES
+#   Typo abbreviation: url-open (expands to open-url on space/enter).
 function open-url --description 'Open a URL in the best available web browser'
     argparse h/help s/silent v/verbose -- $argv
     or return 1
diff --git a/functions/repo-open.fish b/functions/repo-open.fish
index b65d0dc..4952029 100644
--- a/functions/repo-open.fish
+++ b/functions/repo-open.fish
@@ -42,6 +42,12 @@
 #   repo-open              # open current branch (+ subdir) in browser
 #   repo-open --print      # just print the URL
 #   repo-open --root       # repo home page for the current branch
+#   repo-open
+#   repo-open --print
+#   repo-open --root
+#
+# NOTES
+#   Typo abbreviation: open-repo (expands to repo-open on space/enter).
 function repo-open --description 'Open the origin remote of the current repo in a browser'
     argparse -X 0 h/help p/print r/root -- $argv
     or return 1
diff --git a/functions/rg.fish b/functions/rg.fish
index 9ccae44..346f652 100644
--- a/functions/rg.fish
+++ b/functions/rg.fish
@@ -17,6 +17,8 @@
 #
 # EXAMPLE
 #   rg "TODO" src/
+#   rg "fish_greeting" ~/.config/fish/
+#   rg -l "TODO" ~/projects/myapp
 function rg --description 'alias rg=rg --hyperlink-format=kitty'
     # Opinionated guard (C1): fall back to bare command rg when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases
diff --git a/functions/rm.fish b/functions/rm.fish
index 0c1532b..cfac650 100644
--- a/functions/rm.fish
+++ b/functions/rm.fish
@@ -33,6 +33,9 @@
 #   rm file.txt
 #   rm -e
 #   rm -S sensitive_key.pem
+#
+# NOTES
+#   Falls back to /usr/bin/rm when trash is unavailable.
 function rm --description 'Ultimate rm: trash, list, empty, and secure-erase'
     # Opinionated guard (C1): fall back to bare command rm when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases
diff --git a/functions/spark.fish b/functions/spark.fish
index f978155..2a48ac1 100644
--- a/functions/spark.fish
+++ b/functions/spark.fish
@@ -22,6 +22,7 @@
 # EXAMPLE
 #   spark 1 1 2 5 14 42
 #   seq 64 | sort --random-sort | spark
+#   echo "3 7 2 9 1" | spark
 function spark --description 'Sparklines'
     argparse --ignore-unknown --name=spark v/version h/help m/min= M/max= -- $argv || return
 
diff --git a/functions/y.fish b/functions/y.fish
index a08b177..b965c3f 100644
--- a/functions/y.fish
+++ b/functions/y.fish
@@ -20,6 +20,8 @@
 #
 # EXAMPLE
 #   y "hello world"
+#   ls | y
+#   cat file.txt | y
 function y --description 'Yank to clipboard'
     # Check for help flag
     if contains -- -h $argv; or contains -- --help $argv
diff --git a/functions/yt-dlp.fish b/functions/yt-dlp.fish
index e2c160a..b9eb35c 100644
--- a/functions/yt-dlp.fish
+++ b/functions/yt-dlp.fish
@@ -17,6 +17,7 @@
 #
 # ARGUMENTS
 #   args...  Arguments forwarded to yt-dlp (defaults prepended)
+#   --no-embed-thumbnail  Skip thumbnail embedding for this run
 #
 # EXAMPLE
 #   yt-dlp dQw4w9WgXcQ