DOC: Break some lines for a finer read

Author: kernc

.github/scripts/aspell-ignorewords.txt

@@ -79,3 +79,4 @@ virii
 vqwg
 worktree
 zsh
+vL

README.full.md

@@ -40,7 +40,7 @@ Features
 * **Version-controlled (git-based) backup** of plaintext documents as well as large binary files.
 * Automatic **text compression** for reduced space use.
 * Currently using **_strong_ AES256 encryption** of files and paths, so far quantum-safe.
-* Familiar git workflow: add, stage, commit, push, clone, pull, checkout.
+* **Familiar git workflow**: add (stage), commit, push, clone, pull, checkout.
 * **Selective (sparse) checkout** of backup files, efficient size-on-disk overhead.
 * **Sync to multiple clouds** for nearly free by (ab)using popular git hosts.
 * **Or sync anywhere simply** by cloning or checking-out a directory ...
@@ -84,8 +84,10 @@ fully **encrypted backups** that are really **easily replicated and synced to th
 ### Use-cases
 
 * **Zero-knowledge cloud sync and storage**
-* Replace or supplement existing **poor complex and proprietary solutions** (like Veeam, Time Machine, Google Photos & Drive, iCloud)
-  or software programs with **complex and unfamiliar CLI APIs or wide attack surfaces** (Bacula, Borg Backup, restic) ...
+* Replace or supplement existing **poor complex and proprietary solutions**
+  (like Veeam, Time Machine, Google Photos & Drive, iCloud)
+  or software programs with **complex and unfamiliar CLI APIs or wide attack surfaces**
+  (Bacula, Borg Backup, restic, git-crypt) ...
 * Cloud-based serverless virii
 * **Protocol- and PaaS-agnostic** design (AWS to Backblaze B2, GitLab to Gitea). Simply sync (even rsync) a git folder.
 
@@ -98,7 +100,7 @@ To install everything on a Debian/Ubuntu-based system, run:
 sudo apt install  gzip git git-lfs openssl gpg
 
 # Download and make available somewhere in path
-curl -L https://bit.ly/myba-backup > ~/.local/bin/myba
+curl -vL 'https://bit.ly/myba-backup' > ~/.local/bin/myba
 export PATH="$HOME/.local/bin:$PATH"
 
 myba help
@@ -150,12 +152,13 @@ The script also acknowledges a few **environment variables** which you can _set_
 * `PLAIN_REPO=` The _internal_ directory where myba actually stores both its repositories.
   Defaults to `$WORK_TREE/.myba` but can be overriden to somewhere out-of-tree ...
 * `PASSWORD=` The password to use for encryption instead of asking / reading from stdin.
-* `USE_GPG=` Myba uses `openssl enc` by default, but if you prefer to use GPG for symmetric encryption, set `USE_GPG=1`.
-* `KDF_ITERS=` A sufficient number of iterations is used for the encryption key derivation function.
-  To specify your own value and avoid rainbow table attacks on myba itself, you can customize this value.
-  If you don't know, just leave it.
-* `YES_OVERWRITE=` If set, overwrite existing when restoring/checking out files that already exist in $WORK_TREE. 
-  The default is to ask instead.
+* `USE_GPG=` Myba uses `openssl enc` by default, but if you prefer to use GPG even for
+  symmetric encryption, set `USE_GPG=1`.
+* `KDF_ITERS=` A sufficient number of iterations is used for the encryption key derivation
+  function. To specify your own value and avoid rainbow table attacks on myba itself,
+  you can customize this value. If you don't know, just leave it.
+* `YES_OVERWRITE=` If set, overwrite existing when restoring/checking out files that already
+  exist in $WORK_TREE. The default is to ask instead.
 * `VERBOSE=` More verbose output about what the program is doing.
 
 
@@ -167,15 +170,15 @@ export WORK_TREE="$HOME"
 
 myba init
 myba add Documents Photos Etc .dotfile
-PASSWORD=secret  myba commit -m "my precious"
+PASSWORD='secret'  myba commit -m "my precious"
 myba remote add origin "/media/usb/backup"
 myba remote add github "git@github.com:user/my-backup.git"
 myba push  # Push to all configured remotes & free disk space
 
 # Somewhere else, much, much later, avoiding catastrophe ...
 
 export WORK_TREE="$HOME"
