105 lines
2.9 KiB
Markdown
105 lines
2.9 KiB
Markdown
# Bash Template Command
|
|
|
|
*This `README.md` is [autogenerated](#generate-readmemd-file).*
|
|
|
|
This is a GitHub template repo that will be copied instead of forked to
|
|
create a new Bash command with a command something like this:
|
|
|
|
```
|
|
gh repo create rwxrob/mycmd -p rwxrob/template-bash-command
|
|
```
|
|
|
|
This `command` inside can then be renamed and finished.
|
|
|
|
Obviously, not all of this is needed for many Bash scripts, but anything
|
|
with more than two subcommands will benefit from the builtin tab
|
|
completion, embedded Markdown help documentation support, and included
|
|
functions (`usage`, `_filter`, `_buffer`, `_have`, etc.)
|
|
|
|
## Naming Conventions
|
|
|
|
* Name repos containing single bash commands with `cmd-`
|
|
* Name template repos beginning with `template-`
|
|
* Start command functions with `command_` to be completed
|
|
* Start command functions with `command__` to not be completed
|
|
|
|
## Dependencies
|
|
|
|
Required:
|
|
|
|
* Bash 4+
|
|
|
|
Optional:
|
|
|
|
* `pandoc` - for rich help docs
|
|
|
|
## Justification
|
|
|
|
Bash is the dominate shell scripting language and the official default
|
|
Linux interactive shell, which reduces cognitive overhead; every command
|
|
line *is* a line of code that could be put into script as is. Bash
|
|
scripts are at the core of cloud, containers, and Kubernetes. Bash 4+
|
|
with its associative array support, powerful regular expressions, and
|
|
multiple ways of feeding data to loops easily covers the needs
|
|
previously requiring Python and Perl scripts. Bash scripts are also much
|
|
more powerful, safer, flexible, and performant than POSIX shell or Zsh.
|
|
|
|
## Caveats
|
|
|
|
* Use the official bash path: `#!/usr/bin/bash`
|
|
* Using `#!/usr/bin/env bash` introduces unnecessary risk
|
|
* Always set the acceptable `PATH` at beginning of script
|
|
* Always check script with [`shellcheck`] before releasing
|
|
* Always use `bc` for *any* floating point math
|
|
|
|
[`shellcheck`]: <https://www.shellcheck.net>
|
|
|
|
## Legal
|
|
|
|
Copyright 2021 Rob Muhlestein <rob@rwx.gg>
|
|
Released under Apache-2.0 License
|
|
Please mention <https://youtube.com/rwxrob>
|
|
|
|
----
|
|
|
|
## Commands
|
|
|
|
### The `bar` Command
|
|
|
|
Bars.
|
|
|
|
### The `foo` Command
|
|
|
|
Foos.
|
|
|
|
### Display Help Information
|
|
|
|
```
|
|
help [<command>]
|
|
```
|
|
|
|
Displays specific help information. If no argument is passed displays
|
|
general help information (main). Otherwise, the documentation for the
|
|
specific argument keyword is displayed, which usually corresponds to
|
|
a command name (but not necessarily). All documentation is written in
|
|
GitHub Flavored Markdown and will displayed as a web page if `pandoc`
|
|
and `$HELP_BROWSER` are detected, otherwise, just the Markdown is sent
|
|
to `$PAGER` (default: more).
|
|
|
|
Also see `readme` and `usage` commands.
|
|
|
|
### Generate `README.md` File
|
|
|
|
```
|
|
command readme > README.md
|
|
```
|
|
|
|
The `readme` command will output the embedded help documentation in raw
|
|
GitHub Flavored Markdown suitable for use as a `README.md` file on
|
|
GitHub or similar hosting service.
|
|
|
|
### The `usage` Command
|
|
|
|
Displays a summary of usage.
|
|
|