From 0d40b9cc847185fcccd376b34b39bbee0e04b8ea Mon Sep 17 00:00:00 2001
From: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com>
Date: Sun, 10 Aug 2025 00:39:02 +0100
Subject: [PATCH] alpha(update): add --squash, --preserve-path, --output-branch
 for PR-friendly upgrades
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This change makes `kubebuilder alpha update` produce a PR-ready branch and a
single squashed commit when requested, improving automation and review UX.

Key changes
-----------
• New `--squash` flag:
  - Snapshots the exact tree of the temporary merge branch into ONE commit on a
    stable branch: `kubebuilder-alpha-update-to-<to-version>`.
  - Intended for opening/refreshing idempotent PRs.
  - Gracefully handles "no changes" (git commit exits 1 → treated as no-op).

• New `--preserve-path` (repeatable):
  - When squashing, restore given paths from the base branch (e.g.
    `.github/workflows`) so CI/config files are kept as-is on the PR branch.

• New `--output-branch`:
  - Overrides the default PR branch name created by `--squash`.

• Commit message used by `--squash`:
  - `[kubebuilder-automated-update]: update scaffold from <from> to <to>; (squashed 3-way merge)`

• Behavior/ergonomics:
  - Without `--force`: stops on conflicts on the temporary merge branch.
  - With `--force`: commits conflict markers on the merge branch (automation-friendly).
  - After merge, still best-effort run: `make manifests generate fmt vet lint-fix`.

Defaults / Compatibility
------------------------
  - `--squash` is off by default (no behavior change unless opted-in).
  - `--from-branch` defaults to `main`.
  - `--preserve-path` is empty by default (no restores).
  - Safe to run on projects scaffolded with v4.5.0+ (uses `alpha generate`).

Motivation
----------
Make upgrades PR-centric and automation-ready by producing a deterministic,
reviewable branch and a single squashed commit that mirrors the merge result.

Assisted-by: ChatGPT (OpenAI)

Co-authored-by: Vitor Floriano <vitorfloriano@users.noreply.github.com>
---
 .../src/reference/commands/alpha_update.md    | 70 ++++++++++++--
 pkg/cli/alpha/internal/update/update.go       | 69 ++++++++++++++
 pkg/cli/alpha/internal/update/update_test.go  | 95 ++++++++++++++++++-
 pkg/cli/alpha/update.go                       | 73 +++++++++-----
 pkg/cli/alpha/update_test.go                  | 12 ++-
 test/e2e/alphaupdate/update_test.go           | 80 +++++++++++-----
 6 files changed, 337 insertions(+), 62 deletions(-)

diff --git a/docs/book/src/reference/commands/alpha_update.md b/docs/book/src/reference/commands/alpha_update.md
index b0d79dc54a1..16ea9cbe344 100644
--- a/docs/book/src/reference/commands/alpha_update.md
+++ b/docs/book/src/reference/commands/alpha_update.md
@@ -12,6 +12,7 @@ It uses a **3-way merge** so you do less manual work. The command creates these
 - **Merge**: result of merging **Original** into **Upgrade** (this is where conflicts appear)
 
 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>
@@ -43,8 +44,13 @@ Use this command when you:
 3. **3-way merge**
    Creates `tmp-merge-*` from **Upgrade** and merges **Original** into it.
    Runs `make manifests generate fmt vet lint-fix` to normalise outputs.
+   Runs `make manifests generate fmt vet lint-fix` to normalize outputs.
 
-Push either `tmp-merge-*` (no squash) to open a PR.
+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.
 
 ## How to Use It
 
@@ -68,6 +74,27 @@ Automation-friendly (proceed even with conflicts):
 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
+```
+
 ## Merge Conflicts with `--force`
 
 When you use `--force`, Git finishes the merge even if there are conflicts.
@@ -82,7 +109,29 @@ Incoming changes
 ```
 
 - **Without `--force`**: the command stops on `tmp-merge-*` and prints guidance; no commit is created.
