CLI¶
This page documents the CLI for gitversioned.
gitversioned¶
Opinionated PEP 440 Python versioning for Git repos and submodules.
Usage:
Options:
-v, --version: Show the version and exit.--help: Show this message and exit.
Commands:
calculate: Resolve and output only the PEP 440...format: Resolve the version and output the...write: Resolve the version and write output files.init-archive: Initialize git archive fallback metadata...overrides: Run commands under a specific overrides...
gitversioned calculate¶
Resolve and output only the PEP 440 version string.
This command runs version resolution and prints the final calculated version string directly to stdout. It excludes output target and strategy settings.
:param kwargs: Dynamic CLI override arguments mapping to Settings schema fields. :returns: None.
Usage:
Options:
--package-name TEXT: The package name being versioned. Enables automatic package name detection when set to 'auto'. [default: (auto)]--project-root PATH: The absolute path to the root directory of the project.--src-root PATH: The path to the source root directory. Enables automatic source directory fallback detection when set to 'auto'.--build-is-editable: Flag indicating whether the package is built as an editable installation.--overrides TEXT: Override-based settings configurations.--explicit-version TEXT: Explicit version override string. Enables dynamic version resolution from git/files when set to 'auto'. [default: (auto)]--source-type TEXT: Priority order of sources to query for version information.--version-source-file TEXT: Path to a file containing the version string. Set to None to disable. [default: (version.txt)]--version-source-archive TEXT: Path to a git-archive export info file used when Git is unavailable. Set to None to disable. [default: (.git_archival.txt)]--version-source-function TEXT: A string pointing to a module and function (e.g. 'module:func') to resolve the version. Set to None to disable.--regex-version TEXT: Regular expression patterns to parse and validate the explicit version string.--regex-tag TEXT: Regular expression patterns to extract semantic versioning from Git tags.--regex-branch TEXT: Regular expression patterns to extract semantic versioning from the current Git branch name.--regex-commit TEXT: Regular expression patterns to extract semantic versioning from Git commit messages.--regex-file TEXT: Regular expression patterns to parse version strings from version source files.--regex-archive TEXT: Regular expression patterns to parse Git metadata from git-archive export files.--version-type [auto|release|dev|pre|alpha|nightly|post]: The type of version format to generate (e.g. 'release', 'dev', or 'auto'). [default: (auto)]--version-standard [pep440|semver2]: The standard formatting layout (PEP 440 or SemVer 2) to use for version normalization. [default: (pep440)]--auto-increment TEXT: Target increment mapping to apply when ahead of the latest release tag.--format-main TEXT: Format string for the main semantic version segment. [default: ({version.major}.{version.minor}.{version.micro})]--format-dev TEXT: Format string for development builds. [default: (dev{ref.timestamp:%Y%m%d}+{ref.short_sha})]--format-pre TEXT: Format string for pre-release or alpha builds. [default: (a{ref.timestamp:%Y%m%d})]--format-post TEXT: Format string for post-release builds. [default: (post{ref.distance_from_head})]--dirty-ignore TEXT: List of file paths and directories to ignore when checking if the repository is dirty.--help: Show this message and exit.
gitversioned format¶
Resolve the version and output the formatted strategy templates.
This command prints the rendered content from the configured version output strategies to stdout. It excludes final file write targets from the options.
:param kwargs: Dynamic CLI override arguments mapping to Settings schema fields. :returns: None.
Usage:
Options:
--package-name TEXT: The package name being versioned. Enables automatic package name detection when set to 'auto'. [default: (auto)]--project-root PATH: The absolute path to the root directory of the project.--src-root PATH: The path to the source root directory. Enables automatic source directory fallback detection when set to 'auto'.--build-is-editable: Flag indicating whether the package is built as an editable installation.--overrides TEXT: Override-based settings configurations.--explicit-version TEXT: Explicit version override string. Enables dynamic version resolution from git/files when set to 'auto'. [default: (auto)]--source-type TEXT: Priority order of sources to query for version information.--version-source-file TEXT: Path to a file containing the version string. Set to None to disable. [default: (version.txt)]--version-source-archive TEXT: Path to a git-archive export info file used when Git is unavailable. Set to None to disable. [default: (.git_archival.txt)]--version-source-function TEXT: A string pointing to a module and function (e.g. 'module:func') to resolve the version. Set to None to disable.--regex-version TEXT: Regular expression patterns to parse and validate the explicit version string.--regex-tag TEXT: Regular expression patterns to extract semantic versioning from Git tags.--regex-branch TEXT: Regular expression patterns to extract semantic versioning from the current Git branch name.--regex-commit TEXT: Regular expression patterns to extract semantic versioning from Git commit messages.--regex-file TEXT: Regular expression patterns to parse version strings from version source files.--regex-archive TEXT: Regular expression patterns to parse Git metadata from git-archive export files.--version-type [auto|release|dev|pre|alpha|nightly|post]: The type of version format to generate (e.g. 'release', 'dev', or 'auto'). [default: (auto)]--version-standard [pep440|semver2]: The standard formatting layout (PEP 440 or SemVer 2) to use for version normalization. [default: (pep440)]--auto-increment TEXT: Target increment mapping to apply when ahead of the latest release tag.--format-main TEXT: Format string for the main semantic version segment. [default: ({version.major}.{version.minor}.{version.micro})]--format-dev TEXT: Format string for development builds. [default: (dev{ref.timestamp:%Y%m%d}+{ref.short_sha})]--format-pre TEXT: Format string for pre-release or alpha builds. [default: (a{ref.timestamp:%Y%m%d})]--format-post TEXT: Format string for post-release builds. [default: (post{ref.distance_from_head})]--dirty-ignore TEXT: List of file paths and directories to ignore when checking if the repository is dirty.--output-strategies TEXT: Output strategies for formatting the version file.--help: Show this message and exit.
gitversioned write¶
Resolve the version and write output files.
This command writes the rendered version templates to the configured file paths and prints a confirmation of the successfully written path to stdout.
:param kwargs: Dynamic CLI override arguments mapping to Settings schema fields. :returns: None.
Usage:
Options:
--package-name TEXT: The package name being versioned. Enables automatic package name detection when set to 'auto'. [default: (auto)]--project-root PATH: The absolute path to the root directory of the project.--src-root PATH: The path to the source root directory. Enables automatic source directory fallback detection when set to 'auto'.--build-is-editable: Flag indicating whether the package is built as an editable installation.--overrides TEXT: Override-based settings configurations.--explicit-version TEXT: Explicit version override string. Enables dynamic version resolution from git/files when set to 'auto'. [default: (auto)]--source-type TEXT: Priority order of sources to query for version information.--version-source-file TEXT: Path to a file containing the version string. Set to None to disable. [default: (version.txt)]--version-source-archive TEXT: Path to a git-archive export info file used when Git is unavailable. Set to None to disable. [default: (.git_archival.txt)]--version-source-function TEXT: A string pointing to a module and function (e.g. 'module:func') to resolve the version. Set to None to disable.--regex-version TEXT: Regular expression patterns to parse and validate the explicit version string.--regex-tag TEXT: Regular expression patterns to extract semantic versioning from Git tags.--regex-branch TEXT: Regular expression patterns to extract semantic versioning from the current Git branch name.--regex-commit TEXT: Regular expression patterns to extract semantic versioning from Git commit messages.--regex-file TEXT: Regular expression patterns to parse version strings from version source files.--regex-archive TEXT: Regular expression patterns to parse Git metadata from git-archive export files.--version-type [auto|release|dev|pre|alpha|nightly|post]: The type of version format to generate (e.g. 'release', 'dev', or 'auto'). [default: (auto)]--version-standard [pep440|semver2]: The standard formatting layout (PEP 440 or SemVer 2) to use for version normalization. [default: (pep440)]--auto-increment TEXT: Target increment mapping to apply when ahead of the latest release tag.--format-main TEXT: Format string for the main semantic version segment. [default: ({version.major}.{version.minor}.{version.micro})]--format-dev TEXT: Format string for development builds. [default: (dev{ref.timestamp:%Y%m%d}+{ref.short_sha})]--format-pre TEXT: Format string for pre-release or alpha builds. [default: (a{ref.timestamp:%Y%m%d})]--format-post TEXT: Format string for post-release builds. [default: (post{ref.distance_from_head})]--dirty-ignore TEXT: List of file paths and directories to ignore when checking if the repository is dirty.--output TEXT: The target output path to write the generated version file. [default: (version.py)]--output-strategies TEXT: Output strategies for formatting the version file.--help: Show this message and exit.
gitversioned init-archive¶
Initialize git archive fallback metadata template files in the repository.
Creates .git_archival.txt and appends export-subst to .gitattributes.
Usage:
Options:
--help: Show this message and exit.
gitversioned overrides¶
Run commands under a specific overrides context.
Usage:
Arguments:
OVERRIDES: The overrides name context to use. [required]
Options:
--help: Show this message and exit.
Commands:
calculate: Resolve and output only the PEP 440...format: Resolve the version and output formatted...write: Resolve the version and write output files...
gitversioned overrides calculate¶
Resolve and output only the PEP 440 version string for overrides.
Usage:
Options:
--package-name TEXT: The package name being versioned. Enables automatic package name detection when set to 'auto'. [default: (auto)]--project-root PATH: The absolute path to the root directory of the project.--src-root PATH: The path to the source root directory. Enables automatic source directory fallback detection when set to 'auto'.--build-is-editable: Flag indicating whether the package is built as an editable installation.--overrides TEXT: Override-based settings configurations.--explicit-version TEXT: Explicit version override string. Enables dynamic version resolution from git/files when set to 'auto'. [default: (auto)]--source-type TEXT: Priority order of sources to query for version information.--version-source-file TEXT: Path to a file containing the version string. Set to None to disable. [default: (version.txt)]--version-source-archive TEXT: Path to a git-archive export info file used when Git is unavailable. Set to None to disable. [default: (.git_archival.txt)]--version-source-function TEXT: A string pointing to a module and function (e.g. 'module:func') to resolve the version. Set to None to disable.--regex-version TEXT: Regular expression patterns to parse and validate the explicit version string.--regex-tag TEXT: Regular expression patterns to extract semantic versioning from Git tags.--regex-branch TEXT: Regular expression patterns to extract semantic versioning from the current Git branch name.--regex-commit TEXT: Regular expression patterns to extract semantic versioning from Git commit messages.--regex-file TEXT: Regular expression patterns to parse version strings from version source files.--regex-archive TEXT: Regular expression patterns to parse Git metadata from git-archive export files.--version-type [auto|release|dev|pre|alpha|nightly|post]: The type of version format to generate (e.g. 'release', 'dev', or 'auto'). [default: (auto)]--version-standard [pep440|semver2]: The standard formatting layout (PEP 440 or SemVer 2) to use for version normalization. [default: (pep440)]--auto-increment TEXT: Target increment mapping to apply when ahead of the latest release tag.--format-main TEXT: Format string for the main semantic version segment. [default: ({version.major}.{version.minor}.{version.micro})]--format-dev TEXT: Format string for development builds. [default: (dev{ref.timestamp:%Y%m%d}+{ref.short_sha})]--format-pre TEXT: Format string for pre-release or alpha builds. [default: (a{ref.timestamp:%Y%m%d})]--format-post TEXT: Format string for post-release builds. [default: (post{ref.distance_from_head})]--dirty-ignore TEXT: List of file paths and directories to ignore when checking if the repository is dirty.--help: Show this message and exit.
gitversioned overrides format¶
Resolve the version and output formatted strategy templates for overrides.
Usage:
Options:
--package-name TEXT: The package name being versioned. Enables automatic package name detection when set to 'auto'. [default: (auto)]--project-root PATH: The absolute path to the root directory of the project.--src-root PATH: The path to the source root directory. Enables automatic source directory fallback detection when set to 'auto'.--build-is-editable: Flag indicating whether the package is built as an editable installation.--overrides TEXT: Override-based settings configurations.--explicit-version TEXT: Explicit version override string. Enables dynamic version resolution from git/files when set to 'auto'. [default: (auto)]--source-type TEXT: Priority order of sources to query for version information.--version-source-file TEXT: Path to a file containing the version string. Set to None to disable. [default: (version.txt)]--version-source-archive TEXT: Path to a git-archive export info file used when Git is unavailable. Set to None to disable. [default: (.git_archival.txt)]--version-source-function TEXT: A string pointing to a module and function (e.g. 'module:func') to resolve the version. Set to None to disable.--regex-version TEXT: Regular expression patterns to parse and validate the explicit version string.--regex-tag TEXT: Regular expression patterns to extract semantic versioning from Git tags.--regex-branch TEXT: Regular expression patterns to extract semantic versioning from the current Git branch name.--regex-commit TEXT: Regular expression patterns to extract semantic versioning from Git commit messages.--regex-file TEXT: Regular expression patterns to parse version strings from version source files.--regex-archive TEXT: Regular expression patterns to parse Git metadata from git-archive export files.--version-type [auto|release|dev|pre|alpha|nightly|post]: The type of version format to generate (e.g. 'release', 'dev', or 'auto'). [default: (auto)]--version-standard [pep440|semver2]: The standard formatting layout (PEP 440 or SemVer 2) to use for version normalization. [default: (pep440)]--auto-increment TEXT: Target increment mapping to apply when ahead of the latest release tag.--format-main TEXT: Format string for the main semantic version segment. [default: ({version.major}.{version.minor}.{version.micro})]--format-dev TEXT: Format string for development builds. [default: (dev{ref.timestamp:%Y%m%d}+{ref.short_sha})]--format-pre TEXT: Format string for pre-release or alpha builds. [default: (a{ref.timestamp:%Y%m%d})]--format-post TEXT: Format string for post-release builds. [default: (post{ref.distance_from_head})]--dirty-ignore TEXT: List of file paths and directories to ignore when checking if the repository is dirty.--output-strategies TEXT: Output strategies for formatting the version file.--help: Show this message and exit.
gitversioned overrides write¶
Resolve the version and write output files for overrides.
Usage:
Options:
--package-name TEXT: The package name being versioned. Enables automatic package name detection when set to 'auto'. [default: (auto)]--project-root PATH: The absolute path to the root directory of the project.--src-root PATH: The path to the source root directory. Enables automatic source directory fallback detection when set to 'auto'.--build-is-editable: Flag indicating whether the package is built as an editable installation.--overrides TEXT: Override-based settings configurations.--explicit-version TEXT: Explicit version override string. Enables dynamic version resolution from git/files when set to 'auto'. [default: (auto)]--source-type TEXT: Priority order of sources to query for version information.--version-source-file TEXT: Path to a file containing the version string. Set to None to disable. [default: (version.txt)]--version-source-archive TEXT: Path to a git-archive export info file used when Git is unavailable. Set to None to disable. [default: (.git_archival.txt)]--version-source-function TEXT: A string pointing to a module and function (e.g. 'module:func') to resolve the version. Set to None to disable.--regex-version TEXT: Regular expression patterns to parse and validate the explicit version string.--regex-tag TEXT: Regular expression patterns to extract semantic versioning from Git tags.--regex-branch TEXT: Regular expression patterns to extract semantic versioning from the current Git branch name.--regex-commit TEXT: Regular expression patterns to extract semantic versioning from Git commit messages.--regex-file TEXT: Regular expression patterns to parse version strings from version source files.--regex-archive TEXT: Regular expression patterns to parse Git metadata from git-archive export files.--version-type [auto|release|dev|pre|alpha|nightly|post]: The type of version format to generate (e.g. 'release', 'dev', or 'auto'). [default: (auto)]--version-standard [pep440|semver2]: The standard formatting layout (PEP 440 or SemVer 2) to use for version normalization. [default: (pep440)]--auto-increment TEXT: Target increment mapping to apply when ahead of the latest release tag.--format-main TEXT: Format string for the main semantic version segment. [default: ({version.major}.{version.minor}.{version.micro})]--format-dev TEXT: Format string for development builds. [default: (dev{ref.timestamp:%Y%m%d}+{ref.short_sha})]--format-pre TEXT: Format string for pre-release or alpha builds. [default: (a{ref.timestamp:%Y%m%d})]--format-post TEXT: Format string for post-release builds. [default: (post{ref.distance_from_head})]--dirty-ignore TEXT: List of file paths and directories to ignore when checking if the repository is dirty.--output TEXT: The target output path to write the generated version file. [default: (version.py)]--output-strategies TEXT: Output strategies for formatting the version file.--help: Show this message and exit.