1.3.7

.gitignore

@@ -1,3 +1,4 @@
 /cache
 /docs
+/tmp
 retype.manifest

Gemfile.lock

@@ -1,22 +1,23 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
     base64 (0.3.0)
-    clamp (1.3.3)
+    clamp (1.5.2)
     colsole (1.0.0)
     docopt_ng (0.7.1)
     domain_name (0.6.20240107)
-    ffi (1.17.2-x86_64-linux-gnu)
+    ffi (1.17.3-x86_64-linux-gnu)
     ffi-compiler (1.3.2)
       ffi (>= 1.15.5)
       rake
-    filewatcher (2.1.0)
-      module_methods (~> 0.1.0)
-    filewatcher-cli (1.1.0)
+    filewatcher (3.0.1)
+      logger (~> 1.7)
+      module_methods (~> 1.0)
+    filewatcher-cli (2.0.0)
       clamp (~> 1.3)
-      filewatcher (~> 2.1)
+      filewatcher (~> 3.0)
     foreman (0.90.0)
       thor (~> 1.4)
     http (5.3.1)
@@ -27,31 +28,33 @@ GEM
     http-cookie (1.1.0)
       domain_name (~> 0.5)
     http-form_data (2.3.0)
-    httpme (0.2.3)
-      colsole (>= 0.8.1, < 2)
+    httpme (0.2.4)
+      colsole (~> 1.0)
       mister_bin (~> 0.7)
-      puma (>= 5.6, < 7.0)
+      puma (~> 7.2)
       rack-contrib (~> 2.3)
       rackup (~> 2.2)
-      sinatra (>= 3.0, < 5)
+      sinatra (~> 4.2)
+    io-console (0.8.2)
     llhttp-ffi (0.5.1)
       ffi-compiler (~> 1.0)
       rake (~> 13.0)
     logger (1.7.0)
-    mister_bin (0.8.1)
-      colsole (>= 0.8.1, < 2)
-      docopt_ng (~> 0.7, >= 0.7.1)
-    module_methods (0.1.0)
+    mister_bin (0.9.0)
+      colsole (~> 1.0.0)
+      docopt_ng (~> 0.7.1)
+      reline (~> 0.6)
+    module_methods (1.0.0)
     mustermann (3.0.4)
       ruby2_keywords (~> 0.0.1)
     nio4r (2.7.5)
-    nokogiri (1.18.10-x86_64-linux-gnu)
+    nokogiri (1.19.2-x86_64-linux-gnu)
       racc (~> 1.4)
-    public_suffix (6.0.2)
-    puma (6.6.1)
+    public_suffix (7.0.5)
+    puma (7.2.0)
       nio4r (~> 2.0)
     racc (1.8.1)
-    rack (3.2.4)
+    rack (3.2.5)
     rack-contrib (2.5.0)
       rack (< 4)
     rack-protection (4.2.1)
@@ -61,9 +64,11 @@ GEM
     rack-session (2.1.1)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
-    rackup (2.2.1)
+    rackup (2.3.1)
       rack (>= 3)
     rake (13.3.1)
+    reline (0.6.3)
+      io-console (~> 0.5)
     ruby2_keywords (0.0.5)
     sinatra (4.2.1)
       logger (>= 1.6.0)
@@ -77,8 +82,8 @@ GEM
       mister_bin (~> 0.7)
       nokogiri (~> 1.10)
       webcache (~> 0.8)
-    thor (1.4.0)
-    tilt (2.6.1)
+    thor (1.5.0)
+    tilt (2.7.0)
     webcache (0.9.0)
       http (~> 5.0)
 
@@ -92,4 +97,4 @@ DEPENDENCIES
   sla
 
 BUNDLED WITH
-   2.6.9
+  4.0.3

retype.yml

@@ -15,6 +15,8 @@ branding:
   logo: assets/logo.svg
   logoDark: assets/logo-dark.svg
   label: v1.3.6
+  logoWidth: 143
+  logoHeight: 40
 
 meta:
   title: " - Bashly"

src/configuration/command.md

@@ -214,6 +214,44 @@ Specify an array of variables that can be accessed globally in your script, or s
 
 ## Advanced Options
 
