changelog remove cli command

docs-builder changelog remove \
  [<profile>] \
  [<profile-arg>] \
  [<profile-report>] \
  [options]
		

Remove changelog YAML files from a directory.

Two mutually exclusive modes are available:

• Profile-based: docs-builder changelog remove <profile> <version|promotion-report> — uses the same bundle.profiles configuration as changelog bundle to determine which changelogs to remove.
• Option-based: docs-builder changelog remove --products "..." (or --prs, --issues, --all, --release-version, --report) — specify the filter directly.

Before deleting anything, the command checks whether any matching files are referenced by unresolved bundles, to prevent silently breaking the {changelog} directive.

For more context, go to Bundle changelogs > Remove changelog files.

Behaviour flags:

--dry-run — Print the files that would be removed without deleting them. Valid in both profile and raw mode. --force — Proceed with removal even when files are referenced by unresolved bundles. Emits warnings instead of errors for each dependency. Valid in both profile and raw mode.

<profile> string

Optional: Profile name from bundle.profiles in config (for example, "elasticsearch-release"). When specified, the second argument is the version or promotion report URL.

<profile-arg> string

Optional: Version number or promotion report URL/path when using a profile (for example, "9.2.0" or "https://buildkite.../promotion-report.html")

<profile-report> string

Optional: Promotion report or URL list file when also providing a version. When provided, the second argument must be a version string and this is the PR/issue filter source.

--[no-]all

Remove all changelogs in the directory. Exactly one filter option must be specified: --all, --products, --prs, --issues, or --report.

Default: false

--bundles-dir string

Optional: Override the directory that is scanned for bundles during the dependency check. Auto-discovered from config or fallback paths when not specified.

Constraints: symbolic links not allowed, supports ~ home expansion

--config string

Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml'

Constraints: symbolic links not allowed, must exist, extensions: yml, yaml, supports ~ home expansion

--directory string

Optional: Directory containing changelog YAML files. Uses config bundle.directory or defaults to current directory

Constraints: symbolic links not allowed, supports ~ home expansion

--[no-]dry-run

Print the files that would be removed without deleting them. Valid in both profile and raw mode. (preview changes without applying them)

Default: false

--[no-]force

Proceed with removal even when files are referenced by unresolved bundles. Emits warnings instead of errors for each dependency. Valid in both profile and raw mode. (pass to skip the confirmation prompt)

Default: false

--issues string[]

Filter by issue URLs (comma-separated) or a path to a newline-delimited file containing fully-qualified GitHub issue URLs. Can be specified multiple times.

Repeatable: pass --issues multiple times to supply more than one value

--owner string

Optional: GitHub repository owner, which is used when PRs or issues are specified as numbers or when using --release-version. Falls back to bundle.owner in changelog.yml when not specified. If that value is also absent, "elastic" is used.

--products string

Filter by products in format "product target lifecycle, ..." (for example, "elasticsearch 9.3.0 ga"). All three parts are required but can be wildcards (*).

--prs string[]

Filter by pull request URLs (comma-separated) or a path to a newline-delimited file containing fully-qualified GitHub PR URLs. Can be specified multiple times.

Repeatable: pass --prs multiple times to supply more than one value

--release-version string

GitHub release tag to use as a filter source (for example, "v9.2.0" or "latest"). Fetches the release, parses PR references from the release notes, and removes changelogs whose PR URLs match — equivalent to passing the PR list using --prs.

--repo string

GitHub repository name, which is used when PRs or issues are specified as numbers or when --release-version is used. Falls back to bundle.repo in changelog.yml when not specified. If that value is also absent, the product ID is used.

--report string

Optional (option-based mode only): URL or file path to a promotion report. Extracts PR URLs and uses them as the filter. Mutually exclusive with --all, --products, --prs, --release-version, and --issues.

-l --log-level enum

Minimum log level.

Values: trace, debug, information, warning, error, critical, none

Default: information

-c --config-source enum

Override the configuration source: local, remote

Values: local, remote, embedded

--[no-]skip-private-repositories

Skip cloning private repositories

Both modes use the same ordered fallback to locate changelog YAML files and existing bundles.

Changelog files directory:

Bundles directory (scanned during the dependency check):

Setting bundle.directory and bundle.output_directory in changelog.yml is recommended so you don't need to rely on running the command from a specific directory.

Exactly one filter must be specified: --all, --products, --prs, --issues, --release-version, or --report.

# Preview what would be removed (dry run)
docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run

# Remove by GitHub release tag
docs-builder changelog remove \
  --release-version v1.34.0 \
  --repo apm-agent-dotnet --owner elastic

# Preview using the latest release
docs-builder changelog remove --release-version latest --dry-run
		

The --products filter supports wildcards:

• "elasticsearch 9.3.0 ga" — exact match
• "elasticsearch * *" — all elasticsearch changelogs
• "* 9.3.* *" — any product with a target starting with 9.3.
• "* * *" — all changelogs (equivalent to --all)

When changelog.yml defines bundle.profiles, use those same profiles with changelog remove to remove exactly the changelogs that would be included in a matching bundle.

Profile-based commands discover the changelog configuration automatically: they look for changelog.yml in the current directory, then docs/changelog.yml.

Refer to Bundle changelogs > Remove changelog files for examples.