Support a default help flag.

[impguard]

It would be nice if we could support a help flag for each bake task. Currently, I created a helper shell script to handle this:

bake_task init "generate initial files"
function init () {
    util:help "$@" "$(cat <<EOM
Usage: bake init

Sets up the environment:

   * creates default credentials
   * sets up test fixtures
EOM
)"
    ....
}

function util:help () {
    local usage="${@:$#} "

    while getopts "h" opt; do
        case "$opt" in
            h)
                echo "$usage"
                exit 2
                ;;
        esac
    done
}

This works fine, but would love if the overhead of this was built into bake. Thanks!

[kyleburton]

Are you looking for util:help to be a bake builtin? Or are we looking for a way to have a longer usage string in addition to the brief one? How do you see this being used at the cli? What if we allowed bake_task to take a 3rd argument which was the usage? Alternatively what if bake_task's second argument allowed for longer strings with multiple lines & only showed the first line (or first X chars of the first line) when no command is given to bake?

I think in your example each task would then support an implicit -h switch correct?

$ bake init -h
Usage: bake init

Sets up the environment:

   * creates default credentials
   * sets up test fixtures
$

Is this the example you had in mind?

For the alternatives, perhaps, supporting a help command would work?

$ bake help init
Usage: bake init

Sets up the environment:

   * creates default credentials
   * sets up test fixtures
$

One trade off of the help command is that there is a magic command that users might end up overriding or wanting to use. The -h approach means that bake would then need to inspect the arguments to every task, catching the -h, where tasks couldn't then decide to handle the -h themselves.

What are your thoughts?