-- **With `--force`**: the merge is committed (on `tmp-merge-*`) and contains the markers.
+- **With `--force`**: the merge is committed (on `tmp-merge-*`, or on the output branch if using `--squash`) and contains the markers.
+
+## 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` 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.
+
+</aside>
+
+<aside class="note">
+<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>
 
 <aside class="note warning">
 You must resolve these conflicts before merging into `main` (or your base branch).
@@ -98,13 +147,16 @@ make all
 
 ## Flags
 
-| Flag              | Description                                                                                                        |
-|-------------------|--------------------------------------------------------------------------------------------------------------------|
-| `--from-version`  | 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). |
-| `-h, --help`      | Show help for this command.                                                                                        |
+| Flag              | Description                                                                                                                                |
+|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| `--from-version`  | 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">
 <h1>CLI Version Tracking</h1>
diff --git a/pkg/cli/alpha/internal/update/update.go b/pkg/cli/alpha/internal/update/update.go
index a2629e16f8e..a432da052c2 100644
--- a/pkg/cli/alpha/internal/update/update.go
+++ b/pkg/cli/alpha/internal/update/update.go
@@ -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
 }
 
diff --git a/pkg/cli/alpha/internal/update/update_test.go b/pkg/cli/alpha/internal/update/update_test.go
index f8bb9d86a63..a452311c417 100644
--- a/pkg/cli/alpha/internal/update/update_test.go
+++ b/pkg/cli/alpha/internal/update/update_test.go
@@ -110,7 +110,7 @@ var _ = Describe("Prepare for internal update", func() {
 			Expect(err).ToNot(HaveOccurred())
 			logs, readErr := os.ReadFile(logFile)
 			Expect(readErr).ToNot(HaveOccurred())
-			Expect(string(logs)).To(ContainSubstring("checkout %s", opts.FromBranch))
+			Expect(string(logs)).To(ContainSubstring(fmt.Sprintf("checkout %s", opts.FromBranch)))
 		})
 		It("Should fail when git command fails", func() {
 			fakeBinScript := `#!/bin/bash
@@ -124,7 +124,7 @@ var _ = Describe("Prepare for internal update", func() {
 
 			logs, readErr := os.ReadFile(logFile)
 			Expect(readErr).ToNot(HaveOccurred())
-			Expect(string(logs)).To(ContainSubstring("checkout %s", opts.FromBranch))
+			Expect(string(logs)).To(ContainSubstring(fmt.Sprintf("checkout %s", opts.FromBranch)))
 		})
 		It("Should fail when kubebuilder binary could not be downloaded", func() {
 			gock.Off()
@@ -141,7 +141,7 @@ var _ = Describe("Prepare for internal update", func() {
 			Expect(err.Error()).To(ContainSubstring("failed to prepare ancestor branch"))
 			logs, readErr := os.ReadFile(logFile)
 			Expect(readErr).ToNot(HaveOccurred())
-			Expect(string(logs)).To(ContainSubstring("checkout %s", opts.FromBranch))
+			Expect(string(logs)).To(ContainSubstring(fmt.Sprintf("checkout %s", opts.FromBranch)))
 		})
 	})
 
@@ -363,10 +363,97 @@ var _ = Describe("Prepare for internal update", func() {
 							exit 1`
 			err = mockBinResponse(fakeBinScript, mockGit)
 			Expect(err).ToNot(HaveOccurred())
-			err := opts.mergeOriginalToUpgrade()
+			err = opts.mergeOriginalToUpgrade()
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring(
 				"failed to create merge branch %s from %s", opts.MergeBranch, opts.OriginalBranch))
 		})
 	})