-PASSWORD=secret  myba clone "..."  # Clone one of the known remotes
+PASSWORD='secret'  myba clone "..."  # Clone one of the known remotes
 myba checkout ".dotfile" # Restore backed up files in a space-efficient manner
 ```
 See [_smoke-test.sh_](https://github.com/kernc/myba/blob/master/smoke-test.sh) file for a more full example & test case!
@@ -185,8 +188,10 @@ Contributing
 ------------
 The project is [hosted on github](https://github.com/kernc/myba/).
 
-The script is considered _mostly_ feature-complete, but there remain bugs and design flaws to be discovered and ironed out,
-as well as any TODOs and FIXMEs marked in the source.
+The script is considered _mostly_ feature-complete, but there remain
+bugs and design flaws to be discovered and ironed out, as well as any
+[TODOs and FIXMEs](https://github.com/search?q=repo%3Akernc%2Fmyba+%28todo+OR+fixme+OR+xxx%29&type=code)
+marked in the source.
 **All source code lines are open to discussion.**
 Especially appreciated are clear pointers to targets for simplification.
 
@@ -235,8 +240,9 @@ you find widely-applicable and useful.
 <details markdown="1">
 <summary>Git isn't optimized for continuously-changing databases and binary files ...</summary>
 
-That is correct. Git saves whole file snapshots and doesn't do any in-file or within-file deduplication,
-so it's not well suited to automatic continuous backing up of databases that change often.
+That is correct. Git saves whole file snapshots and doesn't do any in-file or within-file
+or across-file deduplication, so it's not well suited to automatic continuous backing up
+of databases that change often.
 
 However, while git repositories bloat when commiting large binary and media files,
 **_myba_ only ever uses sparse-checkout**, keeping overhead disk space use to a minimum.

myba.sh

@@ -1,18 +1,21 @@
 #!/bin/sh
 # myba - Secure, distributed, encrypted backups based on `sh` shell and `git` (and `openssl enc` or `gpg`)
-# FIXME review
 #
 # Basically your beloved git, but with underlying two repos:
-#   - bare, local-only _plain repo_ to track changes upon local, plaintext (and binary) files, set e.g. to your $HOME,
-#   - _encrypted repo_ that holds the encrypted blobs.
+#   * bare, local-only _plain repo_ to track changes upon local,
+#     plaintext (and binary) files, set e.g. to your $HOME,
+#   * _encrypted repo_ that holds the encrypted blobs.
 # Only the encrypted repo is ever synced with configured remotes.
 # Every commit into the plain repo creates a commit in the encrypted repo.
-# Commits in the encrypted repo carry base64-encoded encrypted commit metadata of the plain repo.
-# In the encrypted repo, there is a dir "manifest" with filename "{plain_repo_commit_hash}" and
-# line format: `<enc_path>\t<plain_path>`.
-# Encrypted paths are like "abc/def//rest-of-hash" and are _deterministic_,
-# dependent upon the plain pathname and chosen password! The multi-level fs hierarchy is for near maximum efficiency of `git sparse-checkout`.
-# Encrypted blobs are also encrypted deterministically, based on hash of the plain content and chosen password.
+# Commits in the encrypted repo carry base64-encoded encrypted commit metadata
+# of the plain repo.
+# Additional files `$ENC_REPO/manifest/<plain_repo_commit_hash>` with
+# with line format: `<enc_path>\t<plain_path>`.
+# Encrypted paths are like "$ENC_REPO/abc/def/rest-of-hash" and are _deterministic_,
+# dependent upon the plain pathname and chosen password! The multi-level fs hierarchy
+# is for near maximum efficiency of `git sparse-checkout`.
+# Encrypted blobs are also encrypted deterministically, based on hash of the plain
+# content and chosen password.
 #
 # This is an expected shell workflow:
 #
@@ -196,7 +199,7 @@ cmd_init () {
     email="$USER@$(hostname 2>/dev/null || cat /etc/hostname)"
     git_plain config user.name "$USER"
     git_plain config user.email "$email"
-    git_plain config status.showUntrackedFiles no # We don't care to see largely untracked $HOME  # XXX: remove this!
+    git_plain config status.showUntrackedFiles no  # We don't care to see largely untracked $HOME  # XXX: remove this?
     git_enc config user.name "$USER"
     git_enc config user.email "$email"
     # All our files are strictly binary (encrypted)
@@ -260,14 +263,17 @@ cmd_restore () {
                 git_enc sparse-checkout reapply
 
                 # Decrypt and stage files from this commit into temp_dir
-                plain_commit="$(git_enc show --name-only --pretty=format: "$_enc_commit" -- "manifest/" | cut -d/ -f2)"
+                plain_commit="$(git_enc show --name-only --pretty=format: "$_enc_commit" -- "manifest/" |
+                                cut -d/ -f2)"
                 while IFS="$_tab" read -r _enc_path _plain_path; do
                     WORK_TREE="$temp_dir" _decrypt_file "$_enc_path" "$_plain_path"
                     WORK_TREE="$temp_dir" git_plain add "$_plain_path"
                 done < "$PLAIN_REPO/manifest/$plain_commit"
 
                 # Commit the changes to the plain repo
-                _msg="$(git_enc show -s --format='%B' "$_enc_commit" | _decrypt "" $_armor_flags | gzip -dc)"
+                _msg="$(git_enc show -s --format='%B' "$_enc_commit" |
+                        _decrypt "" $_armor_flags |
+                        gzip -dc)"
                 _date="$(git_enc show -s --format='%ai' "$_enc_commit")"
                 _author="$(git_enc show -s --format='%an <%ae>' "$_enc_commit")"
                 if ! WORK_TREE="$temp_dir" git_plain diff --staged --quiet; then
@@ -306,20 +312,23 @@ cmd_commit () {
         done
 
     # If first commit, add self
-    # FIXME: fixme??
     if ! git_enc rev-parse HEAD 2>/dev/null; then
         _self="$(command -v "$0" 2>/dev/null || echo "$0")"
         cp "$_self" "$ENC_REPO/$(basename "$_self")"
         git_enc add --sparse "$(basename "$_self")"
     fi
 
     # Stage new manifest
-    gzip -c2 "$PLAIN_REPO/$manifest_path" | _encrypt "" > "$ENC_REPO/$manifest_path"
+    gzip -c2 "$PLAIN_REPO/$manifest_path" |
+        _encrypt "" > "$ENC_REPO/$manifest_path"
     git_enc add --sparse "$manifest_path"
 
     # Commit to encrypted repo
     git_enc status --short
-    git_enc commit -m "$(git_plain show --format='%B' --name-status | gzip -c9 | _encrypt "" $_armor_flags)"
+    git_enc commit -m "$(
+        git_plain show --format='%B' --name-status |
+            gzip -c9 |
+            _encrypt "" $_armor_flags)"
 }