﻿---
title: changelog remove
description: Remove changelog YAML files from a directory. You can use either profile-based removal or raw filter flags: Profile-based: docs-builder changelog remove...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2841/cli/release/changelog-remove
---

# changelog remove
Remove changelog YAML files from a directory.
You can use either profile-based removal or raw filter flags:
- **Profile-based**: `docs-builder changelog remove <profile> <version|promotion-report>` — uses the same `bundle.profiles` configuration as [`changelog bundle`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2841/cli/release/changelog-bundle) to determine which changelogs to remove.
- **Raw flags**: `docs-builder changelog remove --products "..." ` (or `--prs`, `--issues`, `--all`) — specify the filter directly.

Before deleting anything, the command checks whether any of the matching files are referenced by unresolved bundles, to prevent silently breaking the `{changelog}` directive.
For more context, go to [Create and bundle changelogs > Remove changelog files](/elastic/docs-builder/pull/2841/contribute/changelog#changelog-remove).

## Usage

```sh
docs-builder  changelog remove [arguments...] [options...] [-h|--help]
```


## Arguments

You can use either profile-based removal (for example, `remove elasticsearch-release 9.2.0`) or raw flags (`remove --all`).
These arguments apply to profile-based removal:
<definitions>
  <definition term="[0] <string?>">
    Profile name from `bundle.profiles` in the changelog configuration file.
  </definition>
  <definition term="For example, "elasticsearch-release".">
  </definition>
  <definition term="When specified, the second argument is the version or promotion report URL.">
  </definition>
  <definition term="Mutually exclusive with --all, --products, --prs, and --issues.">
  </definition>
  <definition term="[1] <string?>">
    Version number or promotion report URL or path.
  </definition>
  <definition term="For example, "9.2.0" or "https://buildkite.../promotion-report.html".">
  </definition>
</definitions>


## Options

<definitions>
  <definition term="--all">
    Remove all changelog files in the directory.
  </definition>
  <definition term="Exactly one filter option must be specified: --all, --products, --prs, or --issues.">
  </definition>
  <definition term="Cannot be combined with a profile argument.">
  </definition>
  <definition term="--bundles-dir <string?>">
    Optional: Override the directory scanned for bundles during the dependency check.
  </definition>
  <definition term="When not specified, the directory is discovered automatically from config or fallback paths.">
  </definition>
  <definition term="--config <string?>">
    Optional: Path to the changelog configuration file.
  </definition>
  <definition term="Defaults to docs/changelog.yml.">
  </definition>
  <definition term="--directory <string?>">
    Optional: The directory that contains the changelog YAML files.
  </definition>
  <definition term="When not specified, uses bundle.directory from the changelog configuration if set, otherwise the current directory.">
  </definition>
  <definition term="--dry-run">
    Print the files that would be removed and any bundle dependency conflicts, without deleting anything.
  </definition>
  <definition term="Valid in both profile and raw mode.">
  </definition>
  <definition term="--force">
    Proceed with removal even when files are referenced by unresolved bundles.
  </definition>
  <definition term="Emits a warning per dependency instead of blocking.">
  </definition>
  <definition term="Valid in both profile and raw mode.">
  </definition>
  <definition term="--issues <string[]?>">
    Filter by issue URLs or numbers (comma-separated), or a path to a newline-delimited file containing issue URLs or numbers.
  </definition>
  <definition term="Can be specified multiple times.">
  </definition>
  <definition term="Exactly one filter option must be specified: --all, --products, --prs, or --issues.">
  </definition>
  <definition term="Cannot be combined with a profile argument.">
  </definition>
  <definition term="--owner <string?>">
    The GitHub repository owner, which is required when pull requests or issues are specified as numbers.
  </definition>
  <definition term="--products <List<ProductInfo>?>">
    Filter by products in format `"product target lifecycle, ..."`
  </definition>
  <definition term="Exactly one filter option must be specified: --all, --products, --prs, or --issues.">
  </definition>
  <definition term="Cannot be combined with a profile argument.">
  </definition>
  <definition term="All three parts (product, target, lifecycle) are required but can be wildcards (*). Multiple comma-separated values are combined with OR: a changelog is removed if it matches any of the specified product/target/lifecycle combinations. For example:">
  </definition>
</definitions>

- `"elasticsearch 9.3.0 ga"` — exact match
- `"cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"` — remove changelogs for either cloud-serverless 2025-12-02 ga or cloud-serverless 2025-12-06 beta
- `"elasticsearch * *"` — all elasticsearch changelogs
- `"* 9.3.* *"` — any product with a target starting with `9.3.`
- `"* * *"` — all changelogs (equivalent to `--all`)

<definitions>
  <definition term="--prs <string[]?>">
    Filter by pull request URLs or numbers (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers.
  </definition>
  <definition term="Can be specified multiple times.">
  </definition>
  <definition term="Exactly one filter option must be specified: --all, --products, --prs, or --issues.">
  </definition>
  <definition term="Cannot be combined with a profile argument.">
  </definition>
  <definition term="--repo <string?>">
    The GitHub repository name, which is required when pull requests or issues are specified as numbers.
  </definition>
</definitions>


## Profile-based removal

When a `changelog.yml` configuration file defines `bundle.profiles`, you can use those same profiles with `changelog remove` to remove exactly the changelogs that would be included in a matching bundle.
Only the `products` field from a profile is used for removal. The `output` and `hide_features` fields are bundle-specific and are ignored.
For example, if your configuration file defines:
```yaml
bundle:
  profiles:
    elasticsearch-release:
      products: "elasticsearch {version} {lifecycle}"
      output: "elasticsearch-{version}.yaml"
```

You can remove the matching changelogs with:
```sh
docs-builder changelog remove elasticsearch-release 9.2.0 --dry-run
```

This removes changelogs for `elasticsearch 9.2.0 ga` — the same set that `docs-builder changelog bundle elasticsearch-release 9.2.0` would include.
You can also pass a promotion report URL or file path as the second argument, in which case the command removes changelogs whose PR URLs appear in the report:
```sh
docs-builder changelog remove elasticsearch-release https://buildkite.../promotion-report.html
```