TypedDevs · Chemaclass · Jul 20, 2025 · Jul 20, 2025 · Jul 20, 2025 · Jul 20, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@
 - Add `--init [dir]` option to get you started quickly
 - Optimize `--help` message
 - Add `--no-output` option
+- Add `--doc [search]` option
 
 ## [0.21.0](https://github.com/TypedDevs/bashunit/compare/0.20.0...0.21.0) - 2025-06-18
 

diff --git a/bashunit b/bashunit
@@ -25,6 +25,7 @@ source "$BASHUNIT_ROOT_DIR/src/console_results.sh"
 source "$BASHUNIT_ROOT_DIR/src/helpers.sh"
 source "$BASHUNIT_ROOT_DIR/src/upgrade.sh"
 source "$BASHUNIT_ROOT_DIR/src/assertions.sh"
+source "$BASHUNIT_ROOT_DIR/src/doc.sh"
 source "$BASHUNIT_ROOT_DIR/src/reports.sh"
 source "$BASHUNIT_ROOT_DIR/src/runner.sh"
 source "$BASHUNIT_ROOT_DIR/src/bashunit.sh"
@@ -101,6 +102,15 @@ while [[ $# -gt 0 ]]; do
       console_header::print_version
       trap '' EXIT && exit 0
       ;;
+    --doc)
+      if [[ -n ${2:-} && ${2:0:1} != "-" ]]; then
+        doc::print_asserts "$2"
+        shift
+      else
+        doc::print_asserts
+      fi
+      trap '' EXIT && exit 0
+      ;;
     --upgrade)
       upgrade::upgrade
       trap '' EXIT && exit 0

