docs: improved fs_patch and fs_write descriptions and examples

2026-06-03 12:06:39 -06:00
parent 43fbe448cb
commit b781dd8dc6
3 changed files with 10 additions and 4 deletions
@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
 set -e

-# @describe Write the full file contents to a file at the specified path.
+# @describe Write the FULL file contents to a file at the specified path. Use this for NEW files or COMPLETE rewrites
+# only. For editing an existing file, prefer fs_patch. It's a surgical edit that preserves unchanged content, requires
+# sending less data, and is less prone to accidental data loss.

 # @option --path! The path of the file to write to
 # @option --contents! The full contents to write to the file