Bash Template Command

This README.md is autogenerated.

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.

Guidelines

Write GitHub Flavored Markdown only
Use present tense ("outputs" over "will output")
Prefer "output" and "display" over ~~print~~
Follow the naming conventions
Use the official bash path: #!/bin/bash
Use of #!/usr/bin/bash is outdated
Using #!/usr/bin/env bash introduces unnecessary risk
Explicitly export PATH in script when possible
Always check script with shellcheck before releasing
Always use bc for any floating point math

Legal

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.

The `json` Command

Converts input into JSON string using jq containing only escaped ( ) line returns.

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.

Autogenerated Sun Aug 15 04:56:38 PM EDT 2021

sdconrox/template-bash-command