kubernetes-sigs
diff --git a/‎docs/book/src/reference/commands/alpha_update.md
Lines changed: 102 additions & 83 deletions b/‎docs/book/src/reference/commands/alpha_update.md
Lines changed: 102 additions & 83 deletions
diff --git a/‎pkg/cli/alpha/internal/update/update.go
Lines changed: 69 additions & 0 deletions b/‎pkg/cli/alpha/internal/update/update.go
Lines changed: 69 additions & 0 deletions
@@ -2,150 +2,169 @@
 
 ## Overview
 
-The `kubebuilder alpha update` command helps you upgrade your project scaffold to a newer Kubebuilder version or plugin layout automatically.
+`kubebuilder alpha update` upgrades your project’s scaffold to a newer Kubebuilder version or plugin layout.
 
-It uses a **3-way merge strategy** to update your project with less manual work.
-To achieve that, the command creates the following branches:
+It uses a **3-way merge** so you do less manual work. The command creates these branches:
 
-- *Ancestor branch*: clean scaffold using the old version
-- *Current branch*: your existing project with your custom code
-- *Upgrade branch*: scaffold generated using the new version
+- **Ancestor**: clean scaffold from the **old** version
+- **Original**: your current project (from your base branch)
+- **Upgrade**: clean scaffold from the **new** version
+- **Merge**: result of merging **Original** into **Upgrade** (this is where conflicts appear)
 
-Then, it creates a **merge branch** that combines everything.
-You can review and test this branch before applying the changes.
+You can review and test the merge result before applying it to your main branch.
+Optionally, use **`--squash`** to put the merge result into **one commit** on a stable output branch (great for PRs).
 
 <aside class="note warning">
 <h1>Creates branches and deletes files</h1>
 
-This command creates Git branches starting with `tmp-kb-update-` and deletes files during the process.
-Make sure to commit your work before running it.
+This command creates branches like `tmp-kb-update-*` and removes files during the process.
+Make sure your work is committed before you run it.
 
 </aside>
 
-## When to Use It?
+## When to Use It
 
-Use this command when:
+Use this command when you:
 
-- You want to upgrade your project to a newer Kubebuilder version or plugin layout
-- You prefer to automate the migration instead of updating files manually
-- You want to review scaffold changes in a separate Git branch
-- You want to focus only on fixing merge conflicts instead of re-applying all your code
+- Want to move to a newer Kubebuilder version or plugin layout
+- Prefer automation over manual file editing
+- Want to review scaffold changes on a separate branch
+- Want to focus on resolving merge conflicts (not re-applying your custom code)
 
 ## How It Works
 
-The command performs the following steps:
+1. **Detect versions**
+   Reads `--from-version` (or the `PROJECT` file) and `--to-version` (or uses the latest).
 
-1. Downloads the older CLI version (from the `PROJECT` file or `--from-version`)
-2. Creates `tmp-kb-update-ancestor` with a clean scaffold using that version
-3. Creates `tmp-kb-update-current` and restores your current code on top
-4. Creates `tmp-kb-update-upgrade` using the latest scaffold
-5. Created `tmp-kb-update-merge` which is a merge of the above branches using the 3-way merge strategy
+2. **Create branches & re-scaffold**
+   - `tmp-ancestor-*`: clean scaffold from **from-version**
+   - `tmp-original-*`: snapshot of your **from-branch** (e.g., `main`)
+   - `tmp-upgrade-*`: clean scaffold from **to-version**
 
-You can push the `tmp-kb-update-merge` branch to your remote repository,
-review the diff, and test the changes before merging into your main branch.
+3. **3-way merge**
+   Creates `tmp-merge-*` from **Upgrade** and merges **Original** into it.
+   Runs `make manifests generate fmt vet lint-fix` to normalize outputs.
+
+4. **(Optional) Squash**
+   With `--squash`, copies the merge result to a stable output branch and commits **once**:
+   - Default output branch: `kubebuilder-alpha-update-to-<to-version>`
+   - Or set your own with `--output-branch`
+     If there are conflicts, the single commit will include conflict markers.
+
+Push either `tmp-merge-*` (no squash) or the output branch (with `--squash`) to open a PR.
 
 ## How to Use It
 
-Run the command from your project directory:
+Run from your project root:
 
-```sh
+```shell
 kubebuilder alpha update
 ```
 
-If needed, set a specific version or branch:
+Pin versions and base branch:
 
-```sh
+```shell
 kubebuilder alpha update \
-  --from-version=v4.5.2 \
-  --to-version=v4.6.0 \
-  --from-branch=main
+  --from-version v4.5.2 \
+  --to-version   v4.6.0 \
+  --from-branch  main
 ```
+Automation-friendly (proceed even with conflicts):
 
