// file      : bpkg/pkg-fetch.cli
// license   : MIT; see accompanying LICENSE file

include <bpkg/configuration.cli>;

"\section=1"
"\name=bpkg-pkg-fetch"
"\summary=fetch package archive"

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

    "\h|SYNOPSIS|

     \c{\b{bpkg pkg-fetch} [<options>] (<pkg>\b{/}<ver> | \b{--existing|-e} <file>)}

     \h|DESCRIPTION|

     The \cb{pkg-fetch} command fetches the archive for the specified package
     name and version from one of the archive-based repositories
     (\l{bpkg-rep-add(1)}). The resulting package state is \cb{fetched}
     (\l{bpkg-pkg-status(1)}).

     If the \cb{--replace|-r} option is specified, then \cb{pkg-fetch} will
     replace the archive of a package that is already in the \cb{fetched} or
     \cb{unpacked} state. Otherwise, \cb{pkg-fetch} expects the package to not
     exist in the configuration.

     If the \cb{--existing|-e} option is used, then instead of the name and
     version arguments, \cb{pkg-fetch} expects a local path to an existing
     package archive. In this case, \cb{bpkg} will use the archive in place,
     without copying it into the configuration directory. Also, unless the
     \cb{--purge|-p} option is specified, \cb{bpkg} will not attempt to remove
     this archive when the package is later purged with the
     \l{bpkg-pkg-purge(1)} command."
  }

  class pkg_fetch_options: configuration_options
  {
    "\h|PKG-FETCH OPTIONS|"

    bool --replace|-r
    {
      "Replace the archive if the package is already fetched or unpacked."
    }

    bool --existing|-e
    {
      "Treat the argument as an existing package archive path rather than
       the package name/version to fetch."
    }

    bool --purge|-p
    {
      "Remove the existing package archive when the package is purged."
    }
  };

  "
   \h|DEFAULT OPTIONS FILES|

   See \l{bpkg-default-options-files(1)} for an overview of the default
   options files. For the \cb{pkg-fetch} command the search start
   directory is the configuration directory. The following options files are
   searched for in each directory and, if found, loaded in the order listed:

   \
   bpkg.options
   bpkg-pkg-fetch.options
   \

   The following \cb{pkg-fetch} command options cannot be specified in the
   default options files:

   \
   --directory|-d
   --purge|-p
   \
  "
}