diff --git a/docs/assertions.md b/docs/assertions.md
@@ -113,7 +113,7 @@ function test_failure() {
 
 Reports an error if `needle` is not a substring of `haystack`.
 
-[assert_not_contains](#assert-not-contains) is the inverse of this assertion and takes the same arguments.
+- [assert_not_contains](#assert-not-contains) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -150,7 +150,7 @@ function test_failure() {
 
 Reports an error if `actual` is not empty.
 
-[assert_not_empty](#assert-not-empty) is the inverse of this assertion and takes the same arguments.
+- [assert_not_empty](#assert-not-empty) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -169,7 +169,7 @@ function test_failure() {
 
 Reports an error if `value` does not match the regular expression `pattern`.
 
-[assert_not_matches](#assert-not-matches) is the inverse of this assertion and takes the same arguments.
+- [assert_not_matches](#assert-not-matches) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -188,7 +188,7 @@ function test_failure() {
 
 Reports an error if `haystack` does not starts with `needle`.
 
-[assert_string_not_starts_with](#assert-string-not-starts-with) is the inverse of this assertion and takes the same arguments.
+- [assert_string_not_starts_with](#assert-string-not-starts-with) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -207,7 +207,7 @@ function test_failure() {
 
 Reports an error if `haystack` does not ends with `needle`.
 
-[assert_string_not_ends_with](#assert-string-not-ends-with) is the inverse of this assertion and takes the same arguments.
+- [assert_string_not_ends_with](#assert-string-not-ends-with) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -247,7 +247,7 @@ function test_failure() {
 
 Reports an error if `actual` is not less than `expected`.
 
-[assert_greater_than](#assert-greater-than) is the inverse of this assertion and takes the same arguments.
+- [assert_greater_than](#assert-greater-than) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -266,7 +266,7 @@ function test_failure() {
 
 Reports an error if `actual` is not less than or equal to `expected`.
 
-[assert_greater_than](#assert-greater-or-equal-than) is the inverse of this assertion and takes the same arguments.
+- [assert_greater_than](#assert-greater-or-equal-than) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -289,7 +289,7 @@ function test_failure() {
 
 Reports an error if `actual` is not greater than `expected`.
 
-[assert_less_than](#assert-less-than) is the inverse of this assertion and takes the same arguments.
+- [assert_less_than](#assert-less-than) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -308,7 +308,7 @@ function test_failure() {
 
 Reports an error if `actual` is not greater than or equal to `expected`.
 
-[assert_less_or_equal_than](#assert-less-or-equal-than) is the inverse of this assertion and takes the same arguments.
+- [assert_less_or_equal_than](#assert-less-or-equal-than) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -333,7 +333,7 @@ Reports an error if the exit code of `callable` is not equal to `expected`.
 
 If `callable` is not provided, it takes the last executed command or function instead.
 
-[assert_successful_code](#assert-successful-code), [assert_general_error](#assert-general-error) and [assert_command_not_found](#assert-command-not-found)
+- [assert_successful_code](#assert-successful-code), [assert_general_error](#assert-general-error) and [assert_command_not_found](#assert-command-not-found)
 are more semantic versions of this assertion, for which you don't need to specify an exit code.
 
 ::: code-group
@@ -371,7 +371,7 @@ function test_failure() {
 
 Reports an error if `needle` is not an element of `haystack`.
 
-[assert_array_not_contains](#assert-array-not-contains) is the inverse of this assertion and takes the same arguments.
+- [assert_array_not_contains](#assert-array-not-contains) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -396,7 +396,7 @@ Reports an error if the exit code of `callable` is not successful (`0`).
 
 If `callable` is not provided, it takes the last executed command or function instead.
 
-[assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code.
+- [assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code.
 
 ::: code-group
 ```bash [Example]
@@ -435,7 +435,7 @@ Reports an error if the exit code of `callable` is not a general error (`1`).
 
 If `callable` is not provided, it takes the last executed command or function instead.
 
-[assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code.
+- [assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code.
 
 ::: code-group
 ```bash [Example]
@@ -475,7 +475,7 @@ In other words, if executing `callable` does not return a command not found exit
 
 If `callable` is not provided, it takes the last executed command or function instead.
 
-[assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code.
+- [assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code.
 
 ::: code-group
 ```bash [Example]
@@ -500,7 +500,7 @@ function test_failure() {
 
 Reports an error if `file` does not exists, or it is a directory.
 
-[assert_file_not_exists](#assert-file-not-exists) is the inverse of this assertion and takes the same arguments.
+- [assert_file_not_exists](#assert-file-not-exists) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -526,7 +526,7 @@ function test_failure() {
 
 Reports an error if `file` does not contains the search string.
 
-[assert_file_not_contains](#assert-file-not-contains) is the inverse of this assertion and takes the same arguments.
+- [assert_file_not_contains](#assert-file-not-contains) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -601,7 +601,7 @@ function test_failure() {
 
 Reports an error if `directory` does not exist.
 
-[assert_directory_not_exists](#assert-directory-not-exists) is the inverse of this assertion and takes the same arguments.
+- [assert_directory_not_exists](#assert-directory-not-exists) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -645,7 +645,7 @@ function test_failure() {
 
 Reports an error if `directory` is not an empty directory.
 
-[assert_is_directory_not_empty](#assert-is-directory-not-empty) is the inverse of this assertion and takes the same arguments.
+- [assert_is_directory_not_empty](#assert-is-directory-not-empty) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -669,7 +669,7 @@ function test_failure() {
 
 Reports an error if `directory` is not a readable directory.
 
-[assert_is_directory_not_readable](#assert-is-directory-not-readable) is the inverse of this assertion and takes the same arguments.
+- [assert_is_directory_not_readable](#assert-is-directory-not-readable) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -693,7 +693,7 @@ function test_failure() {
 
 Reports an error if `directory` is not a writable directory.
 
-[assert_is_directory_not_writable](#assert-is-directory-not-writable) is the inverse of this assertion and takes the same arguments.
+- [assert_is_directory_not_writable](#assert-is-directory-not-writable) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -717,7 +717,7 @@ function test_failure() {
 
 Reports an error if `expected` and `actual` are not equals.
 
-[assert_files_not_equals](#assert-files-not-equals) is the inverse of this assertion and takes the same arguments.
+- [assert_files_not_equals](#assert-files-not-equals) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -757,7 +757,7 @@ function test_failure() {
 
 Reports an error if the two variables `expected` and `actual` are the same value.
 
-[assert_same](#assert-same) is the inverse of this assertion and takes the same arguments.
+- [assert_same](#assert-same) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -776,7 +776,7 @@ function test_failure() {
 
 Reports an error if `needle` is a substring of `haystack`.
 
-[assert_contains](#assert-contains) is the inverse of this assertion and takes the same arguments.
+- [assert_contains](#assert-contains) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -795,7 +795,7 @@ function test_failure() {
 
 Reports an error if `haystack` does starts with `needle`.
 
-[assert_string_starts_with](#assert-string-starts-with) is the inverse of this assertion and takes the same arguments.
+- [assert_string_starts_with](#assert-string-starts-with) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -814,7 +814,7 @@ function test_failure() {
 
 Reports an error if `haystack` does ends with `needle`.
 
-[assert_string_ends_with](#assert-string-ends-with) is the inverse of this assertion and takes the same arguments.
+- [assert_string_ends_with](#assert-string-ends-with) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -833,7 +833,7 @@ function test_failure() {
 
 Reports an error if `actual` is empty.
 
-[assert_empty](#assert-empty) is the inverse of this assertion and takes the same arguments.
+- [assert_empty](#assert-empty) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -852,7 +852,7 @@ function test_failure() {
 
 Reports an error if `value` matches the regular expression `pattern`.
 
-[assert_matches](#assert-matches) is the inverse of this assertion and takes the same arguments.
+- [assert_matches](#assert-matches) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -871,7 +871,7 @@ function test_failure() {
 
 Reports an error if `needle` is an element of `haystack`.
 
-[assert_array_contains](#assert-array-contains) is the inverse of this assertion and takes the same arguments.
+- [assert_array_contains](#assert-array-contains) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -894,7 +894,7 @@ function test_failure() {
 
 Reports an error if `file` does exists.
 
-[assert_file_exists](#assert-file-exists) is the inverse of this assertion and takes the same arguments.
+- [assert_file_exists](#assert-file-exists) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -921,7 +921,7 @@ function test_failed() {
 
 Reports an error if `file` contains the search string.
 
-[assert_file_contains](#assert-file-contains) is the inverse of this assertion and takes the same arguments.
+- [assert_file_contains](#assert-file-contains) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -946,7 +946,7 @@ function test_failure() {
 
 Reports an error if `directory` exists.
 
-[assert_directory_exists](#assert-directory-exists) is the inverse of this assertion and takes the same arguments.
+- [assert_directory_exists](#assert-directory-exists) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -969,7 +969,7 @@ function test_failure() {
 
 Reports an error if `directory` is empty.
 
-[assert_is_directory_empty](#assert-is-directory-empty) is the inverse of this assertion and takes the same arguments.
+- [assert_is_directory_empty](#assert-is-directory-empty) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -993,7 +993,7 @@ function test_failure() {
 
 Reports an error if `directory` is readable.
 
-[assert_is_directory_readable](#assert-is-directory-readable) is the inverse of this assertion and takes the same arguments.
+- [assert_is_directory_readable](#assert-is-directory-readable) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -1017,7 +1017,7 @@ function test_failure() {
 
 Reports an error if `directory` is writable.
 
-[assert_is_directory_writable](#assert-is-directory-writable) is the inverse of this assertion and takes the same arguments.
+- [assert_is_directory_writable](#assert-is-directory-writable) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]
@@ -1042,7 +1042,7 @@ function test_failure() {
 
 Reports an error if `expected` and `actual` are not equals.
 
-[assert_files_equals](#assert-files-equals) is the inverse of this assertion and takes the same arguments.
+- [assert_files_equals](#assert-files-equals) is the inverse of this assertion and takes the same arguments.
 
 ::: code-group
 ```bash [Example]

diff --git a/docs/command-line.md b/docs/command-line.md
@@ -382,6 +382,26 @@ Upgrade **bashunit** to latest version.
 ```
 :::
 
+## Doc
+
+> `bashunit --doc [filter]`
+
+Display the documentation for assert functions. When `filter` is provided,
+only matching asserts will be shown.
+
+::: code-group
+```bash [Example]
+./bashunit --doc same
+```
+```bash [Output]
+## assert_equals
+...
+
+## assert_not_same
+...
+```
+:::
+
 ## Init
 
 > `bashunit --init [dir]`

diff --git a/src/console_header.sh b/src/console_header.sh
@@ -72,6 +72,10 @@ Options:
   --debug [file]
                             Enable shell debug mode. Logs to file if provided.
 
+  --doc <?filter>
+                            Display the documentation for assert functions. When a filter is
+                            provided, only matching asserts will be shown.
+
   -e, --env, --boot <file>
                             Load a custom env/bootstrap file to override .env or define globals.