﻿---
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/2842/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/2842/cli/release/changelog-bundle) to determine which changelogs to remove.
- **Option-based**: `docs-builder changelog remove --products "..." ` (or `--prs`, `--issues`, `--all`) — specify the filter directly.

These modes are mutually exclusive. You can't combine a profile argument with option-based flags.
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/2842/contribute/changelog#changelog-remove).

## Usage

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


## Arguments

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, promotion report URL, or URL list file.">
  </definition>
  <definition term="Mutually exclusive with --all, --products, --prs, --issues, --report, --owner, --repo, --config, --directory, and --bundles-dir.">
  </definition>
  <definition term="[1] <string?>">
    Version number, promotion report URL/path, or URL list file.
  </definition>
  <definition term="For example, 9.2.0, https://buildkite.../promotion-report.html, or /path/to/prs.txt.">
  </definition>
  <definition term="See Profile argument types for details on accepted formats.">
  </definition>
  <definition term="[2] <string?>">
    Optional: Promotion report URL/path or URL list file when the second argument is a version string.
  </definition>
  <definition term="When provided, [1] must be a version string and [2] is the PR/issue filter source.">
  </definition>
  <definition term="For example, docs-builder changelog remove serverless-release 2026-02 ./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="Not allowed 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 resolved in order: bundle.output_directory from the changelog configuration, then {changelog-dir}/bundles, then {changelog-dir}/../bundles.">
  </definition>
  <definition term="Not allowed with a profile argument. In profile mode, the same automatic discovery applies.">
  </definition>
  <definition term="--config <string?>">
    Optional: Path to the changelog configuration file.
  </definition>
  <definition term="Defaults to docs/changelog.yml.">
  </definition>
  <definition term="Not allowed with a profile argument. In profile mode, the configuration is discovered automatically.">
  </definition>
  <definition term="--directory <string?>">
    Optional: The directory that contains the changelog YAML files.
  </definition>
  <definition term="When not specified, falls back to bundle.directory from the changelog configuration, then the current working directory.">
  </definition>
  <definition term="Not allowed with a profile argument. In profile mode, the same fallback applies (starting from bundle.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 option-based 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 option-based mode.">
  </definition>
  <definition term="--issues <string[]?>">
    Filter by issue URLs (comma-separated), or a path to a newline-delimited file.
  </definition>
  <definition term="Can be specified multiple times.">
  </definition>
  <definition term="Exactly one filter option must be specified: --all, --products, --prs, --issues, or --report.">
  </definition>
  <definition term="When using a file, every line must be a fully-qualified GitHub issue URL. Bare numbers and short forms are not allowed in files.">
  </definition>
  <definition term="Not allowed 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="Not allowed with a profile argument.">
  </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="Not allowed 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 (comma-separated), or a path to a newline-delimited file.
  </definition>
  <definition term="Can be specified multiple times.">
  </definition>
  <definition term="Exactly one filter option must be specified: --all, --products, --prs, --issues, or --report.">
  </definition>
  <definition term="When using a file, every line must be a fully-qualified GitHub PR URL. Bare numbers and short forms are not allowed in files.">
  </definition>
  <definition term="Not allowed 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>
  <definition term="Not allowed with a profile argument.">
  </definition>
  <definition term="--report <string?>">
    Filter by pull requests extracted from a promotion report. Accepts a URL or a local file path.
  </definition>
  <definition term="Exactly one filter option must be specified: --all, --products, --prs, --issues, or --report.">
  </definition>
  <definition term="Not allowed with a profile argument.">
  </definition>
</definitions>


## Directory resolution

Both modes use the same ordered fallback to locate changelog YAML files and existing bundles.
**Changelog files directory** (where changelog YAML files are read from):

| Priority | Profile-based                         | Option-based                          |
|----------|---------------------------------------|---------------------------------------|
| 1        | `bundle.directory` in `changelog.yml` | `--directory` CLI option              |
| 2        | Current working directory             | `bundle.directory` in `changelog.yml` |
| 3        | —                                     | Current working directory             |

**Bundles directory** (scanned for existing bundles during the dependency check):

| Priority | Both modes                                     |
|----------|------------------------------------------------|
| 1        | `--bundles-dir` CLI option (option-based only) |
| 2        | `bundle.output_directory` in `changelog.yml`   |
| 3        | `{changelog-dir}/bundles`                      |
| 4        | `{changelog-dir}/../bundles`                   |

<note>
  "Current working directory" means the directory you are in when you run the command (`pwd`).
  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.
</note>


## 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.
Profile-based commands discover the changelog configuration automatically (no `--config` flag): they look for `changelog.yml` in the current directory, then `docs/changelog.yml`. If neither file is found, the command returns an error with instructions to run `docs-builder changelog init` or to re-run from the folder where the file exists.
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.
<note>
  The `output_products`, `repo`, `owner`, and `hide_features` fields are not relevant to changelog removal and are ignored.
</note>

You can also pass a promotion report URL or file path, in which case the command removes changelogs that have `prs` that match the report.
The following commands perform the same task with and without a profile:
```sh
docs-builder changelog remove serverless-report ./promotion-report.html

docs-builder changelog remove \
  --report ./promotion-report.html 
```

Alternatively, use a newline delimited text file that lists pull request or issue URLs:
```sh
docs-builder changelog remove serverless-report ./prs.txt
```