From dc7e2324e613baf78b8e57c28e66e930634b4bb0 Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Mon, 14 Sep 2026 21:38:50 +0200
Subject: [PATCH] feat: document `cooldown` updater option (#135)

Co-authored-by: carlosala <66907184+carlosala@users.noreply.github.com>
---
 FAQ.md      |  5 ++++-
 Settings.md | 16 ++++++++++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/FAQ.md b/FAQ.md
index 2ad6272..f9ab31f 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -148,6 +148,8 @@ If you want to manually update Oh My Zsh, you have 2 options:
   omz update
   ```
 
+  This command honors the `':omz:update' cooldown` setting documented in [[Settings]].
+
 - If you want to update Oh My Zsh as part of an automated script, its better to use the `upgrade.sh` script directly. You can call it with any of these alternatives:
 
   ```sh
@@ -157,10 +159,11 @@ If you want to manually update Oh My Zsh, you have 2 options:
   /path/to/ohmyzsh/tools/upgrade.sh
   ```
 
-  This script also allows you to pass in 2 separate flags to control its behavior:
+  This script also allows you to pass in 3 separate flags to control its behavior:
 
   - `-i`: tells the script to upgrade interactively. In this mode, the only change is that the changelog will be displayed after the update.
   - `-v default|minimal|silent`: control the verbosity of the script. This is equivalent to the [verbosity](https://github.com/ohmyzsh/ohmyzsh/wiki/Settings#omzupdate-verbosity) settings.
+  - `-c <days>`: only apply updates that are at least _N_ days old. This is equivalent to the [`cooldown`](https://github.com/ohmyzsh/ohmyzsh/wiki/Settings#omzupdate-cooldown) setting.
 
 > [!IMPORTANT]
 > To upgrade Oh My Zsh, you need to have `git` installed and it needs to be installed as a git repository.  
diff --git a/Settings.md b/Settings.md
index 4eeae86..5434e2d 100644
--- a/Settings.md
+++ b/Settings.md
@@ -19,6 +19,7 @@
 - [Update settings](#update-settings)
   - [`':omz:update' mode`](#omzupdate-mode)
   - [`':omz:update' frequency`](#omzupdate-frequency)
+  - [`':omz:update' cooldown`](#omzupdate-cooldown)
   - [`':omz:update' verbose`](#omzupdate-verbose)
   - [Deprecated settings](#deprecated-settings)
 - [Completion settings](#completion-settings)
@@ -139,6 +140,21 @@ setting only takes effect when automatic updates are enabled. **The default are
 zstyle ':omz:update' frequency 7
 ```
 
+### `':omz:update' cooldown`
+
+By default, updates always pull the latest changes. This setting tells Oh My Zsh to only apply updates whose commits are at least _N_ days old. It affects both the auto-updater and `omz update`. **The default is 0 days**, which keeps the current behavior.
+
+```zsh
+# Only apply updates that are at least 10 days old
+zstyle ':omz:update' cooldown 10
+```
+
+If you call `upgrade.sh` directly from a script, pass the same value with `-c` because the script does not read your `.zshrc`:
+
+```sh
+"$ZSH/tools/upgrade.sh" -c 10
+```
+
 ### `':omz:update' verbose`
 
 This setting controls the amount of information displayed after an update finishes. These are the available verbosity levels: