From 82bd1a3aa712907c8b41533bef14b7ff9cf47cb1 Mon Sep 17 00:00:00 2001
From: Dean Chen <862469039@qq.com>
Date: Sat, 15 Aug 2026 23:39:03 +0500
Subject: [PATCH] docs(stack deploy): say how --resolve-image affects pulls

Default always pins a digest from the registry, so :latest
is whatever the registry has at deploy time.

Signed-off-by: Dean Chen <862469039@qq.com>
---
 docs/reference/commandline/stack_deploy.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/reference/commandline/stack_deploy.md b/docs/reference/commandline/stack_deploy.md
index 01ccf278875f..a939568435e9 100644
--- a/docs/reference/commandline/stack_deploy.md
+++ b/docs/reference/commandline/stack_deploy.md
@@ -88,6 +88,18 @@ Creating service vossibility_ghollector
 Creating service vossibility_lookupd
 ```
 
+### Image pull (--resolve-image)
+
+By default (`--resolve-image always`) the manager asks the registry for
+a digest and workers pull that digest when they start a task. A moving
+tag such as `:latest` therefore becomes whatever the registry has *now*,
+not whatever happened to be cached on the node.
+
+`--resolve-image changed` only re-resolves if the tag in the Compose
+file changed. `--resolve-image never` leaves the image name as written
+and does not query the registry on deploy (nodes still pull if they
+do not already have the image).
+
 You can verify that the services were correctly created:
 
 ```console