// file      : bpkg/pkg-status.cli
// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

include <bpkg/configuration.cli>;

"\section=1"
"\name=bpkg-pkg-status"
"\summary=print package status"

namespace bpkg
{
  {
    "<options> <pkg> <ver>",

    "\h|SYNOPSIS|

     \c{\b{bpkg pkg-status}|\b{status} [<options>] <pkg>[/<ver>]...}

     \h|DESCRIPTION|

     The \cb{pkg-status} command prints the status of the specified packages
     or, if <ver> is specified, package versions. Note that the status is
     written to \cb{STDOUT}, not \cb{STDERR}.

     The status output format is regular. If several packages were specified,
     then each line starts with the package name (and version, if specified)
     followed by '\cb{:}'. Then comes one of the following status words:

     \dl|

     \li|\cb{unknown}

         Package is not part of the configuration nor available from any of the
         repositories.|

     \li|\cb{available}

         Package is not part of the configuration but is available from one of
         the repositories.|

     \li|\cb{fetched}

         Package is part of the configuration and is fetched.|

     \li|\cb{unpacked}

         Package is part of the configuration and is unpacked.|

     \li|\cb{configured}

         Package is part of the configuration and is configured.|

     \li|\cb{broken}

         Package is part of the configuration and is broken (broken packages
         can only be purged; see \l{bpkg-pkg-purge(1)}).||

     If only the package name was specified without the package version, then
     the \cb{available} status word is followed by the list of available
     versions.

     Similarly, if only the package name was specified, then the \cb{fetched},
     \cb{unpacked}, \cb{configured}, and \cb{broken} status words are followed
     by the version of the package. After the package version, these status
     words may be followed by one or more sub-status words. Currently, these
     can be \cb{hold_package} (package should not be automatically dropped) and
     \cb{hold_version} (package should not be automatically upgraded). Finally,
     if only the package name was specified and newer versions are available
     from some of the repositories, then the sub-status word is followed
     by '\cb{;}', the \cb{available} status word, and the list of newer
     versions.

     Below are some examples, assuming the configuration has \cb{libfoo}
     \cb{1.0.0} configured and held as well as \cb{libfoo} \cb{1.1.0} and
     \cb{1.1.1} available from a repository.

     \
     bpkg status libbar
     unknown

     bpkg status libbar/1.0.0
     unknown

     bpkg status libfoo/1.0.0
     configured hold_package

     bpkg status libfoo/1.1.0
     available

     bpkg status libfoo
     configured 1.0.0 hold_package; available 1.1.0 1.1.1

     bpkg status libfoo/1.0.0 libbar
     libfoo/1.0.0: configured hold_package
     libbar: unknown
     \

     Assuming now that we dropped \cb{libfoo} from the configuration:

     \
     bpkg status libfoo/1.0.0
     unknown

     bpkg status libfoo/1.1.0
     available

     bpkg status libfoo
     available 1.1.0 1.1.1
     \
     "
  }

  class pkg_status_options: configuration_options
  {
    "\h|PKG-STATUS OPTIONS|"
  };
}