# NAME

`bdep-release` – manage project's version during release

# SYNOPSIS

`bdep release [options] [prj-spec]`

`prj-spec = --directory|-d prj-dir | pkg-spec
pkg-spec = (pkg | (--directory|-d pkg-dir))...`

# DESCRIPTION

The `release` command manages the project's version during the release. Specifically, it first changes the snapshot version to the corresponding release version in each project package's `manifest` file, commits these changes (unless `--no-commit` is specified), tags this commit (unless `--no-tag` is specified), and, if `--push` is specified, pushes the changes to the remote. Unless `--no-open` is specified, the `release` command then opens the next development cycle by changing the version to a snapshot, committing these changes (unless `--no-commit` is specified), and, if `--push` is specified, pushing them to the remote. Note that committing, tagging, and pushing is currently only supported for `git(1)` project repositories.

The `release` command can also be used to release a new package revision by passing the `--revision` option. In this mode `release` increments the current version's revision component in each project package's `manifest` file, commits these changes (unless `--no-commit` is specified), tags this commit (unless `--no-tag` is specified), and, if `--push` is specified, pushes the changes to the remote. In this mode `release` can be optionally instructed to update an existing tag for the current version to point to the latest revision (`--current-tag=update`) or to remove it (`--current-tag=remove`).

When releasing a revision, the project's repository index is expected to already contain other changes since for a revision all the associated changes, including to version, must belong to a single commit. Alternatively, a revision can be released by amending one or more existing commits using the `--amend` and `--squash` options. In this case the index may still contain additional changes but is not required to.

The `release` command also has a number of continue modes that allow the completion of steps that were previously suppressed with the `--no-*` options in the above main modes. These are `--tag` which tags the release commit and, if `--push` is specified, pushes it to the remote as well as `--open` which performs the opening of the next development cycle as described above.

In all the modes that perform a commit, if the project's repository index already contains other changes, then the commit message is automatically opened for editing unless `--no-edit` is specified. The editing of the commit message in the absence of other changes can be requested with the `--edit` option.

Normally, `release` operates on all the packages in a project. If no project directory is specified, then the current working directory is assumed and all the packages are released, even if the current directory is a package directory. If, however, one or more package directories are specified explicitly with `--directory|-d`, then `release` assumes you know what you are doing and only releases these packages. All the packages being released must have the same version but may have different revisions.

# RELEASE OPTIONS

`--revision`
  Release a new package revision instead of a new version.
`--no-commit`
  Don't commit the changes. Implies `--no-tag` and, in the version release mode, `--no-open`.
`--no-tag`
  Don't tag the release commit. Tagging can be performed later using the `--tag` mode option.
`--tag`
  Tag the already released version instead of releasing a new one.
`--current-tag` `action`
  Specify what to do with an existing tag for the current version when tagging a new revision. Valid values for this option are `keep` (default), `update`, and `remove`.
`--push`
  Push the committed changes and tags to the remote.
`--show-push`
  Print the push command instead of executing it. This allows examining the committed changes and tags before pushing them to the remote. Note that the command is printed to `stdout`.
`--no-open`
  Don't open the next development cycle. Opening can be performed later using the `--open` mode option.
`--open`
  Open the next development cycle instead of releasing a new version.
`--amend`
  Release a revision by amending the latest commit instead of making a new one.
`--squash` `num`
  Release a revision by squashing the specified number of previous commits and then amending the result. Requires the `--amend` option to be specified.
`--alpha`
  Release an alpha instead of the final version.
`--beta`
  Release a beta version instead of the final version.
`--minor`
  Release the next minor version instead of the current patch.
`--major`
  Release the next major version instead of the current minor or patch.
`--open-beta`
  Open the development cycle with the next beta version.
`--open-patch`
  Open the development cycle with the next patch version. This is the default if the current patch version is not `0` (bugfix release series).
`--open-minor`
  Open the development cycle with the next minor version. This is the default if the current patch version is `0` (feature release series).
`--open-major`
  Open the development cycle with the next major version.
`--open-base` `version`
  Open the development cycle with the specified version. The base version should be in the `major.minor`.`patch` form with the opened version becoming `major.minor.patch-a.0.z`.
`--edit`
  Open the commit message for editing.
`--no-edit`
  Don't open the commit message for editing.
`--force` `check`
  Force releasing, disabling the specified check. Repeat this option to disable multiple checks.
`--yes`|`-y`
  Don't prompt for confirmation before releasing.
`--directory`|`-d` `dir`
  Assume project/package is in the specified directory rather than in the current working directory.

# COMMON OPTIONS

The common options are summarized below with a more detailed description available in `bdep-common-options(1)`.

`-v`
  Print essential underlying commands being executed.
`-V`
  Print all underlying commands being executed.
`--quiet`|`-q`
  Run quietly, only printing error messages.
`--verbose` `level`
  Set the diagnostics verbosity to `level` between 0 and 6.
`--stdout-format` `format`
  Representation format to use for printing to `stdout`.
`--jobs`|`-j` `num`
  Number of jobs to perform in parallel.
`--progress`
  Display progress indicators for long-lasting operations, such as network transfers, building, etc.
`--no-progress`
  Suppress progress indicators for long-lasting operations, such as network transfers, building, etc.
`--diag-color`
  Use color in diagnostics.
`--no-diag-color`
  Don't use color in diagnostics.
`--bpkg` `path`
  The package manager program to be used for build configuration management.
`--bpkg-option` `opt`
  Additional option to be passed to the package manager program.
`--build` `path`
  The build program to be used to build packages.
`--build-option` `opt`
  Additional option to be passed to the build program.
`--curl` `path`
  The curl program to be used for network operations.
`--curl-option` `opt`
  Additional option to be passed to the curl program.
`--offline`
  Do not attempt to download resources (packages, repository metadata, etc), instead taking them from the local fetch cache if available and failing otherwise.
`--no-fetch-cache`
  Disable local caching of download resources (packages, repository metadata, etc).
`--fetch-cache` `mode`
  Comma-separated list of local fetch cache modes.
`--fetch-cache-session` `id`
  The local fetch cache session.
`--sqlite-synchronous` `mode`
  Filesystem synchronization mode for the project SQLite database.
`--pager` `path`
  The pager program to be used to show long text.
`--pager-option` `opt`
  Additional option to be passed to the pager program.
`--options-file` `file`
  Read additional options from `file`.
`--default-options` `dir`
  The directory to load additional default options files from.
`--no-default-options`
  Don't load default options files.

# DEFAULT OPTIONS FILES

See `bdep-default-options-files(1)` for an overview of the default options files. For the `release` command the search start directory is the project directory. The following options files are searched for in each directory and, if found, loaded in the order listed:

    bdep.options
    bdep-release.options
    bdep-release-{version|revision|open|tag}.options # (mode-dependent)

The following `release` command options cannot be specified in the default options files:

    --directory|-d
    --revision
    --open
    --tag

# BUGS

Send bug reports to the users@build2.org mailing list.