+
+	Context("SquashToOutputBranch", func() {
+		BeforeEach(func() {
+			opts.FromBranch = "main"
+			opts.ToVersion = "v4.6.0"
+			if opts.MergeBranch == "" {
+				opts.MergeBranch = "tmp-merge-test"
+			}
+		})
+
+		It("should create/reset the output branch and commit one squashed snapshot", func() {
+			opts.OutputBranch = ""
+			opts.PreservePath = []string{".github/workflows"} // exercise the restore call
+
+			err = opts.squashToOutputBranch()
+			Expect(err).ToNot(HaveOccurred())
+
+			logs, readErr := os.ReadFile(logFile)
+			Expect(readErr).ToNot(HaveOccurred())
+			s := string(logs)
+
+			Expect(s).To(ContainSubstring(fmt.Sprintf("checkout %s", opts.FromBranch)))
+			Expect(s).To(ContainSubstring(fmt.Sprintf(
+				"checkout -B kubebuilder-alpha-update-to-%s %s",
+				opts.ToVersion, opts.FromBranch,
+			)))
+			Expect(s).To(ContainSubstring(
+				"-c find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +",
+			))
+			Expect(s).To(ContainSubstring(fmt.Sprintf("checkout %s -- .", opts.MergeBranch)))
+			Expect(s).To(ContainSubstring(fmt.Sprintf(
+				"restore --source %s --staged --worktree .github/workflows",
+				opts.FromBranch,
+			)))
+			Expect(s).To(ContainSubstring("add --all"))
+
+			msg := fmt.Sprintf(
+				"[kubebuilder-automated-update]: update scaffold from %s to %s; (squashed 3-way merge)",
+				opts.FromVersion, opts.ToVersion,
+			)
+			Expect(s).To(ContainSubstring(msg))
+
+			Expect(s).To(ContainSubstring("commit --no-verify -m"))
+		})
+
+		It("should respect a custom output branch name", func() {
+			opts.OutputBranch = "my-custom-branch"
+			err = opts.squashToOutputBranch()
+			Expect(err).ToNot(HaveOccurred())
+
+			logs, _ := os.ReadFile(logFile)
+			Expect(string(logs)).To(ContainSubstring(
+				fmt.Sprintf("checkout -B %s %s", "my-custom-branch", opts.FromBranch),
+			))
+		})
+
+		It("squash: no changes -> commit exits 1 but returns nil", func() {
+			fake := `#!/bin/bash
+echo "$@" >> "` + logFile + `"
+if [[ "$1" == "commit" ]]; then exit 1; fi
+exit 0`
+			Expect(mockBinResponse(fake, mockGit)).To(Succeed())
+
+			opts.PreservePath = nil
+			Expect(opts.squashToOutputBranch()).To(Succeed())
+
+			s, _ := os.ReadFile(logFile)
+			Expect(string(s)).To(ContainSubstring("commit --no-verify -m"))
+		})
+
+		It("squash: trims preserve-path and skips blanks", func() {
+			opts.PreservePath = []string{" .github/workflows ", "", "docs"}
+			Expect(opts.squashToOutputBranch()).To(Succeed())
+			s, _ := os.ReadFile(logFile)
+			Expect(string(s)).To(ContainSubstring("restore --source main --staged --worktree .github/workflows"))
+			Expect(string(s)).To(ContainSubstring("restore --source main --staged --worktree docs"))
+		})
+
+		It("update: runs squash when --squash is set", func() {
+			opts.Squash = true
+			Expect(opts.Update()).To(Succeed())
+			s, _ := os.ReadFile(logFile)
+			Expect(string(s)).To(ContainSubstring("checkout -B kubebuilder-alpha-update-to-" + opts.ToVersion + " main"))
+			Expect(string(s)).To(ContainSubstring("-c find . -mindepth 1"))
+			Expect(string(s)).To(ContainSubstring("checkout " + opts.MergeBranch + " -- ."))
+		})
+	})
 })
