{"id":25221720,"url":"https://github.com/devsetgo/bumpcalver","last_synced_at":"2026-03-11T17:02:54.697Z","repository":{"id":257200160,"uuid":"857594290","full_name":"devsetgo/bumpcalver","owner":"devsetgo","description":"Simple Calendar versioning","archived":false,"fork":false,"pushed_at":"2025-02-01T21:22:42.000Z","size":1372,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T22:23:31.360Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devsetgo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-15T04:29:46.000Z","updated_at":"2025-02-01T21:22:40.000Z","dependencies_parsed_at":"2024-09-15T09:20:28.793Z","dependency_job_id":"4fa7582d-007f-471f-9e82-a73996d4cf0f","html_url":"https://github.com/devsetgo/bumpcalver","commit_stats":null,"previous_names":["devsetgo/dsg-calver"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devsetgo%2Fbumpcalver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devsetgo%2Fbumpcalver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devsetgo%2Fbumpcalver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devsetgo%2Fbumpcalver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devsetgo","download_url":"https://codeload.github.com/devsetgo/bumpcalver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238202145,"owners_count":19433177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-10T22:53:05.819Z","updated_at":"2026-03-11T17:02:54.690Z","avatar_url":"https://github.com/devsetgo.png","language":"Python","readme":"[![PyPI version fury.io](https://badge.fury.io/py/bumpcalver.svg)](https://pypi.python.org/pypi/bumpcalver/)\n[![Downloads](https://static.pepy.tech/badge/bumpcalver)](https://pepy.tech/project/bumpcalver)\n[![Downloads](https://static.pepy.tech/badge/bumpcalver/month)](https://pepy.tech/project/bumpcalver)\n[![Downloads](https://static.pepy.tech/badge/bumpcalver/week)](https://pepy.tech/project/bumpcalver)\n\nSupport Python Versions\n\n![Static Badge](https://img.shields.io/badge/Python-3.13%20%7C%203.12%20%7C%203.11%20%7C%203.10%20%7C%203.9-blue)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Coverage Status](https://raw.githubusercontent.com/devsetgo/bumpcalver/refs/heads/main/coverage-badge.svg)](./reports/coverage/index.html)\n[![Tests Status](https://raw.githubusercontent.com/devsetgo/bumpcalver/refs/heads/main/tests-badge.svg)](./reports/coverage/index.html)\n\nCI/CD Pipeline:\n\n[![Testing - Main](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml/badge.svg?branch=main)](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml)\n[![Testing - Dev](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml/badge.svg?branch=dev)](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml)\n\nSonarCloud:\n\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=devsetgo_bumpcalver\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=devsetgo_bumpcalver\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=devsetgo_bumpcalver\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=devsetgo_bumpcalver\u0026metric=reliability_rating)](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=devsetgo_bumpcalver\u0026metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver)\n\n# BumpCalver CLI Documentation\n\n## Note\nThis project should be consider in beta as it could have bugs due to being only a few months old.\n\n## Overview\n\nThe **BumpCalver CLI** is a command-line interface for calendar-based version bumping. It automates the process of updating version strings in your project's files based on the current date and build count. Additionally, it can create Git tags and commit changes automatically. The CLI is highly configurable via a `pyproject.toml` file and supports various customization options to fit your project's needs.\n\n---\n\n## Table of Contents\n- Documentation Site: [BumpCalver CLI](https://devsetgo.github.io/bumpcalver/)\n\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n- [Command-Line Usage](#command-line-usage)\n  - [Options](#options)\n- [Error Handling](#error-handling)\n- [Support](#support)\n\n---\n\n## Installation\n\nTo install the BumpCalver CLI, you can add it to your project's dependencies. If it's packaged as a Python module, you might install it via:\n\n```bash\npip install bumpcalver\n```\n\n*Note: Replace the installation command with the actual method based on how the package is distributed.*\n\n---\n\n## Getting Started\n\n1. **Configure Your Project**: Create or update the `pyproject.toml` file in your project's root directory to include the `[tool.bumpcalver]` section with your desired settings.\n\n2. **Run the CLI**: Use the `bumpcalver` command with appropriate options to bump your project's version.\n\nExample:\n\n```bash\nbumpcalver --build --git-tag --auto-commit\n```\n\n---\n\n## Configuration\n\nThe BumpCalver CLI relies on a `pyproject.toml` configuration file located at the root of your project. This file specifies how versioning should be handled, which files to update, and other settings.\n\nAs an alternative, you can use configuration file named `bumpcalver.toml`. The CLI will look for this file if `pyproject.toml` is not found.\n\n### Configuration Options\n\n- `version_format` (string): Format string for the version. Should include `{current_date}` and `{build_count}` placeholders.\n- `date_format` (string): Format string for the date. Supports various combinations of year, month, day, quarter, and week.\n- `timezone` (string): Timezone for date calculations (e.g., `UTC`, `America/New_York`).\n- `file` (list of tables): Specifies which files to update and how to find the version string.\n  - `path` (string): Path to the file to be updated.\n  - `file_type` (string): Type of the file (e.g., `python`, `toml`, `yaml`, `json`, `xml`, `dockerfile`, `makefile`, `properties`, `env`, `setup.cfg`).\n  - `variable` (string, optional): The variable name that holds the version string in the file.\n  - `pattern` (string, optional): A regex pattern to find the version string.\n  - `version_standard` (string, optional): The versioning standard to follow (e.g., `python` for PEP 440).\n- `git_tag` (boolean): Whether to create a Git tag with the new version.\n- `auto_commit` (boolean): Whether to automatically commit changes when creating a Git tag.\n\n### Example Configuration\n\n```toml\n[tool.bumpcalver]\nversion_format = \"{current_date}-{build_count:03}\"\ndate_format = \"%y.%m.%d\"\ntimezone = \"America/New_York\"\ngit_tag = true\nauto_commit = true\n\n[[tool.bumpcalver.file]]\npath = \"pyproject.toml\"\nfile_type = \"toml\"\nvariable = \"project.version\"\nversion_standard = \"python\"\n\n[[tool.bumpcalver.file]]\npath = \"examples/makefile\"\nfile_type = \"makefile\"\nvariable = \"APP_VERSION\"\nversion_standard = \"default\"\n\n[[tool.bumpcalver.file]]\npath = \"examples/dockerfile\"\nfile_type = \"dockerfile\"\nvariable = \"arg.VERSION\"\nversion_standard = \"default\"\n\n[[tool.bumpcalver.file]]\npath = \"examples/dockerfile\"\nfile_type = \"dockerfile\"\nvariable = \"env.APP_VERSION\"\nversion_standard = \"default\"\n\n[[tool.bumpcalver.file]]\npath = \"examples/p.py\"\nfile_type = \"python\"\nvariable = \"__version__\"\nversion_standard = \"python\"\n\n[[tool.bumpcalver.file]]\npath = \"sonar-project.properties\"\nfile_type = \"properties\"\nvariable = \"sonar.projectVersion\"\nversion_standard = \"default\"\n\n[[tool.bumpcalver.file]]\npath = \".env\"\nfile_type = \"env\"\nvariable = \"VERSION\"\nversion_standard = \"default\"\n\n[[tool.bumpcalver.file]]\npath = \"setup.cfg\"\nfile_type = \"setup.cfg\"\nvariable = \"metadata.version\"\nversion_standard = \"python\"\n```\n\n### Date Format Examples\n\nThe `date_format` option allows you to customize the date format used in version strings. Here are some examples of how to format dates:\n\n- `%Y.%m.%d` - Full year, month, and day (e.g., `2024.12.25`)\n- `%y.%m.%d` - Year without century, month, and day (e.g., `24.12.25`)\n- `%y.Q%q` - Year and quarter (e.g., `24.Q1`)\n- `%y.%m` - Year and month (e.g., `24.12`)\n- `%y.%j` - Year and day of the year (e.g., `24.001` for January 1st, 2024)\n- `%Y.%j` - Full year and day of the year (e.g., `2024.001` for January 1st, 2024)\n- `%Y.%m` - Full year and month (e.g., `2024.12`)\n- `%Y.Q%q` - Full year and quarter (e.g., `2024.Q1`)\n\nRefer to the [Python datetime documentation](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) for more format codes.\n\n---\n\n## Supported File Types\n\nBumpCalver supports version management for the following file types:\n\n### Core File Types\n- **`python`** - Python files with version variables (e.g., `__version__ = \"1.0.0\"`)\n- **`toml`** - TOML configuration files (e.g., `pyproject.toml`)\n- **`yaml`** - YAML configuration files\n- **`json`** - JSON configuration files (e.g., `package.json`)\n- **`xml`** - XML configuration files\n\n### Infrastructure Files\n- **`dockerfile`** - Docker files with ARG or ENV variables\n- **`makefile`** - Makefiles with version variables\n\n### Configuration Files\n- **`properties`** - Java-style properties files (e.g., `sonar-project.properties`)\n  - Format: `key=value`\n  - Example: `sonar.projectVersion=2025.02.02`\n- **`env`** - Environment variable files (e.g., `.env`)\n  - Format: `KEY=value` or `KEY=\"value\"`\n  - Example: `VERSION=2025.02.02`\n- **`setup.cfg`** - Python setup configuration files\n  - Supports both dot notation (`metadata.version`) and simple keys (`version`)\n  - Example: `version = 2025.02.02` in `[metadata]` section\n\n---\n\n## Command-Line Usage\n\nThe CLI provides several options to customize the version bumping process.\n\n```bash\nUsage: bumpcalver [OPTIONS]\n\nOptions:\n  --beta                      Use beta versioning.\n  --rc                        Use rc versioning.\n  --release                   Use release versioning.\n  --custom TEXT               Add custom suffix to version.\n  --build                     Use build count versioning.\n  --timezone TEXT             Timezone for date calculations (default: value\n                              from config or America/New_York).\n  --git-tag / --no-git-tag    Create a Git tag with the new version.\n  --auto-commit / --no-auto-commit\n                              Automatically commit changes when creating a Git\n                              tag.\n  --undo                      Undo the last version bump operation.\n  --undo-id TEXT              Undo a specific operation by ID.\n  --list-history              List recent operations that can be undone.\n  --help                      Show this message and exit.\n```\n\n### Version Bump Options\n\n- `--beta`: Adds `.beta` suffix to the version.\n- `--rc`: Adds `.rc` suffix to the version.\n- `--release`: Adds `.release` suffix to the version.\n- `--custom TEXT`: Adds a custom suffix to the version.\n- `--build`: Increments the build count based on the current date.\n- `--timezone`: Overrides the timezone specified in the configuration.\n- `--git-tag` / `--no-git-tag`: Forces Git tagging on or off, overriding the configuration.\n- `--auto-commit` / `--no-auto-commit`: Forces auto-commit on or off, overriding the configuration.\n\n### Undo Options\n\nBumpCalver includes powerful undo functionality to revert version changes:\n\n- `--undo`: Undo the most recent version bump operation.\n- `--undo-id TEXT`: Undo a specific operation by its unique ID.\n- `--list-history`: Show recent version bump operations that can be undone.\n\n**Note**: Undo options cannot be combined with version bump options.\n\n---\n\n## Examples\n\n### Basic Version Bump\n\nTo bump the version using the current date and build count:\n\n```bash\nbumpcalver --build\n```\n\n### Beta Versioning\n\nTo create a beta version:\n\n```bash\nbumpcalver --build --beta\n```\n\n### Specifying Timezone\n\nTo use a specific timezone:\n\n```bash\nbumpcalver --build --timezone Europe/London\n```\n\n### Creating a Git Tag with Auto-Commit\n\nTo bump the version, commit changes, and create a Git tag:\n\n```bash\nbumpcalver --build --git-tag --auto-commit\n```\n\n### Undo Operations\n\nView recent version bump operations:\n\n```bash\nbumpcalver --list-history\n```\n\nUndo the last version bump:\n\n```bash\nbumpcalver --undo\n```\n\nUndo a specific operation by ID:\n\n```bash\nbumpcalver --undo-id 20251012_143015_123\n```\n\n### Safety Net Workflow\n\nUse undo functionality as a safety net during development:\n\n```bash\n# Make experimental version bump\nbumpcalver --custom \"experimental\"\n\n# Test your changes...\n\n# If tests pass, make official version\nbumpcalver --undo  # Undo experimental version\nbumpcalver --build --git-tag --auto-commit  # Official version\n\n# If tests fail, just undo\nbumpcalver --undo  # Back to original state\n```\n\nFor complete undo documentation, see [Undo Docs](https://devsetgo.github.io/bumpcalver/latest/undo.md).\n\n---\n\n## Documentation\n\nFor comprehensive information about BumpCalver, check out our documentation:\n\n- **[QuickStart Guide](https://devsetgo.github.io/bumpcalver/latest/quickstart.md)** - Get started with BumpCalver quickly\n- **[Calendar Versioning Guide](https://devsetgo.github.io/bumpcalver/latest/calendar-versioning-guide.md)** - Comprehensive guide to calendar versioning patterns, real-world examples, and best practices\n- **[Development Guide](https://devsetgo.github.io/bumpcalver/latest/development-guide.md)** - How to contribute to the project, development setup, testing procedures, and PR guidelines\n- **[Undo Operations](https://devsetgo.github.io/bumpcalver/latest/undo.md)** - How to revert version changes\n- **[Versioning Strategies](https://devsetgo.github.io/bumpcalver/latest/versioning.md)** - Different approaches to version management\n\nFor the full documentation site, visit: [BumpCalver CLI Documentation](https://devsetgo.github.io/bumpcalver/)\n\n---\n\n## Error Handling\n\n- **Unknown Timezone**: If an invalid timezone is specified, the default timezone (`America/New_York`) is used, and a warning is printed.\n- **File Not Found**: If a specified file is not found during version update, an error message is printed.\n- **Invalid Build Count**: If the existing build count in a file is invalid, it resets to `1`, and a warning is printed.\n- **Git Errors**: Errors during Git operations are caught, and an error message is displayed.\n- **Malformed Configuration**: If the `pyproject.toml` file is malformed, an error is printed, and the program exits.\n\n---\n\n## Support\n\nFor issues or questions, please open an issue on the project's repository.\n\n---\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevsetgo%2Fbumpcalver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevsetgo%2Fbumpcalver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevsetgo%2Fbumpcalver/lists"}