From 319abb7ddcf026bd3b887027bc088a5eaad7aa3f Mon Sep 17 00:00:00 2001
From: Waldir Pimenta <waldyrious@gmail.com>
Date: Fri, 16 Jan 2026 20:21:18 +0000
Subject: docs: Expand and clarify usage of the history prune command (#3084)

Added a bit of context to make it clearer how this command works and
when one might want to use it.

<!-- Thank you for making a PR! Bug fixes are always welcome, but if
you're adding a new feature or changing an existing one, we'd really
appreciate if you open an issue, post on the forum, or drop in on
Discord -->

## Checks
- [x] I am happy for maintainers to push small adjustments to this PR,
to speed up the review cycle
- [x] I have checked that there are no existing pull requests for the
same thing
---
 docs/docs/reference/prune.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/docs/reference/prune.md b/docs/docs/reference/prune.md
index 5d85819a..40a75d5c 100644
--- a/docs/docs/reference/prune.md
+++ b/docs/docs/reference/prune.md
@@ -4,6 +4,10 @@
 
 This command deletes history entries matching the [history_filter](../configuration/config.md#history_filter) configuration parameter.
 
+These may be commands that match the current `history_filter` configuration, but were saved to history before the filter was set up, and therefore were not excluded from history at the time of execution.
+
+It may be useful to run the prune command after updating `history_filter` to remove old history entries that match the new filters.
+
 It can be run with `--dry-run` first to list history entries that will be removed.
 
 | Argument         | Description                                                        |
-- 
cgit v1.3.1