✨ (alpha update): Rename alpha update flag preserve-path to restore-path (#5026)

(chore): Rename alpha update flag preserve-path to restore-path

Co-authored-by: Vitor Floriano <[email protected]>

Author: camilamacedo86

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

@@ -50,7 +50,7 @@ The command creates three temporary branches:
   `kubebuilder-update-from-<from-version>-to-<to-version>`.
 - You can change the behavior:
     - `--show-commits`: keep the full history.
-    - `--preserve-path`: in squash mode, restore specific files (like CI configs) from your base branch.
+    - `--restore-path`: in squash mode, restore specific files (like CI configs) from your base branch.
     - `--output-branch`: pick a custom branch name.
     - `--push`: push the result to `origin` automatically.
 
@@ -89,8 +89,8 @@ Default squash but **preserve** CI/workflows from the base branch:
 
 ```shell
 kubebuilder alpha update --force \
---preserve-path .github/workflows \
---preserve-path docs
+--restore-path .github/workflows \
+--restore-path docs
 ```
 
 Use a custom output branch name:
@@ -140,8 +140,8 @@ make all
 | `--to-version`    | Kubebuilder release to update **to** (e.g., `v4.7.0`). If unset, defaults to the latest available release.                                                  |
 | `--from-branch`   | Git branch that holds your current project code. Defaults to `main`.                                                                                        |
 | `--force`         | Continue even if merge conflicts happen. Conflicted files are committed with conflict markers (CI/cron friendly).                                           |
-| `--show-commits`  | Keep full history (do not squash). **Not compatible** with `--preserve-path`.                                                                               |
-| `--preserve-path` | Repeatable. **Squash mode only.** After copying the merge tree to the output branch, restore these paths from the base branch (e.g., `.github/workflows`).  |
+| `--show-commits`  | Keep full history (do not squash). **Not compatible** with `--restore-path`.                                                                               |
+| `--restore-path` | Repeatable. **Squash mode only.** After copying the merge tree to the output branch, restore these paths from the base branch (e.g., `.github/workflows`).  |
 | `--output-branch` | Name of the output branch. Default: `kubebuilder-update-from-<from-version>-to-<to-version>`.                                                               |
 | `--push`          | Push the output branch to the `origin` remote after the update completes.                                                                                   |
 | `-h, --help`      | Show help for this command.                                                                                                                                 |

pkg/cli/alpha/internal/update/update.go

@@ -56,11 +56,11 @@ type Update struct {
 	// unless OutputBranch is explicitly set.
 	ShowCommits bool
 
-	// PreservePath is a list of paths to restore from the base branch (FromBranch)
+	// RestorePath is a list of paths to restore from the base branch (FromBranch)
 	// when SQUASHING, so things like CI config remain unchanged.
 	// Example: []string{".github/workflows"}
 	// NOTE: This is ignored when ShowCommits == true.
-	PreservePath []string
+	RestorePath []string
 
 	// OutputBranch is the name of the branch that will receive the result:
 	//   - In squash mode (ShowCommits == false): the single squashed commit.
@@ -338,9 +338,9 @@ func (opts *Update) getOutputBranchName() string {
 	return fmt.Sprintf("kubebuilder-update-from-%s-to-%s", opts.FromVersion, opts.ToVersion)
 }
 
-// preservePaths checks out the paths specified in PreservePath
+// preservePaths checks out the paths specified in RestorePath
 func (opts *Update) preservePaths() {
-	for _, p := range opts.PreservePath {
+	for _, p := range opts.RestorePath {
 		p = strings.TrimSpace(p)
 		if p == "" {
 			continue
@@ -352,7 +352,7 @@ func (opts *Update) preservePaths() {
 }
 
 // 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
+// on a branch derived from FromBranch (e.g., "main"). If RestorePath 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(hasConflicts bool) error {
 	out := opts.getOutputBranchName()

pkg/cli/alpha/internal/update/update_test.go

@@ -454,7 +454,7 @@ exit 0`
 
 		It("creates/resets output branch and commits one squashed snapshot", func() {
 			opts.OutputBranch = "" // default naming
-			opts.PreservePath = []string{".github/workflows"}
+			opts.RestorePath = []string{".github/workflows"}
 			opts.ShowCommits = false
 
 			err = opts.squashToOutputBranch(false) // no conflicts
@@ -499,15 +499,15 @@ if [[ "$1" == "commit" ]]; then exit 1; fi
 exit 0`
 			Expect(mockBinResponse(fake, mockGit)).To(Succeed())
 
-			opts.PreservePath = nil
+			opts.RestorePath = nil
 			Expect(opts.squashToOutputBranch(false)).To(Succeed())
 
 			s, _ := os.ReadFile(logFile)
 			Expect(string(s)).To(ContainSubstring("commit --no-verify -m"))
 		})
 
-		It("trims preserve-path and skips blanks", func() {
-			opts.PreservePath = []string{" .github/workflows ", "", "docs"}
+		It("trims restore-path and skips blanks", func() {
+			opts.RestorePath = []string{" .github/workflows ", "", "docs"}
 			Expect(opts.squashToOutputBranch(false)).To(Succeed())
 
 			s, _ := os.ReadFile(logFile)

pkg/cli/alpha/update.go

@@ -42,14 +42,14 @@ The updater uses four temporary branches during the run:
 Output branch & history:
   • Default: SQUASH the merge result into ONE commit on:
         kubebuilder-update-from-<from-version>-to-<to-version>
-  • --show-commits: keep full history (not compatible with --preserve-path).
+  • --show-commits: keep full history (not compatible with --restore-path).
 
 Conflicts:
   • Default: stop on conflicts and leave the merge branch for manual resolution.
   • --force: commit with conflict markers so automation can proceed.
 
 Other options:
-  • --preserve-path: restore paths from base when squashing (e.g., CI configs).
+  • --restore-path: restore paths from base when squashing (e.g., CI configs).
   • --output-branch: override the output branch name.
   • --push: push the output branch to 'origin' after the update.
 
@@ -70,16 +70,16 @@ Defaults:
   kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force --show-commits
 
   # Squash while preserving CI workflows from base (e.g., main)
-  kubebuilder alpha update --force --preserve-path .github/workflows
+  kubebuilder alpha update --force --restore-path .github/workflows
 
   # Show commits into a custom output branch name
   kubebuilder alpha update --force --show-commits --output-branch my-update-branch
 
   # Run update and push the output branch to origin (works with or without --show-commits)
   kubebuilder alpha update --from-version v4.6.0 --to-version v4.7.0 --force --push`,
 		PreRunE: func(_ *cobra.Command, _ []string) error {
-			if opts.ShowCommits && len(opts.PreservePath) > 0 {
-				return fmt.Errorf("the --preserve-path flag is not supported with --show-commits")
+			if opts.ShowCommits && len(opts.RestorePath) > 0 {
+				return fmt.Errorf("the --restore-path flag is not supported with --show-commits")
 			}
 
 			if err := opts.Prepare(); err != nil {
@@ -107,9 +107,9 @@ Defaults:
 			"commit will be created automatically. Ideal for automation (e.g., cronjobs, CI).")
 	updateCmd.Flags().BoolVar(&opts.ShowCommits, "show-commits", false,
 		"If set, the update will keep the full history instead of squashing into a single commit.")
-	updateCmd.Flags().StringArrayVar(&opts.PreservePath, "preserve-path", nil,
+	updateCmd.Flags().StringArrayVar(&opts.RestorePath, "restore-path", nil,
 		"Paths to preserve from the base branch when squashing (repeatable). Not supported with --show-commits. "+
-			"Example: --preserve-path .github/workflows")
+			"Example: --restore-path .github/workflows")
 	updateCmd.Flags().StringVar(&opts.OutputBranch, "output-branch", "",
 		"Override the default output branch name (default: kubebuilder-update-from-<from-version>-to-<to-version>).")
 	updateCmd.Flags().BoolVar(&opts.Push, "push", false,

pkg/cli/alpha/update_test.go

@@ -36,7 +36,7 @@ var _ = Describe("NewUpdateCommand", func() {
 			Expect(flags.Lookup("from-branch")).NotTo(BeNil())
 			Expect(flags.Lookup("force")).NotTo(BeNil())
 			Expect(flags.Lookup("show-commits")).NotTo(BeNil())
-			Expect(flags.Lookup("preserve-path")).NotTo(BeNil())
+			Expect(flags.Lookup("restore-path")).NotTo(BeNil())
 			Expect(flags.Lookup("output-branch")).NotTo(BeNil())
 			Expect(flags.Lookup("push")).NotTo(BeNil())
 		})

test/e2e/alphaupdate/update_test.go

@@ -258,13 +258,13 @@ var _ = Describe("kubebuilder", func() {
 			git("add", ".github/workflows/ci.yml")
 			git("commit", "-m", "add ci workflow")
 
-			By("running update (default squash) with --preserve-path")
+			By("running update (default squash) with --restore-path")
 			cmd := exec.Command(
 				kbc.BinaryName, "alpha", "update",
 				"--from-version", fromVersion,
 				"--to-version", toVersion,
 				"--from-branch", "main",
-				"--preserve-path", ".github/workflows",
+				"--restore-path", ".github/workflows",
 			)
 			cmd.Dir = kbc.Dir
 			out, err := kbc.Run(cmd)