# Mercurial build integration

## SYNOPSIS

```groovy

plugins {
    id 'org.implab.gradle-mercurial' version '1.0'
}

mercurial {
    releaseBookmark = 'prod'

    preReleasePolicy { it
        // this is the default behaviour
        .addPatch(1)
        .withPreRelease('snapshot')
        .withMeta('changeset')
    }

    // get version from repository and apply it to the project
    applyVersioningPolicy()
}

```

## DESCRIPTION

### `semver(versionString)`

Parses the specified version string and returns the semantic version object

### `mercurial(Closure configure)`

The extension added by the plugin to the project. Apply this plugin to the
root project and use the `mercurial { ... }` section to configure the
versioning.

See the description below for more details about settings.

#### `hgCmd`

The command which will be executed to perform the mercurial commands.
The default value is `hg`.

#### `outputCharset`

The charset for the `hgCmd` output, this property defaults
to the default charset of the operating system.

#### `hg(...args)`

Executes the mercurial command, returns the command output as text.

#### `workspaceInfo` (read-only)

Returns the information about current workspace, see description
below for details.

#### `workspaceVersion`

Returns the semantic version obtained from the repository. Querying
this property will lead querying the workspace info.

#### `applyVersioningPolicy()`

Reads the workspace information and sets the version of the project
according to settings.

If the version was specified using properties, then the specified
version will take preceding over the calculated one.

#### `preReleasePolicy(Closure<SemVersion> config)`

The closure which is used to calculate the version of the project
when the current commit isn't marked with a version tag.

The default behaviour is to increment the patch version and
to set the pre-release suffix to `'snapshot'`.

### `WorkspaceInfo`

This class encapsulates information about the current workspace.
All properties are read-only.

#### `versionTag`

The original version tag from the repository before parsing.

#### `changeSet`

The changeset id of the current workspace.

#### `versionDistance`

The distance in commits to the versionTag

#### `branch`

The name of the current sources branch.

#### `isDirty`

This flag indicates uncommited changes to the workspace. This flag is useful
to control some pipelines which run locally on developer machines.

## TASKS

### `release`

Marks this commit with current version and pre-release suffix removed and
moves the `release` bookmark to it.

### `staging`

Marks this commit with current version and moves the `staging` bookmark to it.

### `printVersion`

Prints the current version.