diff --git a/pkg/cli/alpha/update.go b/pkg/cli/alpha/update.go
index 432afdfe935..8b57e6d9fbc 100644
--- a/pkg/cli/alpha/update.go
+++ b/pkg/cli/alpha/update.go
@@ -35,39 +35,58 @@ func NewUpdateCommand() *cobra.Command {
 	opts := update.Update{}
 	updateCmd := &cobra.Command{
 		Use:   "update",
-		Short: "Update a Kubebuilder project to a newer version",
-		Long: `This command upgrades your Kubebuilder project to the latest scaffold layout using a 3-way merge strategy.
+		Short: "Update your project to a newer version (3-way merge; optional single-commit)",
+		Long: `Upgrade your project scaffold using a 3-way merge strategy while preserving your code.
 
-It performs the following steps:
-  1. Creates an 'ancestor' branch from the version originally used to scaffold the project
-  2. Creates a 'current' branch with your project's current state
-  3. Creates an 'upgrade' branch using the new version's scaffolding
-  4. Attempts a 3-way merge into a 'merge' branch
+The command creates temporary branches to perform the update:
+  - ancestor:  clean scaffold from the original version
+  - current:   your existing project state
+  - upgrade:   scaffold generated with the target version
+  - merge:     result of the 3-way merge (committed; conflict markers kept with --force)
 
-The process uses Git branches:
-  - ancestor: clean scaffold from the original version
-  - current: your existing project state
-  - upgrade: scaffold from the target version
-  - merge: result of the 3-way merge
+By default, the merge result is committed on the temporary 'merge' branch. 
+Use --squash to snapshot that result into a SINGLE commit on a stable branch,
+ready for a PR:
 
-If conflicts occur during the merge, the command will stop and leave the merge branch for manual resolution.
-Use --force to commit conflicts with markers instead. 
+  kubebuilder-alpha-update-to-<to-version>
+
+This keeps history tidy (one commit per update run) and enables idempotent PRs.
+
+Notes:
+  • --force commits even if conflicts occur (markers are kept).
+  • --preserve-path lets you keep files from your base branch when squashing
+    (useful for CI configs like .github/workflows).
+  • --output-branch optionally overrides the default squashed branch name.
 
 Examples:
-  # Update from the version specified in the PROJECT file to the latest release
+  # Update from the version in PROJECT to the latest, stop on conflicts
   kubebuilder alpha update
 
-  # Update from a specific version to the latest release
+  # Update from a specific version to latest
   kubebuilder alpha update --from-version v4.6.0
 
-  # Update from a specific version to an specific release
-  kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0	
+  # Update from v4.5.0 to v4.7.0 and keep conflict markers (automation-friendly)
+  kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force
 
-  # Force update even with merge conflicts (commit conflict markers)
-  kubebuilder alpha update --force
+  # Same as above, but produce ONE squashed commit on a stable PR branch
+  kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force --squash
 
-`,
+  # Squash while preserving CI workflows from base (e.g., main) on the squashed branch
+  kubebuilder alpha update --force --squash --preserve-path .github/workflows
 
+  # Squash into a custom output branch name
+  kubebuilder alpha update --force --squash --output-branch my-update-branch
+
+Behavior summary:
+  • Without --force:
+      - If conflicts occur during the 3-way merge, the command stops on the 'merge' branch
+        for manual resolution (no commit made).
+  • With --force:
+      - Conflicted files are committed on the 'merge' branch with conflict markers.
+  • With --squash:
+      - After the merge step, the exact 'merge' tree is copied to a new/updated branch
+        (default: kubebuilder-alpha-update-to-<to-version>) and committed ONCE, keeping markers
+        if present. This branch is intended for opening/refreshing a PR.`,
 		PreRunE: func(_ *cobra.Command, _ []string) error {
 			err := opts.Prepare()
 			if err != nil {
@@ -75,7 +94,6 @@ Examples:
 			}
 			return opts.Validate()
 		},
-
 		Run: func(_ *cobra.Command, _ []string) {
 			if err := opts.Update(); err != nil {
 				log.Fatalf("Update failed: %s", err)
@@ -87,17 +105,22 @@ Examples:
 		"binary release version to upgrade from. Should match the version used to init the project and be"+
 			"a valid release version, e.g., v4.6.0. If not set, "+
 			"it defaults to the version specified in the PROJECT file. ")
-
 	updateCmd.Flags().StringVar(&opts.ToVersion, "to-version", "",
 		"binary release version to upgrade to. Should be a valid release version, e.g., v4.7.0. "+
 			"If not set, it defaults to the latest release version available in the project repository.")
-
 	updateCmd.Flags().StringVar(&opts.FromBranch, "from-branch", "",
 		"Git branch to use as current state of the project for the update.")
-
 	updateCmd.Flags().BoolVar(&opts.Force, "force", false,
 		"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).")
+	updateCmd.Flags().BoolVar(&opts.Squash, "squash", false,
+		"After merging, write a single squashed commit with the merge result to a fixed branch "+
+			"named kubebuilder-alpha-update-to-<to-version>.")
+	updateCmd.Flags().StringArrayVar(&opts.PreservePath, "preserve-path", nil,
+		"Paths to preserve from the base branch when squashing (repeatable). "+
+			"Example: --preserve-path .github/workflows")
+	updateCmd.Flags().StringVar(&opts.OutputBranch, "output-branch", "",
+		"Override the default kubebuilder-alpha-update-to-<to-version> branch name (used with --squash).")
 
 	return updateCmd
 }
diff --git a/pkg/cli/alpha/update_test.go b/pkg/cli/alpha/update_test.go
index 2c7ef6c1e72..7955e870b35 100644
--- a/pkg/cli/alpha/update_test.go
+++ b/pkg/cli/alpha/update_test.go
@@ -25,10 +25,18 @@ var _ = Describe("NewUpdateCommand", func() {
 		It("Testing the NewUpdateCommand", func() {
 			cmd := NewUpdateCommand()
 			Expect(cmd).NotTo(BeNil())
-			Expect(cmd.Use).NotTo(Equal(""))
 			Expect(cmd.Use).To(ContainSubstring("update"))
 			Expect(cmd.Short).NotTo(Equal(""))
-			Expect(cmd.Short).To(ContainSubstring("Update a Kubebuilder project to a newer version"))
+			Expect(cmd.Short).To(ContainSubstring("Update your project to a newer version"))
+
+			flags := cmd.Flags()
+			Expect(flags.Lookup("from-version")).NotTo(BeNil())
+			Expect(flags.Lookup("to-version")).NotTo(BeNil())
+			Expect(flags.Lookup("from-branch")).NotTo(BeNil())
+			Expect(flags.Lookup("force")).NotTo(BeNil())
+			Expect(flags.Lookup("squash")).NotTo(BeNil())
+			Expect(flags.Lookup("preserve-path")).NotTo(BeNil())
+			Expect(flags.Lookup("output-branch")).NotTo(BeNil())
 		})
 	})
 })
