An alternative to `rm`, but moves the file to a dustbox instead.

## Creating ShellScript files

When creating a ShellScript file:

- Always include `./LICENSE` content as a comment at the end of the file.

- Minimize dependencies on other ShellScript files whenever possible.
    - This is because `./README.md` explicitly states that the installation is independent of the environment.
    - However, exceptions are `./define-options.sh` and `./lib/fun.sh`, which may be depended upon.
        - This is also explicitly stated in `./README.md`.
    - For usage of `./lib/fun.sh`, refer to its contents or the [official README.md](https://raw.githubusercontent.com/ssledz/bash-fun/refs/heads/master/README.md).

- If a library in the `./lib` directory seems useful, prioritize using it.
    - `./lib/fun.sh` is particularly useful. Keep functional programming in mind.

- Include `#!/bin/bash` as the first line.

- Follow this with a description and usage examples. For instance:
    - The usage examples should be comprehensive, but also remain simple and easy to read for users.

bin/dust
```sh
#!/bin/bash

# An alternative to `rm`, but moves the file to a dustbox instead.
#
# ```shell-session
# $ ls README.md  # Checking existence of readme
# $ dust README.md
# mv README.md /home/aiya000/.backup/dustbox/README.md_2025-02-25_13:45:37.md
# ```

# Implementation follows
# ...

# Contents of ./LICENSE follow
# ...
```

- Read the "About `./sources`" and "About `./bin`" sections to determine the appropriate placement of ShellScript files.
    - Ensure that placed scripts adhere to the rules outlined in their respective sections.

- Allow users as much configuration flexibility as possible.
    - Whenever possible, allow settings to be configured via environment variables.
        - In such cases, append the following format to `./define-options.sh`:

define-options.sh
```sh
# ...

[[ -z $BASH_TOYS_{VARIABLE_NAME} ]] && export BASH_TOYS_{VARIABLE_NAME}={DEFAULT_VALUE}

# ...
```

- After creating a ShellScript file, also create a corresponding test.
    - Test-related rules are outlined in the 'Creating Test Files' section.

- When using variable names, prefer `$varname` over `${varname}`.
    - However, use `${varname}` when `$varname` could be misinterpreted as part of a string.

- Always use `function` when defining functions.
- When defining local variables within functions, use `local`.
- Whenever possible, avoid using global variables (such as top-level `$1`) within functions and use arguments instead.
- Strive for low module coupling and high module cohesion in functions.

- While defining helper functions is acceptable, avoid excessive proliferation.
    - In other words, minimize unnecessary noise.

Here are examples of unnecessary helper functions:

```sh
function has_glow () {
  # Writing this directly in the condition does not significantly reduce readability.
  command -v glow >/dev/null 2>&1
}

function is_disable_glow_opt () {
  # Same as above.
  [[ $1 == '--disable-glow' ]]
}
```

Conversely, the following is an appropriate helper function:

```sh
# Show help
function show_help () {
  cat << EOF
bash-toys-help - Show help for bash-toys commands

Usage:
  bash-toys-help [--disable-glow] COMMAND
  bash-toys-help --help

Options:
  --disable-glow  Do not use glow for markdown rendering
  --help         Show this help message
EOF
}
```

- Use `snake_case` for helper function names.
    - However, an exception applies to functions placed in `./sources` following the `function {feature_name}` naming pattern.
        - See the "About `./sources`" section for details.

- Insert spaces before and after `;`.
- Use `[[ ... ]]` instead of `[ ... ]`.

- If `--help` is passed, implement it to display help documentation.
    - Ensure no other operations are performed when displaying help.

- Prefer `''` over `""` when possible.
- If quotes are unnecessary, omit them entirely.

- While comments are allowed, avoid writing them if the code is self-explanatory.
    - Strive for code that is inherently descriptive.

Here is an example where a comment is unnecessary:
`# Show help` is redundant.

```sh
# Show help
function show_help () {
  cat << EOF
cmd - ...

Usage:
  ...

Options:
  ...
EOF
}
```

- Run shellcheck and fix any issues whenever possible.

### About `./sources`

- ShellScripts that cannot be executed as a subprocess (i.e., functions affecting the current shell) should be placed in `./sources`.
    - Name the file `{feature_name}.sh` and define a function inside it as `function {feature_name} () { ... }`.
    - Use `kebab-case` for `{feature_name}`.

For example:

source/define-alias.sh
```sh
#!/bin/bash

# Defines an alias.
# ```shell-session
# $ define-alias ll 'ls -l'
# ```

function define-alias () {
  local name=$1 detail=$2
  eval "alias $name='$detail'"
}
```

- All other ShellScripts that can be executed as a subprocess should be placed in `./bin`.

### About `./bin`

- ShellScripts that can be executed as a subprocess should be placed in `./bin`.
    - Name the file `{feature_name}` without an extension.

Refer to the "About `./sources`" section for additional details.

### Creating Test Files

- Test descriptions MUST follow the format: ``'`{The actual run command} should {expected behavior}`'``
    - The actual run command should be exactly as it would be typed in the terminal
    - Example: ``'`my-command --flag` should display help message'``

- Use `./bin/expects` for assertions instead of `[[ ... ]]` or `[ ... ]`
    - This provides clearer error messages and more consistent testing
    - Example: `expects "$status" to_be 0` instead of `[[ $status -eq 0 ]]`
    - The only exception is tests for `/bin/expects` itself

- Do not write tests that only check if environment variables are set
    - Environment setup should be handled in the setup() function
    - Focus tests on command behavior, not configuration

- Help message testing conventions:
    - First line must match the pattern `^{command-name} - ` using `to_match`
    - Second line must be empty
    - Usage section starts at line 3
    - Options section starts at line 6
    - Example:
      ```sh
      expects "${lines[0]}" to_match '^my-command - '
      expects "${lines[1]}" to_equal ''
      expects "${lines[3]}" to_equal 'Usage:'
      expects "${lines[6]}" to_equal 'Options:'
      ```

## Git

- Write commit messages in English.

- Format commit messages as `{Verb} ...`.
    - Capitalize the first letter of the verb, e.g., `Add ...`, `Fix ...`.

- If the `gh` command is available, check the issue list using `$ gh issue list` before committing.
    - If there is an issue that the commit is likely to resolve, add `Closes #{IssueNumber}` on the third line of the commit message.

## General Rules

- When executing `$ curl {url} | sh` or `$ curl {url} | bash`, always review the contents of `{url}` first and understand any potential risks before proceeding.
    - If any risks exist, halt the process and consult with me for further instructions.

- If installing OS packages (e.g., `$ sudo apt install {packages}` or `$ brew install {packages}`) is necessary, pause the task and consult with me first.