github.com/containers/podman/v5@v5.1.0-rc1/hack/podman-commands.sh (about)

     1  #!/usr/bin/env bash
     2  #
     3  # Compare commands listed by 'podman help' against those in 'man podman'.
     4  # Recurse into subcommands as well.
     5  #
     6  # Because we read metadoc files in the `docs` directory, this script
     7  # must run from the top level of a git checkout. FIXME: if necessary,
     8  # it could instead run 'man podman-XX'; my thinking is that this
     9  # script should run early in CI.
    10  #
    11  
    12  # override with, e.g.,  PODMAN=./bin/podman-remote
    13  PODMAN=${PODMAN:-./bin/podman}
    14  
    15  function die() {
    16      echo "FATAL: $*" >&2
    17      exit 1
    18  }
    19  
    20  
    21  # Run 'podman help' (possibly against a subcommand, e.g. 'podman help image')
    22  # and return a list of each first word under 'Available Commands', that is,
    23  # the command name but not its description.
    24  function podman_commands() {
    25      $PODMAN help "$@" |\
    26          awk '/^Available Commands:/{ok=1;next}/^Options:/{ok=0}ok { print $1 }' |\
    27          grep .
    28  
    29      # Special case: podman-completion is a hidden command
    30      # it does not show in podman help so add it here
    31      if [[ -z "$@" ]]; then
    32          echo "completion"
    33      fi
    34  }
    35  
    36  # Read a list of subcommands from a command's metadoc
    37  function podman_man() {
    38      if [ "$@" = "podman" ]; then
    39          # podman itself.
    40          # This md file has a table of the form:
    41          #   | [podman-cmd(1)\[(podman-cmd.1.md)   | Description ... |
    42          # For all such, print the 'cmd' portion (the one in brackets).
    43          sed -ne 's/^|\s\+\[podman-\([a-z]\+\)(1.*/\1/p' <docs/source/markdown/$1.1.md
    44  
    45          # Special case: there is no podman-help man page, nor need for such.
    46          echo "help"
    47          # Auto-update differs from other commands as it's a single command, not
    48          # a main and sub-command split by a dash.
    49          echo "auto-update"
    50      elif [ "$@" = "podman-image-trust" ]; then
    51          # Special case: set and show aren't actually in a table in the man page
    52          echo set
    53          echo show
    54      else
    55          # podman subcommand.
    56          # Each md file has a table of the form:
    57          #    | cmd | [podman-cmd(1)](podman-cmd.1.md) | Description ... |
    58          # For all such we find, with 'podman- in the second column, print the
    59          # first column (with whitespace trimmed)
    60          awk -F\| '$3 ~ /podman-/ { gsub(" ","",$2); print $2 }' < docs/source/markdown/$1.1.md
    61      fi
    62  }
    63  
    64  # The main thing. Compares help and man page; if we find subcommands, recurse.
    65  rc=0
    66  function compare_help_and_man() {
    67      echo
    68      echo "checking: podman $@"
    69  
    70      # e.g. podman, podman-image, podman-volume
    71      local basename=$(echo podman "$@" | sed -e 's/ /-/g')
    72  
    73      podman_commands "$@" | sort > /tmp/${basename}_help.txt
    74      podman_man $basename | sort > /tmp/${basename}_man.txt
    75  
    76      diff -u /tmp/${basename}_help.txt /tmp/${basename}_man.txt || rc=1
    77  
    78      # Now look for subcommands, e.g. container, image
    79      for cmd in $(< /tmp/${basename}_help.txt); do
    80          usage=$($PODMAN "$@" $cmd --help | grep -A1 '^Usage:' | tail -1)
    81  
    82          # if string ends in '[command]', recurse into its subcommands
    83          if expr "$usage" : '.*\[command\]$' >/dev/null; then
    84              compare_help_and_man "$@" $cmd
    85          fi
    86      done
    87  
    88      rm -f /tmp/${basename}_{help,man}.txt
    89  }
    90  
    91  
    92  compare_help_and_man
    93  
    94  if [ $rc -ne 0 ]; then
    95      cat <<EOF
    96  
    97  **************************
    98  ** INTERPRETING RESULTS **
    99  **************************************************************************
   100  *
   101  * The above results show differences between 'podman --help' and
   102  * podman man pages.
   103  *
   104  * The 'checking:' header indicates the specific command (and possibly
   105  * subcommand) being tested, e.g. podman --help vs docs/source/podman.1.md.
   106  *
   107  * A '-' indicates a subcommand present in 'podman --help' but not the
   108  * corresponding man page.
   109  *
   110  * A '+' indicates a subcommand present in the man page but not --help.
   111  *
   112  **************************************************************************
   113  EOF
   114  fi
   115  
   116  exit $rc