diff --git a/test/e2e/alphaupdate/update_test.go b/test/e2e/alphaupdate/update_test.go
index 4e85e562e06..a112186932a 100644
--- a/test/e2e/alphaupdate/update_test.go
+++ b/test/e2e/alphaupdate/update_test.go
@@ -104,7 +104,15 @@ var _ = Describe("kubebuilder", func() {
 
 		It("should update project from v4.5.2 to v4.6.0 without conflicts", func() {
 			By("running alpha update from v4.5.2 to v4.6.0")
-			runAlphaUpdate(kbc.Dir, kbc, toVersion, false)
+			cmd := exec.Command(
+				kbc.BinaryName, "alpha", "update",
+				"--from-version", fromVersion,
+				"--to-version", toVersion,
+				"--from-branch", "main",
+			)
+			cmd.Dir = kbc.Dir
+			out, err := kbc.Run(cmd)
+			Expect(err).NotTo(HaveOccurred(), string(out))
 
 			By("checking that custom code is preserved")
 			validateCustomCodePreservation(kbc.Dir)
@@ -123,8 +131,17 @@ var _ = Describe("kubebuilder", func() {
 			By("modifying original Makefile to use CONTROLLER_TOOLS_VERSION v0.17.3")
 			modifyMakefileControllerTools(kbc.Dir, "v0.17.3")
 
-			By("running alpha update to v4.7.0 with --force flag")
-			runAlphaUpdate(kbc.Dir, kbc, toVersionWithConflict, true)
+			By("running alpha update with --force --squash")
+			cmd := exec.Command(
+				kbc.BinaryName, "alpha", "update",
+				"--from-version", fromVersion,
+				"--to-version", toVersionWithConflict,
+				"--from-branch", "main",
+				"--force", "--squash",
+			)
+			cmd.Dir = kbc.Dir
+			out, err := kbc.Run(cmd)
+			Expect(err).NotTo(HaveOccurred(), string(out))
 
 			By("checking that custom code is preserved")
 			validateCustomCodePreservation(kbc.Dir)
@@ -166,11 +183,48 @@ var _ = Describe("kubebuilder", func() {
 				"Expected original user version in conflict")
 			Expect(makefileStr).To(ContainSubstring("CONTROLLER_TOOLS_VERSION ?= v0.18.0"),
 				"Expected latest scaffold version in conflict")
+
+			By("checking that the squashed branch is created with the expected commit message")
+			prBranch := "kubebuilder-alpha-update-to-" + toVersionWithConflict
+
+			git := func(args ...string) ([]byte, error) {
+				cmd := exec.Command("git", args...)
+				cmd.Dir = kbc.Dir
+				return cmd.CombinedOutput()
+			}
+
+			By("checking that the squashed branch exists")
+			_, err = git("rev-parse", "--verify", prBranch)
+			Expect(err).NotTo(HaveOccurred())
+
+			By("checking that exactly one squashed commit ahead of main")
+			out, err = git("rev-list", "--count", prBranch, "^main")
+			Expect(err).NotTo(HaveOccurred(), string(out))
+			Expect(strings.TrimSpace(string(out))).To(Equal("1"))
+
+			By("checking commit message of the squashed branch")
+			out, err = git("log", "-1", "--pretty=%B", prBranch)
+			Expect(err).NotTo(HaveOccurred(), string(out))
+			expected := fmt.Sprintf(
+				"[kubebuilder-automated-update]: update scaffold from %s to %s; (squashed 3-way merge)",
+				fromVersion, toVersionWithConflict,
+			)
+			Expect(string(out)).To(ContainSubstring(expected))
 		})
 
 		It("should stop when updating the project from v4.5.2 to v4.7.0 without the flag force", func() {
 			By("running alpha update without --force flag")
-			runAlphaUpdate(kbc.Dir, kbc, toVersionWithConflict, false, true)
+			By("running alpha update without --force flag")
+			cmd := exec.Command(
+				kbc.BinaryName, "alpha", "update",
+				"--from-version", fromVersion,
+				"--to-version", toVersionWithConflict,
+				"--from-branch", "main",
+			)
+			cmd.Dir = kbc.Dir
+			out, err := kbc.Run(cmd)
+			Expect(err).To(HaveOccurred())
+			Expect(string(out)).To(ContainSubstring("merge stopped due to conflicts"))
 
 			By("validating that merge stopped with conflicts requiring manual resolution")
 			validateConflictState(kbc.Dir)
@@ -286,24 +340,6 @@ func downloadKubebuilderVersion(version string) (string, error) {
 	return binaryPath, nil
 }
 
-func runAlphaUpdate(projectDir string, kbc *utils.TestContext, version string, force bool, expectFailure ...bool) {
-	args := []string{"alpha", "update", "--from-version", fromVersion, "--to-version", version, "--from-branch", "main"}
-	if force {
-		args = append(args, "--force")
-	}
-
-	cmd := exec.Command(kbc.BinaryName, args...)
-	cmd.Dir = projectDir
-
-	output, err := kbc.Run(cmd)
-	if len(expectFailure) > 0 && expectFailure[0] {
-		Expect(err).To(HaveOccurred())
-		Expect(string(output)).To(ContainSubstring("merge stopped due to conflicts"))
-	} else {
-		Expect(err).NotTo(HaveOccurred(), fmt.Sprintf("Alpha update failed: %s", string(output)))
-	}
-}
-
 func updateController(projectDir string) {
 	controllerFile := filepath.Join(projectDir, "internal", "controller", "testoperator_controller.go")
 	Expect(util.ReplaceInFile(controllerFile, "_ = logf.FromContext(ctx)", "log := logf.FromContext(ctx)")).To(Succeed())