+### argfile
+
+[!badge String]
+
+Specify a file to load additional arguments and flags from before parsing the
+actual command line.
+
+If the file does not exist, it is ignored.
+
+This is useful for keeping default arguments in a file while still allowing
+explicit CLI arguments to override them.
+
+The argfile format is intentionally simple:
+
+- Empty lines are ignored
+- Lines starting with `#` are ignored
+- Each other line becomes one argument
+- A flag and value can be written on one line or on two lines
+- Matching outer quotes are stripped
+
+Example argfile:
+
+```bash .download
+--force
+--debug
+
+# These are all equivalent:
+--output some file
+
+--output
+some file
+
+--output "some file"
+```
+
+[!button variant="primary" icon="code-review" text="Argfile Example"](https://github.com/bashly-framework/bashly/tree/master/examples/argfile#readme)
+
+
 ### catch_all
 
 [!badge Boolean / String / Hash]

src/examples.md

@@ -50,6 +50,7 @@ All examples are listed below for convenience.
 - [private-reveal](https://github.com/bashly-framework/bashly/tree/master/examples/private-reveal#readme) - allowing users to reveal private commands, flags or environment variables
 - [stdin](https://github.com/bashly-framework/bashly/tree/master/examples/stdin#readme) - reading input from stdin
 - [filters](https://github.com/bashly-framework/bashly/tree/master/examples/filters#readme) - preventing commands from running unless custom conditions are met
+- [argfile](https://github.com/bashly-framework/bashly/tree/master/examples/argfile#readme) - auto-load arguments from a file
 - [commands-expose](https://github.com/bashly-framework/bashly/tree/master/examples/commands-expose#readme) - showing subcommands in the parent's help
 - [key-value-pairs](https://github.com/bashly-framework/bashly/tree/master/examples/key-value-pairs#readme) - parsing key=value arguments and flags
 - [command-examples-on-error](https://github.com/bashly-framework/bashly/tree/master/examples/command-examples-on-error#readme) - showing examples on error

src/usage/settings.md

@@ -5,8 +5,8 @@ order: 80
 
 # Settings
 
-Some of bashly's commands can be tweaked through the use of environment
-variables, or a settings file.
+Some of bashly's behavior and output can be tweaked through the use of
+environment variables, or a settings file.
 
 ## Settings file
 
@@ -411,6 +411,33 @@ enable_sourcing: development
 Specify if you want the generated script to include a condition that checks if
 the script was sourced and only execute it if it is not.
 
+## Developer Options
+
+### `watch_evented`
+
+```yaml
+# default
+watch_evented: false
+```
+
+Enable evented file watching for the `bashly generate --watch` command.
+
+Evented file watching is more efficient than polling, but may not work reliably
+in some environments or operating systems (for example, network file systems or
+containerized environments). By default, this option is disabled, causing the
+file watcher to use polling instead.
+
+### `watch_latency`
+
+```yaml
+# default
+watch_latency: 1.0
+```
+
+Set the file watcher latency (in seconds) for the `bashly generate --watch`
+command.
+
+
 ## Scripting Options
 
 ### `var_aliases`

src/usage/testing-your-scripts.md

@@ -21,30 +21,16 @@ spaces, and case indentation rules:
 $ shfmt --diff --case-indent --indent 2 yourscript
 ```
 
-## Approval Testing
+## Testing Frameworks
 
-!!!success Tip
-Run `bashly add test` to add a `test` folder to your project, with the 
-Approvals.bash framework.
-!!!
+When your scripts grow more elaborate, you can test them with any Bash testing
+framework you prefer.
 
-In cases where your scripts are more elaborate, or when you wish to ensure
-your scripts behave as expected, you can use any bash testing framework to test
-your scripts.
-
-One such lightweight framework is
-[Approvals.bash](https://github.com/dannyben/approvals.bash#readme), which lets
-you test any command in your script and prompts you for interactive approval
-of its output. Whenever the output changes, you will be prompted again to approve it.
-
-A sample test script looks like this:
-
-```bash
-#!/usr/bin/env bash
-source approvals.bash
-
-approve "your-cli --help"
-approve "your-cli command --arg"
-# ... more tests
-```
+One advantage of Bashly projects is that user-developed logic usually lives in
+separate files under `src`. This makes it easier to test only the unit under
+test by sourcing the relevant file directly, instead of invoking the entire
+generated script for every test.
 
+This approach works well for unit tests around helper functions, command logic,
+and edge cases, while higher-level integration tests can still exercise the
+generated CLI as an end user would.