From 7fbf498277eba9014120698501f3ccf73760d520 Mon Sep 17 00:00:00 2001
From: Guillaume Lours <705411+glours@users.noreply.github.com>
Date: Thu, 18 Sep 2025 11:54:30 +0200
Subject: [PATCH] add description of 'initial_sync' attribute in Compose watch
 documentation (#23421)

<!--Delete sections as needed -->

## Description
Describe the new added `initial_sync` attribute of Compose watch
configuration

## Related issues or tickets
Fix #23345

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [x] Editorial review
- [ ] Product review

---------

Signed-off-by: Guillaume Lours <705411+glours@users.noreply.github.com>
Co-authored-by: aevesdocker <allie.sadler@docker.com>
---
 content/manuals/compose/how-tos/file-watch.md | 5 +++++
 content/reference/compose-file/develop.md     | 6 ++++++
 2 files changed, 11 insertions(+)

diff --git a/content/manuals/compose/how-tos/file-watch.md b/content/manuals/compose/how-tos/file-watch.md
index a9463df968..624df4f876 100644
--- a/content/manuals/compose/how-tos/file-watch.md
+++ b/content/manuals/compose/how-tos/file-watch.md
@@ -118,6 +118,10 @@ For `path: ./app/html` and a change to `./app/html/index.html`:
 
 The `ignore` patterns are relative to the `path` defined in the current `watch` action, not to the project directory. In the following Example 1, the ignore path would be relative to the `./web` directory specified in the `path` attribute.
 
+### `initial_sync`
+
+When using a `sync+x` action, the `initial_sync` attribute tells Compose to ensure files that are part of the defined `path` are up to date before starting a new watch session.
+
 ## Example 1
 
 This minimal example targets a Node.js application with the following structure:
@@ -142,6 +146,7 @@ services:
         - action: sync
           path: ./web
           target: /src/web
+          initial_sync: true
           ignore:
             - node_modules/
         - action: rebuild
diff --git a/content/reference/compose-file/develop.md b/content/reference/compose-file/develop.md
index 6ad7de6e04..4f49b0fa01 100644
--- a/content/reference/compose-file/develop.md
+++ b/content/reference/compose-file/develop.md
@@ -124,6 +124,12 @@ services:
 > In many cases `include` patterns start with a wildcard (`*`) character. This has special meaning in YAML syntax
 > to define an [alias node](https://yaml.org/spec/1.2.2/#alias-nodes) so you have to wrap pattern expression with quotes.
 
+#### `initial_sync`
+
+When using `sync+x` actions, it can be useful to ensure that files inside containers are up to date at the start of a new watch session.
+
+The `initial_sync` attribute instructs the Compose runtime, if containers for the service already exist, to check that the files from the path attribute are in sync within the service containers.
+
 #### `path`
 
 `path` attribute defines the path to source code (relative to the project directory) to monitor for changes. Updates to any file