package-versioner 0.7.1 → 0.8.1

package/README.md

@@ -58,6 +58,9 @@ npx package-versioner -t @scope/package-a,@scope/package-b
 # Perform a dry run: calculates version, logs actions, but makes no file changes or Git commits/tags
 npx package-versioner --dry-run
 
+# Only use reachable tags (Git-semantic mode, no fallback to unreachable tags)
+npx package-versioner --strict-reachable
+
 # Output results as JSON (useful for CI/CD scripts)
 npx package-versioner --json
 
@@ -67,6 +70,26 @@ npx package-versioner --dry-run --json
 
 **Note on Targeting:** Using the `-t` flag creates package-specific tags (e.g., `@scope/package-a@1.2.0`) but *not* a global tag (like `v1.2.0`). If needed, create the global tag manually in your CI/CD script after this command.
 
+### Git Tag Reachability
+
+By default, `package-versioner` intelligently handles Git tag reachability to provide the best user experience:
+
+- **Default behavior**: Uses reachable tags when available, but falls back to the latest repository tag if needed (common in feature branches)
+- **Strict mode (`--strict-reachable`)**: Only uses tags reachable from the current commit, following strict Git semantics
+
+This is particularly useful when working on feature branches that have diverged from the main branch where newer tags exist. The tool will automatically detect the Git context and provide helpful guidance:
+
+```bash
+# On a feature branch with unreachable tags
+npx package-versioner --dry-run
+# Output: "No tags reachable from current branch 'feature-x'. Using latest repository tag v1.2.3 as version base."
+# Tip: Consider 'git merge main' or 'git rebase main' to include tag history in your branch.
+
+# Force strict Git semantics
+npx package-versioner --dry-run --strict-reachable
+# Output: Uses only reachable tags, may result in "No reachable tags found"
+```
+
 ## JSON Output
 
 When using the `--json` flag, normal console output is suppressed and the tool outputs a structured JSON object that includes information about the versioning operation.
@@ -92,23 +115,24 @@ For detailed examples of how to use this in CI/CD pipelines, see [CI/CD Integrat
 
 ## Configuration
 
-Customize behavior by creating a `version.config.json` file in your project root:
+Customize behaviour by creating a `version.config.json` file in your project root:
 
 ```json
 {
   "preset": "angular",
   "versionPrefix": "v",
-  "tagTemplate": "${prefix}${version}",
-  "packageTagTemplate": "${packageName}@${prefix}${version}",
+  "tagTemplate": "${packageName}@${prefix}${version}",
+  "packageSpecificTags": true,
   "commitMessage": "chore: release ${packageName}@${version} [skip ci]",
   "updateChangelog": true,
   "changelogFormat": "keep-a-changelog",
+  "strictReachable": false,
   "synced": true,
   "skip": [
     "docs",
     "e2e"
   ],
-  "packages": ["packages/*"],
+  "packages": ["@mycompany/*"],
   "mainPackage": "primary-package",
   "cargo": {
     "enabled": true,
@@ -126,6 +150,7 @@ Customize behavior by creating a `version.config.json` file in your project root
 - `commitMessage`: Template for commit messages (default: "chore(release): ${version}")
 - `updateChangelog`: Whether to automatically update changelogs (default: true)
 - `changelogFormat`: Format for changelogs - "keep-a-changelog" or "angular" (default: "keep-a-changelog")
+- `strictReachable`: Only use reachable tags, no fallback to unreachable tags (default: false)
 - `cargo`: Options for Rust projects:
   - `enabled`: Whether to handle Cargo.toml files (default: true)
   - `paths`: Directories to search for Cargo.toml files (optional)
@@ -133,13 +158,92 @@ Customize behavior by creating a `version.config.json` file in your project root
 #### Monorepo-Specific Options
 - `synced`: Whether all packages should be versioned together (default: true)
 - `skip`: Array of package names to exclude from versioning
-- `packages`: Glob patterns for package discovery (e.g., ["packages/*"])
+- `packages`: Array of package names or patterns to target for versioning. Supports exact names, scope wildcards, and global wildcards (e.g., ["@scope/package-a", "@scope/*", "*"])
 - `mainPackage`: Package name whose commit history should drive version determination
-- `packageTagTemplate`: Template for package-specific Git tags (default: "${packageName}@${prefix}${version}")
+- `packageSpecificTags`: Whether to enable package-specific tagging behaviour (default: false)
 - `updateInternalDependencies`: How to update internal dependencies ("patch", "minor", "major", or "inherit")
 
 For more details on CI/CD integration and advanced usage, see [CI/CD Integration](./docs/CI_CD_INTEGRATION.md).
 
+### Package Targeting
+
+The `packages` configuration option allows you to specify which packages should be processed for versioning. It supports several pattern types:
+
+#### Exact Package Names
+```json
+{
+  "packages": ["@mycompany/core", "@mycompany/utils", "standalone-package"]
+}
+```
+
+#### Scope Wildcards
+Target all packages within a specific scope:
+```json
+{
+  "packages": ["@mycompany/*"]
+}
+```
+
+#### Global Wildcard
+Target all packages in the workspace:
+```json
+{
+  "packages": ["*"]
+}
+```
+
+#### Mixed Patterns
+Combine different pattern types:
+```json
+{
+  "packages": ["@mycompany/*", "@utils/logger", "legacy-package"]
+}
+```
+
+**Note**: Package discovery is handled by your workspace configuration (pnpm-workspace.yaml, package.json workspaces, etc.). The `packages` option only filters which discovered packages to process.
+
+### Package-Specific Tagging
+
+The `packageSpecificTags` option controls whether the tool creates and searches for package-specific Git tags:
+
+- **When `false` (default)**: Creates global tags like `v1.2.3` and searches for the latest global tag
+- **When `true`**: Creates package-specific tags like `@scope/package-a@v1.2.3` and searches for package-specific tags
+
+This option works in conjunction with `tagTemplate` to control tag formatting. The `tagTemplate` is used for all tag creation, with the `packageSpecificTags` boolean controlling whether the `${packageName}` variable is populated:
+
+- When `packageSpecificTags` is `false`: The `${packageName}` variable is empty, so templates should use `${prefix}${version}`
+- When `packageSpecificTags` is `true`: The `${packageName}` variable contains the package name
+
+**Examples:**
+
+For single-package repositories or synced monorepos:
+```json
+{
+  "packageSpecificTags": true,
+  "tagTemplate": "${packageName}@${prefix}${version}"
+}
+```
+Creates tags like `my-package@v1.2.3`
+
+For global versioning:
+```json
+{
+  "packageSpecificTags": false,
+  "tagTemplate": "${prefix}${version}"
+}
+```
+Creates tags like `v1.2.3`
+
+**Important Notes:**
+- In **synced mode** with a single package, `packageSpecificTags: true` will use the package name even though all packages are versioned together
+- In **synced mode** with multiple packages, package names are not used regardless of the setting
+- In **async mode**, each package gets its own tag when `packageSpecificTags` is enabled
+
+With package-specific tagging enabled, the tool will:
+1. Look for existing tags matching the configured pattern for each package
+2. Create new tags using the same pattern when releasing
+3. Fall back to global tag lookup if no package-specific tags are found
+
 ## How Versioning Works
 
 `package-versioner` determines the next version based on your configuration (`version.config.json`). The two main approaches are: