github.com/containers/libpod@v1.9.4-0.20220419124438-4284fd425507/hack/podman-commands.sh (about)

     1  #!/bin/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}/^Flags:/{ok=0}ok { print $1 }' |\
    27          grep .
    28  }
    29  
    30  # Read a list of subcommands from a command's metadoc
    31  function podman_man() {
    32      if [ "$@" = "podman" ]; then
    33          # podman itself.
    34          # This md file has a table of the form:
    35          #   | [podman-cmd(1)\[(podman-cmd.1.md)   | Description ... |
    36          # For all such, print the 'cmd' portion (the one in brackets).
    37          sed -ne 's/^|\s\+\[podman-\([a-z]\+\)(1.*/\1/p' <docs/source/markdown/$1.1.md
    38  
    39          # Special case: there is no podman-help man page, nor need for such.
    40          echo "help"
    41          # Auto-update differs from other commands as it's a single command, not
    42          # a main and sub-command split by a dash.
    43          echo "auto-update"
    44      elif [ "$@" = "podman-image-trust" ]; then
    45          # Special case: set and show aren't actually in a table in the man page
    46          echo set
    47          echo show
    48      else
    49          # podman subcommand.
    50          # Each md file has a table of the form:
    51          #    | cmd | [podman-cmd(1)](podman-cmd.1.md) | Description ... |
    52          # For all such we find, with 'podman- in the second column, print the
    53          # first column (with whitespace trimmed)
    54          awk -F\| '$3 ~ /podman-/ { gsub(" ","",$2); print $2 }' < docs/source/markdown/$1.1.md
    55      fi
    56  }
    57  
    58  # The main thing. Compares help and man page; if we find subcommands, recurse.
    59  rc=0
    60  function compare_help_and_man() {
    61      echo
    62      echo "checking: podman $@"
    63  
    64      # e.g. podman, podman-image, podman-volume
    65      local basename=$(echo podman "$@" | sed -e 's/ /-/g')
    66  
    67      podman_commands "$@" | sort > /tmp/${basename}_help.txt
    68      podman_man $basename | sort > /tmp/${basename}_man.txt
    69  
    70      diff -u /tmp/${basename}_help.txt /tmp/${basename}_man.txt || rc=1
    71  
    72      # Now look for subcommands, e.g. container, image
    73      for cmd in $(< /tmp/${basename}_help.txt); do
    74          usage=$($PODMAN "$@" $cmd --help | grep -A1 '^Usage:' | tail -1)
    75  
    76          # if string ends in '[command]', recurse into its subcommands
    77          if expr "$usage" : '.*\[command\]$' >/dev/null; then
    78              compare_help_and_man "$@" $cmd
    79          fi
    80      done
    81  
    82      rm -f /tmp/${basename}_{help,man}.txt
    83  }
    84  
    85  
    86  compare_help_and_man
    87  
    88  if [ $rc -ne 0 ]; then
    89      cat <<EOF
    90  
    91  **************************
    92  ** INTERPRETING RESULTS **
    93  **************************************************************************
    94  *
    95  * The above results show differences between 'podman --help' and
    96  * podman man pages.
    97  *
    98  * The 'checking:' header indicates the specific command (and possibly
    99  * subcommand) being tested, e.g. podman --help vs docs/source/podman.1.md.
   100  *
   101  * A '-' indicates a subcommand present in 'podman --help' but not the
   102  * corresponding man page.
   103  *
   104  * A '+' indicates a subcommand present in the man page but not --help.
   105  *
   106  **************************************************************************
   107  EOF
   108  fi
   109  
   110  exit $rc