-Force update even with merge conflicts:
-
-```sh
+```shell
 kubebuilder alpha update --force
 ```
 
+Create a **single squashed commit** on a stable PR branch:
+
+```shell
+kubebuilder alpha update --force --squash
+```
+
+Squash while **preserving** paths from your base branch (keep CI/workflows, docs, etc.):
+
+```shell
+kubebuilder alpha update --force --squash \
+  --preserve-path .github/workflows \
+  --preserve-path docs
+```
+
+Use a **custom output branch** name:
+
+```shell
+kubebuilder alpha update --force --squash \
+  -output-branch upgrade/kb-to-v4.7.0
+```
+
+
+### Commit message used in `--squash` mode
+
+> [kubebuilder-automated-update]: update scaffold from <from> to <to>; (squashed 3-way merge)
+
 <aside class="note warning">
 <h1>You might need to upgrade your project first</h1>
 
-This command uses `kubebuilder alpha generate` internally.
-As a result, the version of the CLI originally used to create your project must support `alpha generate`.
+This command uses `kubebuilder alpha generate` under the hood.
+We support projects created with <strong>v4.5.0+</strong>.
+If yours is older, first run `kubebuilder alpha generate` once to modernize the scaffold.
+After that, you can use `kubebuilder alpha update` for future upgrades.
 
-This command has only been tested with projects created using **v4.5.0** or later.
-It might not work with projects that were initially created using a Kubebuilder version older than **v4.5.0**.
-
-If your project was created with an older version, run `kubebuilder alpha generate` first to re-scaffold it.
-Once updated, you can use `kubebuilder alpha update` for future upgrades.
 </aside>
 
 ## Flags
 
-| Flag                | Description                                                                                                                                                    |
-|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--from-version`    | **Required for projects initialized with versions earlier than v4.6.0.** Kubebuilder version your project was created with. If unset, uses the `PROJECT` file. |
-| `--to-version`      | Version to upgrade to. Defaults to the latest version.                                                                                                         |
-| `--from-branch`     | Git branch that contains your current project code. Defaults to `main`.                                                                                        |
-| `--force`           | Force the update even if conflicts occur. Conflicted files will include conflict markers, and a commit will be created automatically. Ideal for automation (e.g., cronjobs, CI).                                                                       |
-| `-h, --help`        | Show help for this command.                                                                                                                                    |
+| Flag              | Description                                                                                                                                |
+|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| `--from-version`  | **Required for projects initialized before v4.6.0.** Kubebuilder version your project was created with. If unset, taken from the `PROJECT` file. |
+| `--to-version`    | Version to upgrade to. Defaults to the latest release.                                                                                     |
+| `--from-branch`   | Git branch that has your current project code. Defaults to `main`.                                                                          |
+| `--force`         | Continue even if merge conflicts happen. Conflicted files are committed with conflict markers (useful for CI/cron).                         |
+| `--squash`        | Write the merge result as **one commit** on a stable output branch.                                                                         |
+| `--preserve-path` | Repeatable. With `--squash`, restore these paths from the base branch (e.g., `--preserve-path .github/workflows`).                          |
+| `--output-branch` | Branch name to use for the squashed commit (default: `kubebuilder-alpha-update-to-<to-version>`).                                          |
+| `-h, --help`      | Show help for this command.                                                                                                                |
+
 <aside class="note">
-Projects generated with **Kubebuilder v4.6.0** or later include the `cliVersion` field in the `PROJECT` file.
-This field is used by `kubebuilder alpha update` to determine the correct CLI
-version for upgrading your project.
+<h1>CLI Version Tracking</h1>
+
+Projects created with **Kubebuilder v4.6.0+** include `cliVersion` in the `PROJECT` file.
+We use that value to pick the correct CLI for re-scaffolding.
+
 </aside>
 
 ## Merge Conflicts with `--force`
 
-When you use the `--force` flag with `kubebuilder alpha update`, Git will complete the merge even if there are conflicts. The resulting commit will include conflict markers like:
-```
+When you use `--force`, Git finishes the merge even if there are conflicts. The commit will include markers like:
+
+```shell
 <<<<<<< HEAD
 Your changes
 =======
 Incoming changes
->>>>>>> branch-name
+>>>>>>> tmp-original-…
 ```
-These conflicts will be committed in the
-`tmp-kb-update-merge` branch.
 
-<aside class="note warning">
-You must manually resolve these conflicts before merging into your main branch.
+- **Without `--force`**: the command stops on `tmp-merge-*` and prints guidance; no commit is created.
+- **With `--force`**: the merge is committed (on `tmp-merge-*`, or on the output branch if using `--squash`) and contains the markers.
 
 <aside class="note warning">
-<H1>If you face conflicts (using or not the --force flag) </H1>
-If the merge introduces conflicts, you must resolve them and **ensure** you execute the following command to regenerate the manifests and organise the files properly:
+You must resolve these conflicts before merging into `main` (or your base branch).
+<strong>After resolving conflicts, always run:</strong>
 
-```bash
+```shell
 make manifests generate fmt vet lint-fix
-```
-
-Alternatively, you may want to run:
-
-```bash
+# or
 make all
 ```
-</aside>
-
 
