poetry-version

Output the current version

$ poetry version [[-s|--short]]

$ poetry version [stage]

$ poetry version --next-phase

$ poetry version [stage] --dry-run

poetry version [new-version] [-s|--short] [--dry-run] [--absolute]

new-version
    The version string to set (e.g., '1.0.1') or a rule to derive the new version (e.g., 'major', 'minor', 'patch', 'prerelease', 'premajor', 'preminor', 'prepatch').

-s, --short
    Outputs only the version number, without any additional text or context.

--dry-run
    Performs all actions without actually writing changes to the pyproject.toml file, reporting only the new version that would be set.

--absolute
    Displays the version along with the absolute path to the pyproject.toml file where the version is defined.

poetry version is a crucial command within the Poetry ecosystem, designed for managing a Python project's version.
It primarily serves two functions: displaying the current version and updating it.

When invoked without arguments, it simply outputs the version number defined in the pyproject.toml file. This is particularly useful for scripting or quickly checking the current state of a project.

The command's power lies in its ability to increment the version based on predefined rules like major, minor, patch, or even prerelease. It automatically updates the pyproject.toml file, ensuring consistency across your project's metadata.

It also supports setting an absolute version string. This functionality is vital for maintaining semantic versioning practices, facilitating release management, and ensuring that dependencies correctly reference your project's evolution.
It's an indispensable tool for any Poetry-managed project, streamlining the versioning workflow.

poetry version requires that your project is initialized with a pyproject.toml file containing a [tool.poetry] section with a 'version' key.
If the 'version' key is missing or the file is not found, the command will fail.
When using rules like 'major' or 'patch', it adheres strictly to Semantic Versioning 2.0.0 (semver) principles. Non-semver compatible versions may not be correctly incremented by these rules.

The new-version rules (major, minor, patch, prerelease, etc.) strictly follow Semantic Versioning 2.0.0 principles. Understanding semver is crucial for effective use of these versioning rules for project releases.

The command directly reads and writes the 'version' key within the [tool.poetry] section of your project's pyproject.toml file, making it the single source of truth for the project's version.

The Poetry project, initiated by Sébastien Eustace, emerged as a modern Python dependency manager and packaging tool. From its inception, the ability to manage project versions was a core requirement, making poetry version an integral command.

It has evolved to provide robust support for semantic versioning, reflecting the best practices in software development for clear and consistent release cycles. Its introduction streamlined the process of bumping versions manually, which previously often involved direct edits to configuration files or custom scripts.

poetry build(1), poetry publish(1), poetry init(1), poetry new(1)