From 419fdef8b24a451ada95201a66991dba8d668a63 Mon Sep 17 00:00:00 2001
From: hugocasa <hugo@casademont.ch>
Date: Thu, 9 Jul 2026 09:56:15 +0200
Subject: [PATCH] copy(git-sync): both directions in page/card descriptions;
 clearer promotion flow

- Page header and sync-card description mention the pull direction, not only
  push-on-deploy
- Promotion description walks the actual flow (wm_deploy/** branch, merge to
  promote, sync the target workspace) and points at the PR toggle / workflow;
  the Git Promotion docs link now also shows on configured cards, not only in
  the empty state

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PP5gBSPfo1YtkL1sWVAjJm
---
 .../git_sync/GitSyncRepositoryCard.svelte           | 13 ++++++++++---
 .../lib/components/git_sync/GitSyncSection.svelte   |  2 +-
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/frontend/src/lib/components/git_sync/GitSyncRepositoryCard.svelte b/frontend/src/lib/components/git_sync/GitSyncRepositoryCard.svelte
index 61e4427b9b..a01d3b7c81 100644
--- a/frontend/src/lib/components/git_sync/GitSyncRepositoryCard.svelte
+++ b/frontend/src/lib/components/git_sync/GitSyncRepositoryCard.svelte
@@ -266,9 +266,9 @@
 	const displayDescription = $derived(
 		variant === 'primary-sync' || variant === 'primary-promotion'
 			? mode === 'sync'
-				? `Changes will be committed directly to the ${targetOrDefaultBranch} branch`
+				? `Deploys are committed to the ${targetOrDefaultBranch} branch, and new commits to it can deploy back into this workspace automatically`
 				: mode === 'promotion'
-					? `Changes will be made to new branches whose promotion target is the ${targetOrDefaultBranch} branch of the repo to promote to. Remember to also setup Git Sync between the promotion workspace and repo for changes to be deployed when these branches are merged.`
+					? `Each deploy in this workspace pushes its changes to a dedicated wm_deploy/** branch of the repository instead of committing to ${targetOrDefaultBranch} directly. Merging that branch into ${targetOrDefaultBranch} promotes the change: the workspace that syncs ${targetOrDefaultBranch} deploys it on merge, so set up Git Sync there. Windmill can open the pull request for each deploy branch (toggle below), or use the open-pr-on-commit workflow.`
 					: null
 			: null
 	)
@@ -851,7 +851,14 @@
 					</div>
 				</div>
 				{#if displayDescription}
-					<p class="text-xs text-secondary">{displayDescription}</p>
+					<p class="text-xs text-secondary"
+						>{displayDescription}
+						{#if mode === 'promotion'}
+							<a target="_blank" href="https://www.windmill.dev/docs/advanced/deploy_gh_gl"
+								>Learn more about Git Promotion</a
+							>
+						{/if}</p
+					>
 				{/if}
 			</div>
 			{@render repositoryContent()}
diff --git a/frontend/src/lib/components/git_sync/GitSyncSection.svelte b/frontend/src/lib/components/git_sync/GitSyncSection.svelte
index b1aa901729..42e147453c 100644
--- a/frontend/src/lib/components/git_sync/GitSyncSection.svelte
+++ b/frontend/src/lib/components/git_sync/GitSyncSection.svelte
@@ -95,7 +95,7 @@
 {:else}
 	<SettingsPageHeader
 		title="Git Sync"
-		description="Connect the Windmill workspace to a Git repository to automatically commit and push scripts, flows, and apps to the repository on each deploy."
+		description="Connect the Windmill workspace to a Git repository: each deploy commits scripts, flows, and apps to the repository, and new commits to the repository can automatically deploy into the workspace."
 		link="https://www.windmill.dev/docs/advanced/git_sync"
 	>
 		{#snippet actions()}