alpha(update): add --squash, --preserve-path, --output-branch for PR-friendly upgrades

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)

Author: camilamacedo86

docs/book/src/reference/commands/alpha_update.md

@@ -7,12 +7,13 @@ The `kubebuilder alpha update` command helps you upgrade your project scaffold t
 It uses a **3-way merge strategy** to update your project with less manual work.
 To achieve that, the command creates the following 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 using the _old_ version
+- **Original**: your current project (from your base branch)
+- **Upgrade**: scaffold generated using the _new_ version
+- **Merge**: a merge of **Original** into **Upgrade** (where any conflicts show up)
 
-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, you can **squash** the merge result into a single commit on a stable output branch for easier PRs.
 
 <aside class="note warning">
 <h1>Creates branches and deletes files</h1>
@@ -29,120 +30,143 @@ Use this command when:
 - 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
+- You want to focus on resolving merge conflicts instead of re-applying all your custom code
 
 ## How It Works
 
-The command performs the following steps:
+1. **Detect versions**
+   Determines `--from-version` (or reads from your `PROJECT` file) and `--to-version` (or the latest available).
 
-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-*`: your **from-branch** snapshot (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 exact merge tree to a stable output branch:
+    - Default: `kubebuilder-alpha-update-to-<to-version>`
+    - Or whatever you pass via `--output-branch`
+      It then commits **once**. If there were conflicts, the single commit will contain conflict markers.
+
+You can push either `tmp-merge-*` (no squashing) or the output branch (with `--squash`) to your remote and open a PR.
 
 ## How to Use It
 
-Run the command from your project directory:
+Run from your project root:
 
 ```sh
 kubebuilder alpha update
 ```
 
-If needed, set a specific version or branch:
+Pin versions and base branch:
 
 ```sh
 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
 ```
 
-Force update even with merge conflicts:
+Automation-friendly: proceed even with conflicts:
 
 ```sh
 kubebuilder alpha update --force
 ```
 
-<aside class="note warning">
-<h1>You might need to upgrade your project first</h1>
+Create a **single squashed commit** on a stable PR branch:
+
+```sh
+kubebuilder alpha update --force --squash
+```
+
+Squash while **preserving** paths from your base branch (keep CI/workflows, etc.):
+
+```sh
+kubebuilder alpha update --force --squash \
+  --preserve-path .github/workflows \
+  --preserve-path docs
+```
+
+Use a **custom output branch** name:
+
+```sh
+kubebuilder alpha update --force --squash \
+  --output-branch upgrade/kb-to-v4.7.0
+```
 
-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`.
+### Commit message used in `--squash` mode
 
-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**.
+```
+[kubebuilder-automated-update]: update scaffold from <from> to <to>; (squashed 3-way merge)
+```
 
-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 class="note warning">
+<h1>You might need to upgrade your project first</h1>
+This command uses <code>kubebuilder alpha generate</code> internally. The Kubebuilder version originally used to create your project must support <code>alpha generate</code>.<br><br>
+This command has been tested with projects created using <strong>v4.5.0+</strong>. If your project predates that, first run <code>kubebuilder alpha generate</code> once to modernize the scaffold. After that, you can use <code>kubebuilder alpha update</code> 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, uses the `PROJECT` file. |
+| `--to-version`    | Version to upgrade to. Defaults to the latest release.                                                                                     |
+| `--from-branch`   | Git branch that contains your current project code. Defaults to `main`.                                                                    |
+| `--force`         | Continue even if there are merge conflicts. Conflicted files are committed with conflict markers (great for CI/cron).                      |
+| `--squash`        | Write the merge result as a **single commit** on a stable output branch.                                                                   |
+| `--preserve-path` | Repeatable. When squashing, restore these paths from the base branch (e.g., `--preserve-path .github/workflows`).                          |
+| `--output-branch` | Custom branch name for the squashed commit (defaults to `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.
+Projects generated with **Kubebuilder v4.6.0+** include <code>cliVersion</code> in the <code>PROJECT</code> file. `kubebuilder alpha update` uses this 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 completes the merge even if there are conflicts. The resulting commit includes conflict markers like:
+
 ```
 <<<<<<< 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 includes 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 manually resolve these conflicts before merging into your main branch.<br><br>
+<strong>After resolving conflicts, always run:</strong>
+</aside>
 
 ```bash
 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.
+Use `--force` when:
+
+- Running in automated environments (CI/cron) and you want a PR/branch even if conflicts occur
+- A human will resolve conflicts later
+- You prefer the tool to be non-blocking
 
-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.
+This ensures the update proceeds without manual blocking but
+shifts responsibility for conflict resolution to a follow-up step.
 
-## 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
 

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,14 @@ type Update struct {
 	// Force commits the update changes even with merge conflicts
 	Force bool
 
+	// Squash: after creating the merge branch, snapshot its tree as a single commit
+	// on a deterministic output branch named "kubebuilder-alpha-update-to-<ToVersion>".
+	Squash bool
+	// PreservePath: repeatable paths to restore from base (e.g., ".github/workflows")
+	PreservePath []string
+	// OutputBranch (optional): if empty and Squash=true, default is kubebuilder-alpha-update-to-<ToVersion>
+	OutputBranch string
+
 	// UpdateBranches
 	AncestorBranch string
 	OriginalBranch string
@@ -105,6 +114,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)
+	}
+
+	// 3a) 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()
+		}
+	}
+
+	// 4) 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
 }