-## When to Use `--force`
-Use `--force` only in scenarios like:
-- Automated environments (e.g., CI pipelines or cron jobs)
-- When you need to create a PR even if conflicts are present
-- When a human will resolve the conflicts later
-`kubebuilder alpha update --force`
-
-This ensures the update proceeds without manual blocking but shifts responsibility for conflict resolution to a follow-up manual step.
-
-This approach is typically used in automation workflows where conflict markers are later addressed by a human, or where preserving the conflicting changes is acceptable for follow-up processing.
+</aside>
 
-## Requirements
+## Demonstration
 
-- A valid [PROJECT][project-config] file at the root of your project
-- A clean Git working directory (no uncommitted changes)
-- Git must be installed and available
+<iframe width="560" height="315" src="https://www.youtube.com/embed/J8zonID__8k?si=WC-FXOHX0mCjph71" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 ## Further Resources
 
-- [WIP: Design proposal for update automation](https://github.com/kubernetes-sigs/kubebuilder/pull/4302)
+- WIP: Design proposal for update automation — https://github.com/kubernetes-sigs/kubebuilder/pull/4302
 
 [project-config]: ../../reference/project-config.md
@@ -24,6 +24,7 @@ import (
 	"net/http"
 	"os"
 	"os/exec"
+	"strings"
 	"time"
 
 	"github.com/spf13/afero"
@@ -42,6 +43,18 @@ type Update struct {
 	// Force commits the update changes even with merge conflicts
 	Force bool
 
+	// Squash writes the merge result as a single commit on a stable branch when true.
+	// The branch defaults to "kubebuilder-alpha-update-to-<ToVersion>" unless OutputBranch is set.
+	Squash bool
+
+	// PreservePath lists paths to restore from the base branch when squashing (repeatable).
+	// Example: ".github/workflows"
+	PreservePath []string
+
+	// OutputBranch is the branch name to use with Squash.
+	// If empty, it defaults to "kubebuilder-alpha-update-to-<ToVersion>".
+	OutputBranch string
+
 	// UpdateBranches
 	AncestorBranch string
 	OriginalBranch string
@@ -105,6 +118,62 @@ func (opts *Update) Update() error {
 	if err := opts.mergeOriginalToUpgrade(); err != nil {
 		return fmt.Errorf("failed to merge upgrade into merge branch: %w", err)
 	}
+	// If requested, collapse the merge result into a single commit on a fixed branch
+	if opts.Squash {
+		if err := opts.squashToOutputBranch(); err != nil {
+			return fmt.Errorf("failed to squash to output branch: %w", err)
+		}
+	}
+	return nil
+}
+
+// squashToOutputBranch takes the exact tree of the MergeBranch and writes it as ONE commit
+// on a branch derived from FromBranch (e.g., "main"). If PreservePath is set, those paths
+// are restored from the base branch after copying the merge tree, so CI config etc. stays put.
+func (opts *Update) squashToOutputBranch() error {
+	// Default output branch name if not provided
+	out := opts.OutputBranch
+	if out == "" {
+		out = "kubebuilder-alpha-update-to-" + opts.ToVersion
+	}
+
+	// 1. Start from base (FromBranch)
+	if err := exec.Command("git", "checkout", opts.FromBranch).Run(); err != nil {
+		return fmt.Errorf("checkout %s: %w", opts.FromBranch, err)
+	}
+	if err := exec.Command("git", "checkout", "-B", out, opts.FromBranch).Run(); err != nil {
+		return fmt.Errorf("create/reset %s from %s: %w", out, opts.FromBranch, err)
+	}
+
+	// 2. Clean working tree (except .git) so the next checkout is a verbatim snapshot
+	if err := exec.Command("sh", "-c",
+		"find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +").Run(); err != nil {
+		return fmt.Errorf("cleanup output branch: %w", err)
+	}
+
+	// 3. Bring in the exact content from the merge branch (no re-merge -> no new conflicts)
+	if err := exec.Command("git", "checkout", opts.MergeBranch, "--", ".").Run(); err != nil {
+		return fmt.Errorf("checkout merge content: %w", err)
+	}
+
+	// 4. Optionally restore preserved paths from base (keep CI, etc.)
+	for _, p := range opts.PreservePath {
+		p = strings.TrimSpace(p)
+		if p != "" {
+			_ = exec.Command("git", "restore", "--source", opts.FromBranch, "--staged", "--worktree", p).Run()
+		}
+	}
+
+	// 5. One commit (keep markers; bypass hooks if repos have pre-commit on conflicts)
+	if err := exec.Command("git", "add", "--all").Run(); err != nil {
+		return fmt.Errorf("stage output: %w", err)
+	}
+	msg := fmt.Sprintf("[kubebuilder-automated-update]: update scaffold from %s to %s; (squashed 3-way merge)",
+		opts.FromVersion, opts.ToVersion)
+	if err := exec.Command("git", "commit", "--no-verify", "-m", msg).Run(); err != nil {
+		return nil
+	}
+
 	return nil
 }