Migrating between versions

Upgrading v4 to v5

  1. If you've set up something custom with Advanced > Widgets and key bindings and are coming from a 4.x version less than 4.8.1, migrate off deprecated functions.

    • Instead of _abbr_widget_expand use abbr-expand
    • Instead of _abbr_widget_expand_and_accept use abbr-expand-and-accept
    • Instead of _abbr_widget_expand_and_space use abbr-expand-and-space
  2. If you anticipate wanting to downgrade back to v4, backing up your user abbreviations file will make things easier for you in the future.

    cp $ABBR_USER_ABBREVIATIONS_FILE path/to/user-abbreviations-v4.bk
  3. Install the latest zsh-abbr following the instructions at Installation.

  4. If you use zsh-syntax-highlighting to highlight abbreviations, use the new snippets at Reference > Advanced > Syntax highlighting.

Downgrading v5 to v4

  1. Back up your user abbreviations
    cp $ABBR_USER_ABBREVIATIONS_FILE path/to/user-abbreviations-v5.bk
    • If you have a backup from before upgrading v4 to v5, use it

      mv path/to/user-abbreviations-v4.bk $ABBR_USER_ABBREVIATIONS_FILE
    • Otherwise, go through your ABBR_USER_ABBREVIATIONS_FILE and manually

      • Delete all multi-word abbreviations
        abbr "git cp"="git cherry-pick"
        abbr "gcp"="git cherry-pick"
        abbr "gcp"="git cherry-pick"
      • Remove the quotation marks from all abbreviations
        abbr "gcp"="git cherry-pick"
        abbr gcp="git cherry-pick"
  3. Install v4.x
    • Plugin manager: use your manager to install zsh-abbr from branch v4.
    • Homebrew: install v4
      brew uninstall --force zsh-abbr && brew install olets/tap/zsh-abbr@4
      and follow the post-install instructions logged to the terminal.
    • Manual:
  4. Restart zsh
    exec zsh