Cider (CI for Dart. Efficient Release)
A command-line utility to automate package maintenance. Manipulates the changelog and pubspec.yaml.
This tool assumes that the changelog:
- is called
- is sitting in the project root folder
- strictly follows the Changelog format
- uses basic markdown (no HTML and complex formatting supported)
It also assumes that your project follows Semantic Versioning v2.0.0.
pub global activate cider
Cider configuration is stored in
pubspec.yaml under the key
cider: link_template: tag: https://github.com/example/project/releases/tag/%tag% # initial release link template diff: https://github.com/example/project/compare/%from%...%to% # subsequent releases link template
%tag% placeholders will be replaced with the corresponding version tags.
Cider may be run from the project root or from any directory within.
In the latter case, it will try to detect the project root automatically
by going up the filesystem tree until it finds a directory containing
You can override this behavior by passing the
cider --project-root=/path/to/my/project version
These commands manipulate
Adds a new line to the
Unreleased section of the changelog
cider log <type> <description>
- type is one of:
- description is a markdown text line
cider log changed 'New turbo V6 engine installed' cider log added 'Support for rocket fuel and kerosene' cider log fixed 'Wheels falling off sporadically'
Releasing the unreleased changes
Takes all changes from the
Unreleased section on the changelog and creates a new release under the current version in
cider release [options]
--dateto provide the release date (the default is today).
Cider will automatically generate the diff links in the changelog if the diff link template is found in the config.
Printing the list of changes in the given version
Prints the corresponding section from
CHANGELOG.md in markdown format. This command is read-only.
cider describe [<version>] [options]
- version is an existing version from the changelog. If not specified, the
Unreleasedsection will be used.
--only-bodywill skip the header and the link part of the changelog section.
Listing all versions in the changelog
Prints all versions from the changelog, highest to lowest.
cider list [options]
-y- includes yanked versions.
-u- prints "Unreleased" in the top of the version list if there are unreleased changes.
These commands affect the
version line in
pubspec.yaml. If applied successfully, Cider will print the resulting
Printing the current project version
Prints the current version from
pubspec.yaml. This command is read-only.
Setting version to an arbitrary value
Sets the version in
pubspec.yaml to the one provided. The new version must be semver-compatible.
cider version <new_version>
- new_version new value, must be semver-compatible
|Version before||Command||Version after|
Yanking/unyanking a version
The Changelog defines yanked releases as version that are pulled (withdrawn) due to a serious bug or security issue.
According to the Changelog, a yanked release should be marked with a
[YANKED] tag in the changelog file.
To mark a version as yanked, run the following command:
cider yank <version>
To unyank a version, run the following command:
cider unyank <version>
Bumping the project version
Bumps the corresponding part of the project version according to semver.
cider bump <part> [options]
- part can be any of the following:
release(promotes the version to a release, removing the pre-release part)
--keep-buildwill retain the existing build part.
--bump-buildwill increment the build part (see below).
--build=<value>will set the build part to the given value. This is useful when build is a not a simple numeric value, e.g. a timestamp.
--pre=<prefix>sets the prerelease prefix.
When bumping the
build parts, Cider will look for the rightmost dot-separated identifier. If the
identifier is an integer, it will be incremented stripping the leading zeroes. Otherwise, Cider will append
.1 to the
Remember that according to semver v2,
build is considered metadata and is ignored when determining version
|Version before||Command||Version after|
|64||Usage error, e.g. invalid arguments.|
|65||Data error, e.g. missing or invalid project files.|
|70||Software error. If you see this, you might want to open an issue.|