compare documented command usage with a readme

diff-usage.sh

#! /bin/bash

# Compare documented usage with actual help output,
# to e.g. be used from a Git pre-push hook to keep README's up to date

CMD="$1"
README="$2"
NL="$3"

if test -z "$CMD"
then
    echo no command given
    exit 1
fi

if test -z "$README"
then
    echo no README given
    exit 1
fi

if test -z "$NL"
then
    NL="§"
fi

if test ${#NL} != 1
then
    echo the newline placeholder must be a single character
    exit 1
fi

# This matches the behaviour of the `flags` package in the Go standard library,
# and assumes the readme contains a ```shell``` code block with usage output.

documented=$(cat "$README" | tr '\n' "$NL" | grep -o '```shell'"$NL"'Usage of '"$CMD"'[^`]*```' | tr "$NL" '\n')

current=$(echo -e '```shell\n'"$("$CMD" -help 2>&1)"'\n```')

diff -u <(echo "$documented") <(echo "$current")