fix(perms)!: change function name from `fixperms` to `resetperms` and document caution (#10686)

BREAKING CHANGE: function `fixperms` has been renamed to the more accurate `resetperms`.
Please read the README carefully before using it as it may badly reset the permissions.

Fixes #10648
Closes #10686

2 files changed, 29 insertions, 14 deletions

diff --git a/plugins/perms/README.md b/plugins/perms/README.md
index ae7a36b9d..ae10fa659 100644
--- a/plugins/perms/README.md
+++ b/plugins/perms/README.md
@@ -10,6 +10,16 @@ plugins=(... perms)
 
 ## Usage
 
-* `set755` recursively sets all given directories (default to .) to octal 755.
-* `set644` recursively sets all given files (default to .) to octal 644.
-* `fixperms` is a wrapper around `set755` and `set644` applied to a specified directory or the current directory otherwise. It also prompts prior to execution unlike the other two aliases.
+> **CAUTION:** these functions are harmful if you don't know what they do.
+
+- `set755`: sets the permission to octal 755 for all given directories and their child directories (by default, starting from the current directory).
+
+- `set644`: sets the permission to octal 644 for all files of the given directory (by default, the current directory), recursively. It will only affect regular files (no symlinks).
+
+- `resetperms` is a wrapper around `set755` and `set644` applied to a specified directory or the current directory otherwise.
+  It will set the permissions to 755 for directories, and 644 for files.
+
+## Reference
+
+- octal 644: _read and write_ for the owner, _read_ for the group and others users.
+- octal 755: _read, write and execute_ permissions for the owner, and _read and execute_ for the group and others users.
diff --git a/plugins/perms/perms.plugin.zsh b/plugins/perms/perms.plugin.zsh
index 1a7472c1c..353b58411 100644
--- a/plugins/perms/perms.plugin.zsh
+++ b/plugins/perms/perms.plugin.zsh
@@ -6,25 +6,25 @@
 ### Aliases
 
 # Set all files' permissions to 644 recursively in a directory
-set644() {
+function set644 {
 	find "${@:-.}" -type f ! -perm 644 -print0 | xargs -0 chmod 644
 }
 
 # Set all directories' permissions to 755 recursively in a directory
-set755() {
+function set755 {
 	find "${@:-.}" -type d ! -perm 755 -print0 | xargs -0 chmod 755
 }
 
 ### Functions
 
-# fixperms - fix permissions on files and directories, with confirmation
+# resetperms - fix permissions on files and directories, with confirmation
 # Returns 0 on success, nonzero if any errors occurred
-fixperms () {
+function resetperms {
   local opts confirm target exit_status chmod_opts use_slow_mode
   zparseopts -E -D -a opts -help -slow v+=chmod_opts
   if [[ $# > 1 || -n "${opts[(r)--help]}" ]]; then
     cat <<EOF
-Usage: fixperms [-v] [--help] [--slow] [target]
+Usage: resetperms [-v] [--help] [--slow] [target]
 
   target  is the file or directory to change permissions on. If omitted,
           the current directory is taken to be the target.
@@ -40,7 +40,7 @@ EOF
     return $exit_status
   fi
 
-  if [[ $# == 0 ]]; then
+  if [[ $# -eq 0 ]]; then
     target="."
   else
     target="$1"
@@ -49,7 +49,7 @@ EOF
 
   # Because this requires confirmation, bail in noninteractive shells
   if [[ ! -o interactive ]]; then
-    echo "fixperms: cannot run in noninteractive shell"
+    echo "resetperms: cannot run in noninteractive shell"
     return 1
   fi
 
@@ -68,15 +68,20 @@ EOF
   if [[ $use_slow == true ]]; then
     # Process directories first so non-traversable ones are fixed as we go
     find "$target" -type d ! -perm 755 -exec chmod $chmod_opts 755 {} \;
-    if [[ $? != 0 ]]; then exit_status=$?; fi
+    if [[ $? -ne 0 ]]; then exit_status=$?; fi
     find "$target" -type f ! -perm 644 -exec chmod $chmod_opts 644 {} \;
-    if [[ $? != 0 ]]; then exit_status=$?; fi
+    if [[ $? -ne 0 ]]; then exit_status=$?; fi
   else
     find "$target" -type d ! -perm 755 -print0 | xargs -0 chmod $chmod_opts 755
-    if [[ $? != 0 ]]; then exit_status=$?; fi
+    if [[ $? -ne 0 ]]; then exit_status=$?; fi
     find "$target" -type f ! -perm 644 -print0 | xargs -0 chmod $chmod_opts 644
-    if [[ $? != 0 ]]; then exit_status=$?; fi
+    if [[ $? -ne 0 ]]; then exit_status=$?; fi
   fi
   echo "Complete"
   return $exit_status
 }
+
+function fixperms {
+  print -ru2 "fixperms has been deprecated. Use resetperms instead"
+  return 1
+}