dart_bump

dart_bump is a Dart automation tool for safe, consistent patch version bumps in Dart projects.

It integrates with Git and OpenAI to:

• Extract the current Git diff
• Generate a structured CHANGELOG.md entry
• Increment the patch version in pubspec.yaml
• Update API version constants
• Keep releases consistent and low-effort

Designed for automation, CI usage, and developer tooling.

---

Features

• 🔢 Automatic patch version bump (x.y.z → x.y.(z+1))
• 🧩 Git diff extraction
• 📝 AI-generated, structured CHANGELOG entries
• 🔧 API version synchronization
• ♻️ Fully overridable logging
• 🗂️ Support for extra files with custom version regex patterns

---

Usage

Programmatic

import 'dart:io';
import 'package:dart_bump/dart_bump.dart';

void main() async {
  final bump = DartBump(
    Directory.current,
    changeLogGenerator: OpenAIChangeLogGenerator(
      apiKey: Platform.environment['OPENAI_API_KEY'],
    ),
  );

  final result = await bump.bump();

  if (result == null) {
    print('ℹ️  Nothing to bump — version is already up to date.');
    return;
  }

  print('🎯 New version: ${result.version}');

  final changelog = result.changeLogEntry;
  if (changelog != null && changelog.isNotEmpty) {
    print('📝 Generated CHANGELOG entry:');
    print('───────────────────────────────');
    print(changelog);
    print('───────────────────────────────');
  }
}

---

CLI

Activate the dart_bump command:

dart pub global activate dart_bump

Run dart_bump to automatically bump the patch version, update CHANGELOG.md, and synchronize API constants:

dart_bump [<project-dir>] [--api-key <key>] [--extra-file <file=regexp>]

Options:

• <project-dir>: Path to the Dart project 📁 (default: current directory)
• --api-key <key>: OpenAI API key 🔑 (optional; defaults to OPENAI_API_KEY environment variable)
• --extra-file <file=regexp>: Specify extra files to update with a Dart RegExp 🗂️ (multiple allowed)
• --diff-tag <tag>: Generate diff from the given Git tag to HEAD 🏷 (accepts tag last)
• --diff-context <n>: Number of context lines for git diff 📄 (default: 10)
• --major: Bump major version (breaking changes) 🧱
• --minor: Bump minor version (new features) 🧩
• --patch: Bump patch version (bug fixes) 🩹 (default)
• -n, --dry-run: Preview changes only — no files will be modified 🧪 (default: false)
• -h, --help: Show help message ❓

Example usage:

# Bump the current project using the OpenAI API key from environment
dart_bump

# Bump a project in another directory
dart_bump /path/to/project

# Bump with an explicit OpenAI API key
dart_bump --api-key YOUR_API_KEY

# Bump a project in another directory, update an extra file,
# and provide an API key to generate a CHANGELOG entry:
dart_bump /path/to/backend-dir \
  --extra-file "lib/src/api.dart=version\\s*=\\s*'([^']+)'\\s*;" \
  --api-key sk-xyzkey

• The dart_bump CLI can be customized with one or more --extra-file entries, allowing different projects to update additional files with the new version automatically.

---

How It Works

1. Verifies the project is a Git repository ✔️
2. Runs git diff to extract changes 🧩
3. Sends the patch to ChatGPT to generate a CHANGELOG entry 🧠
4. Increments the patch version in pubspec.yaml 🔢
5. Prepends the entry to CHANGELOG.md 📝
6. Updates extra files (if present) 📄

All steps fail fast and log clearly.

---

Requirements

• Git installed and available in PATH
• Dart 3.x+
• OpenAI API key (optional but recommended)

If no API key is provided, version bumping still works, but the CHANGELOG entry will be a placeholder.

---

Logging

All output goes through:

void log(String message)

Override it to:

• Integrate with your logger
• Silence output
• Redirect logs to CI systems

---

Issues & Feature Requests

Please report issues and request features via the issue tracker.

---

Author

Graciliano M. Passos: gmpassos@GitHub.

---

License

Dart free & open-source license.