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

plugins/bgnotify/bgnotify.plugin.zsh

@@ -1,44 +1,79 @@
 #!/usr/bin/env zsh
 
-## setup ##
+## Setup
 
-[[ -o interactive ]] || return #interactive only!
-zmodload zsh/datetime || { print "can't load zsh/datetime"; return } # faster than date()
-autoload -Uz add-zsh-hook || { print "can't add zsh hook!"; return }
+[[ -o interactive ]] || return # don't load on non-interactive shells
+[[ -z "$SSH_CLIENT" && -z "$SSH_TTY" ]] || return # don't load on a SSH connection
 
-(( ${+bgnotify_threshold} )) || bgnotify_threshold=5 #default 10 seconds
+zmodload zsh/datetime # faster than `date`
 
 
-## definitions ##
+## Zsh Hooks
 
-if ! (type bgnotify_formatted | grep -q 'function'); then ## allow custom function override
-  function bgnotify_formatted { ## args: (exit_status, command, elapsed_seconds)
-    elapsed="$(( $3 % 60 ))s"
-    (( $3 >= 60 )) && elapsed="$((( $3 % 3600) / 60 ))m $elapsed"
-    (( $3 >= 3600 )) && elapsed="$(( $3 / 3600 ))h $elapsed"
-    [ $1 -eq 0 ] && bgnotify "#win (took $elapsed)" "$2" || bgnotify "#fail (took $elapsed)" "$2"
-  }
-fi
-
-currentAppId () {
-  if (( $+commands[osascript] )); then
-    osascript -e 'tell application (path to frontmost application as text) to id' 2>/dev/null
-  fi
+function bgnotify_begin {
+  bgnotify_timestamp=$EPOCHSECONDS
+  bgnotify_lastcmd="${1:-$2}"
 }
 
-currentWindowId () {
-  if hash osascript 2>/dev/null; then #osx
-    osascript -e 'tell application (path to frontmost application as text) to id of front window' 2&> /dev/null || echo "0"
-  elif (hash notify-send 2>/dev/null || hash kdialog 2>/dev/null); then #ubuntu!
-    xprop -root 2> /dev/null | awk '/NET_ACTIVE_WINDOW/{print $5;exit} END{exit !$5}' || echo "0"
+function bgnotify_end {
+  {
+    local exit_status=$?
+    local elapsed=$(( EPOCHSECONDS - bgnotify_timestamp ))
+
+    # check time elapsed
+    [[ $bgnotify_timestamp -gt 0 ]] || return
+    [[ $elapsed -ge $bgnotify_threshold ]] || return
+
+    # check if Terminal app is not active
+    [[ $(bgnotify_appid) != "$bgnotify_termid" ]] || return
+
+    printf '\a' # beep sound
+    bgnotify_formatted "$exit_status" "$bgnotify_lastcmd" "$elapsed"
+  } always {
+    bgnotify_timestamp=0
+  }
+}
+
+autoload -Uz add-zsh-hook
+add-zsh-hook preexec bgnotify_begin
+add-zsh-hook precmd bgnotify_end
+
+
+## Functions
+
+# allow custom function override
+(( ${+functions[bgnotify_formatted]} )) || \
+function bgnotify_formatted {
+  local exit_status=$1
+  local cmd="$2"
+
+  # humanly readable elapsed time
+  local elapsed="$(( $3 % 60 ))s"
+  (( $3 < 60 )) || elapsed="$((( $3 % 3600) / 60 ))m $elapsed"
+  (( $3 < 3600 )) || elapsed="$(( $3 / 3600 ))h $elapsed"
+
+  if [[ $1 -eq 0 ]]; then
+    bgnotify "#win (took $elapsed)" "$2"
   else
-    echo $EPOCHSECONDS #fallback for windows
+    bgnotify "#fail (took $elapsed)" "$2"
   fi
 }
 
-bgnotify () { ## args: (title, subtitle)
-  if hash terminal-notifier 2>/dev/null; then #osx
-    local term_id="$bgnotify_appid"
+# for macOS, output is "app ID, window ID" (com.googlecode.iterm2, 116)
+function bgnotify_appid {
+  if (( ${+commands[osascript]} )); then
+    osascript -e 'tell application (path to frontmost application as text) to get the {id, id of front window}' 2>/dev/null
+  elif (( ${+commands[xprop]} )); then
+    xprop -root _NET_ACTIVE_WINDOW 2>/dev/null | cut -d' ' -f5
+  else
+    echo $EPOCHSECONDS
+  fi
+}
+
+function bgnotify {
+  # $1: title, $2: message
+  if (( ${+commands[terminal-notifier]} )); then # macOS
+    local term_id="${bgnotify_termid%%,*}" # remove window id
     if [[ -z "$term_id" ]]; then
       case "$TERM_PROGRAM" in
       iTerm.app) term_id='com.googlecode.iterm2' ;;
@@ -46,48 +81,26 @@ bgnotify () { ## args: (title, subtitle)
       esac
     fi
 
-    ## now call terminal-notifier, (hopefully with $term_id!)
     if [[ -z "$term_id" ]]; then
-      terminal-notifier -message "$2" -title "$1" >/dev/null
+      terminal-notifier -message "$2" -title "$1" &>/dev/null
     else
-      terminal-notifier -message "$2" -title "$1" -activate "$term_id" -sender "$term_id" >/dev/null
+      terminal-notifier -message "$2" -title "$1" -activate "$term_id" -sender "$term_id" &>/dev/null
     fi
-  elif hash growlnotify 2>/dev/null; then #osx growl
+  elif (( ${+commands[growlnotify]} )); then # macOS growl
     growlnotify -m "$1" "$2"
-  elif hash notify-send 2>/dev/null; then #ubuntu gnome!
+  elif (( ${+commands[notify-send]} )); then # GNOME
     notify-send "$1" "$2"
-  elif hash kdialog 2>/dev/null; then #ubuntu kde!
+  elif (( ${+commands[kdialog]} )); then # KDE
     kdialog --title "$1" --passivepopup  "$2" 5
-  elif hash notifu 2>/dev/null; then #cygwyn support!
+  elif (( ${+commands[notifu]} )); then # cygwin
     notifu /m "$2" /p "$1"
   fi
 }
 
+## Defaults
 
-## Zsh hooks ##
+# notify if command took longer than 5s by default
+bgnotify_threshold=${bgnotify_threshold:-5}
 
-bgnotify_begin() {
-  bgnotify_timestamp=$EPOCHSECONDS
-  bgnotify_lastcmd="${1:-$2}"
-  bgnotify_appid="$(currentAppId)"
-  bgnotify_windowid=$(currentWindowId)
-}
-
-bgnotify_end() {
-  didexit=$?
-  elapsed=$(( EPOCHSECONDS - bgnotify_timestamp ))
-  past_threshold=$(( elapsed >= bgnotify_threshold ))
-  if (( bgnotify_timestamp > 0 )) && (( past_threshold )); then
-    if [[ $(currentAppId) != "$bgnotify_appid" || $(currentWindowId) != "$bgnotify_windowid" ]]; then
-      print -n "\a"
-      bgnotify_formatted "$didexit" "$bgnotify_lastcmd" "$elapsed"
-    fi
-  fi
-  bgnotify_timestamp=0 #reset it to 0!
-}
-
-## only enable if a local (non-ssh) connection
-if [ -z "$SSH_CLIENT" ] && [ -z "$SSH_TTY" ]; then
-  add-zsh-hook preexec bgnotify_begin
-  add-zsh-hook precmd bgnotify_end
-fi
+# bgnotify_appid is slow in macOS and the terminal ID won't change, so cache it at startup
+bgnotify_termid="$(bgnotify_appid)"

plugins/debian/README.md

@@ -21,7 +21,7 @@ Set `$apt_pref` and `$apt_upgr` to whatever command you want (before sourcing Oh
 | ------ | ---------------------------------------------------------------------- | ---------------------------------------------------------- |
 | `age`  | `apt-get`                                                              | Command line tool for handling packages                    |
 | `api`  | `aptitude`                                                             | Same functionality as `apt-get`, provides extra options    |
-| `acs`  | `apt-cache search`                                                     | Command line tool for searching apt software package cache |
+| `acse` | `apt-cache search`                                                     | Command line tool for searching apt software package cache |
 | `aps`  | `aptitude search`                                                      | Searches installed packages using aptitude                 |
 | `as`   | `aptitude -F '* %p -> %d \n(%v/%V)' --no-gui --disable-columns search` | Print searched packages using a custom format              |
 | `afs`  | `apt-file search --regexp`                                             | Search file in packages                                    |

plugins/debian/debian.plugin.zsh

@@ -26,7 +26,7 @@ alias age='apt-get'
 alias api='aptitude'
 
 # Some self-explanatory aliases
-alias acs="apt-cache search"
+alias acse="apt-cache search"
 alias aps='aptitude search'
 alias as="aptitude -F '* %p -> %d \n(%v/%V)' --no-gui --disable-columns search"
 
@@ -51,7 +51,7 @@ if [[ $use_sudo -eq 1 ]]; then
     alias au="sudo $apt_pref $apt_upgr"
     alias ai="sudo $apt_pref install"
     # Install all packages given on the command line while using only the first word of each line:
-    # acs ... | ail
+    # acse ... | ail
 
     alias ail="sed -e 's/  */ /g' -e 's/ *//' | cut -s -d ' ' -f 1 | xargs sudo $apt_pref install"
     alias ap="sudo $apt_pref purge"

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.

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
+}

plugins/ubuntu/README.md

@@ -15,7 +15,7 @@ Commands that use `$APT` will use `apt` if installed or defer to `apt-get` other
 | Alias   | Command                                                                  | Description                                                                                       |
 |---------|--------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
 | age     | `sudo $APT`                                                              | Run apt-get with sudo                                                                             |
-| acs     | `apt-cache search`                                                       | Search the apt-cache with the specified criteria                                                  |
+| acse    | `apt-cache search`                                                       | Search the apt-cache with the specified criteria                                                  |
 | acsp    | `apt-cache showpkg`                                                      | Shows information about the listed packages                                                       |
 | acp     | `apt-cache policy`                                                       | Display the package source priorities                                                             |
 | afs     | `apt-file search --regexp`                                               | Perform a regular expression apt-file search                                                      |

plugins/ubuntu/ubuntu.plugin.zsh

@@ -1,6 +1,6 @@
 (( $+commands[apt] )) && APT=apt || APT=apt-get
 
-alias acs='apt-cache search'
+alias acse='apt-cache search'
 
 alias afs='apt-file search --regexp'