// file      : bdep/sync.cli
// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

include <bdep/project.cli>;

"\section=1"
"\name=bdep-sync"
"\summary=synchronize project and build configurations"

namespace bdep
{
  {
    "<options>
     <prj-spec> <prj-dir>
     <pkg-spec> <pkg-dir>
     <cfg-spec> <cfg-name> <cfg-dir>
     <dep-spec> <pkg> <ver>",

    "\h|SYNOPSIS|

     \c{\b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>]\n
        \b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>] \ \b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}\n
        \b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>] [\b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}]\n
        \ \ \ \ \ \ \ \ \ \ <dep-spec>...
        }

     \c{<dep-spec> = <pkg>[\b{/}<ver>]\n
        <cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
        <pkg-spec> = (\b{--directory}|\b{-d} <pkg-dir>)... | <prj-spec>\n
        <prj-spec> = \b{--directory}|\b{-d} <prj-dir>}

     \h|DESCRIPTION|

     The \cb{sync} command synchronizes a project with its build
     configurations. The first form (no arguments nor \cb{--upgrade} or
     \cb{--patch} are specified) upgrades the project packages to the latest
     iteration, adjusts their dependencies according to the latest manifest
     information, and updates the lockfile. If no project or package directory
     is specified, then the current working directory is assumed. If no
     configuration is specified, then the default configuration is assumed. See
     \l{bdep-projects-configs(1)} for details on specifying projects and
     configurations.

     The second form (no arguments but either \cb{--upgrade} or \cb{--patch}
     is specified), in addition to the first form's functionality, also
     upgrades or patches immediate (by default or if
     \c{\b{--immediate}|\b{-i}} is specified) or all (if
     \c{\b{--recursive}|\b{-r}} is specified) dependencies of the specified
     project packages.

     The third form (one or more arguments are specified), in addition to the
     first form's functionality, also upgrades (by default or if
     \cb{--upgrade} is specified) or patches (if \cb{--patch} is specified)
     the specified dependencies. If \c{\b{--immediate}|\b{-i}} or
     \c{\b{--recursive}|\b{-r}} is specified, then it also upgrades or patches
     the immediate or all dependencies of the specified dependencies,
     respectively. Alternative to \cb{--upgrade} and \cb{--patch}, the desired
     upgrade (or downgrade) version can be specified explicitly.

     Note also that \c{\b{--immediate}|\b{-i}} or \c{\b{--recursive}|\b{-r}}
     can only be specified with an explicit \cb{--upgrade} or \cb{--patch}.

     \h|EXAMPLES|

     As an example, consider project \cb{prj} with two packages, \cb{foo}
     and \cb{libfoo}:

     \
     prj/
    ├── foo/
    └── libfoo/
     \

     Assuming \cb{foo} and \cb{libfoo} have been initialized in the default
     build configuration, the following invocations illustrate the common
     \cb{sync} use cases (the current working directory is shown before the
     shell prompt).


     Synchronize \cb{foo} and \cb{libfoo} with the default configuration:

     \
     prj/$ bdep sync
     \

     The same (all initialized packages in a project are always synchronized
     at once):

     \
     prj/$ cd foo
     foo/$ bdep sync
     \

     Add a dependency on \cb{libx} with \cb{sync} fetching and configuring a
     suitable version:

     \
     foo/$ edit manifest  # Add 'depends: libx >= 1.0.0'
     foo/$ bdep sync
     \

     Upgrade all the immediate dependencies of \cb{foo}:

     \
     foo/$ bdep sync -u
     \

     Upgrade all the dependencies of all the initialzied packages in a
     project recursively:

     \
     foo/$ cd ../
     prj/$ bdep sync -u -r
     \

     Upgrade \cb{libx} to the latest version:

     \
     prj/$ bdep sync libx
     \

     Upgrade \cb{libx} and its immediate dependecies to the latest version:

     \
     prj/$ bdep sync -i libx
     \

     Upgrade \cb{libx} to the latest patch version:

     \
     prj/$ bdep sync -p libx
     \

     Upgrade \cb{libx} and all its dependecies recursively to the latest patch
     version.

     \
     prj/$ bdep sync -p -r libx
     \

     Upgrade \cb{libx} to version \cb{1.2.3}.

     \
     prj/$ bdep sync libx/1.2.3
     \

     Upgrade \cb{libx} to version \cb{1.2.3} and patch all its dependecies,
     recursively:

     \
     prj/$ bdep sync -p -r libx/1.2.3
     \

     "
  }

  // Note that not all project/configuration options are valid for all
  // subcommands.
  //
  class cmd_sync_options: project_options
  {
    "\h|SYNC OPTIONS|"

    bool --upgrade|-u
    {
      "Upgrade dependencies to the latest available version that satisfies
       all the constraints."
    }

    bool --patch|-p
    {
      "Upgrade dependencies to the latest available patch version that
       satisfies all the constraints."
    }

    bool --immediate|-i
    {
      "Also upgrade or patch immediate dependencies."
    }

    bool --recursive|-r
    {
      "Also upgrade or patch all dependencies, recursively."
    }

    bool --fetch|-f
    {
      "Perform the \cb{fetch} command prior to synchronization."
    }

    bool --fetch-full|-F
    {
      "Perform the \cb{fetch --full} command prior to synchronization."
    }

    bool --yes|-y
    {
      "Don't prompt for confirmation when up/down-grading dependencies."
    }
  };
}