From 19e12cee88a7e9e3835ebee68ef5bbb9e9e5367b Mon Sep 17 00:00:00 2001
From: Connor Olding <cloningdonor@gmail.com>
Date: Sun, 1 Aug 2021 07:58:21 -0700
Subject: [PATCH] document backup functions

---
 sh/bak    | 14 ++++++++++++++
 sh/baknow | 14 ++++++++++++++
 sh/baks   | 17 +++++++++++++++--
 3 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/sh/bak b/sh/bak
index 150654d..aae753d 100644
--- a/sh/bak
+++ b/sh/bak
@@ -4,6 +4,20 @@
 # YES_DASH
 
 bak() { ### @-
+    ### backup files by copying each and appending ".bak" to their names.
+    ### this calls itself recursively to avoid clobbering existing backups.
+    ###
+    ### ```
+    ### % touch -d '2001-12-25 16:30:00' butts
+    ### % bak butts
+    ### % touch butts
+    ### % bak butts
+    ### % ls -l
+    ### total 0
+    ### -rw-r--r-- 1 notwa None 0 Aug  1 07:56 butts
+    ### -rw-r--r-- 1 notwa None 0 Dec 25  2001 butts.bak
+    ### -rw-r--r-- 1 notwa None 0 Dec 25  2001 butts.bak.bak
+    ### ```
     [ $# -gt 0 ] || { printf "%s\n" "$0: too few arguments" >&2; return 1; }
     local ret=0
     for f; do
diff --git a/sh/baknow b/sh/baknow
index 5eff69d..a75b275 100644
--- a/sh/baknow
+++ b/sh/baknow
@@ -2,6 +2,20 @@
 # YES_ZSH
 
 baknow() { ### @-
+    ### backup a single file by appending its timestamp given by [`now`.](#now)
+    ###
+    ### ```
+    ### $ touch -d '2001-12-25 16:30:00' butts
+    ### $ baknow butts
+    ### $ baknow butts
+    ### cp: overwrite 'butts.2001-12-26_01800000.bak'? n
+    ### $ ls -l
+    ### total 0
+    ### -rw-r--r-- 1 notwa None 0 Dec 25  2001 butts
+    ### -rw-r--r-- 1 notwa None 0 Dec 25  2001 butts.2001-12-26_01800000.bak
+    ### ```
+    ###
+    ### **TODO:** support multiple files at once.
     cp -ip "${1:?missing file argument}" "$1.$(now "$1").bak"
 }
 
diff --git a/sh/baks b/sh/baks
index bdd4368..0879d40 100644
--- a/sh/baks
+++ b/sh/baks
@@ -4,11 +4,24 @@
 # YES_BASH
 # YES_DASH
 
-: $((SOURCING+=1))
+#: $((SOURCING+=1))
 #. ~/sh/note # FIXME: don't do this?
-: $((SOURCING-=1))
+#: $((SOURCING-=1))
 
 baks() { ### @-
+    ### backup files by copying each and appending *the current* date-time,
+    ### irrespective of when the files were modified or created.
+    ###
+    ### ```
+    ### $ touch -d '2001-12-25 16:30:00' butts
+    ### $ baks butts
+    ### $ baks butts
+    ### $ ls -l
+    ### total 0
+    ### -rw-r--r-- 1 notwa None 0 Dec 25  2001 butts
+    ### -rw-r--r-- 1 notwa None 0 Dec 25  2001 butts.21-08-01_14-54-07.bak
+    ### -rw-r--r-- 1 notwa None 0 Dec 25  2001 butts.21-08-01_14-54-09.bak
+    ### ```
     local ret=0
     for fp; do
         local now="$(date -u '+%y-%m-%d_%H-%M-%S')"