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, --files) — specify the filter directly.

Bundles are self-contained (every entry is embedded inline), so removing changelog source files never affects existing bundles or the {changelog} directive. The command deletes matching files without any bundle dependency check.

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.

<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, URL list file, or changelog path list file when also providing a version. When provided, the second argument must be a version string and this is the filter source.

--[no-]all

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

Default: false

--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

--directory string

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

Constraints: symbolic links not allowed

--[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

--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

--files string[]

Filter by changelog YAML paths (comma-separated), or a path to a newline-delimited file containing changelog paths. Can be specified multiple times. Not supported in profile-based commands; pass a path list file as a positional argument instead.

Repeatable: pass --files 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, --issues, and --files.

-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

-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.

Setting bundle.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, --report, or --files.

# 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

# Remove an explicit list of changelog files
docs-builder changelog remove --files "./docs/changelog/a.yaml,./docs/changelog/b.yaml" --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.