DOCSEARCHbyAlgolia
Submit Docs

zsh-abbr

repository·main·Indexed 21 days ago

https://github.com/olets/zsh-abbr

A Zsh plugin for managing auto-expanding abbreviations inspired by the fish shell. It allows users to define shorthands that expand into full commands upon pressing Space or Enter, ensuring the command history remains transparent and readable. Features include support for regular and global abbreviations, session and user scopes, Git shorthand integration, and the ability to import aliases from Git, Fish, or Zsh.

Tokens
1.7K
Snippets
6
Records
9
Agent score
24%

What's inside zsh-abbr

  1. What is zsh-abbr

    main

    zsh-abbr is a Zsh plugin for managing auto-expanding abbreviations. It allows you to define short text sequences (abbreviations) that automatically expand into longer, more descriptive commands when typed in the terminal.

    Key Features

    • Keystroke Savings: Similar to aliases, but with a key difference in how they interact with command history.
    • Transparent History: Unlike standard aliases, abbreviations expand in the terminal, leaving your command history containing the full, understandable command rather than the shorthand. This makes history easier to share or use on different machines.
    • Learning Tool: Helps users learn full command syntax by providing the shorthand while visually presenting the expanded version.
    • Types of Abbreviations:
      • Regular: Abbreviations that only expand when they are at the start of a command.
      • Global: Abbreviations that can expand anywhere on a command line.
    • Persistence: Abbreviations can be created interactively and are automatically synced to a file for easy dotfile management.

  2. Benchmark the performance of zsh-abbr

    main

    To measure the performance of zsh-abbr across different scenarios, use the zsh-bench tool. The benchmarking process requires running tests in an isolated Docker environment using a specific configuration directory provided in the repository.

    Ensure you have zsh-bench installed before running the command.

    zsh-bench --isolation docker --config-dir ./performance -- not-installed fresh-install zero-abbreviations ten-abbreviations one-hundred-abbreviations

  3. Understand abbreviation scopes and types

    main

    When running abbr commands, you can specify the scope and the type to control where and how abbreviations are applied.

    Scopes

    • --session (-S): Abbreviations are available only in the current shell session.
    • --user (-U): Abbreviations are available in all current and future sessions (persisted).

    Types

    • --global (-g): The abbreviation expands anywhere on a line.
    • --regular (-r): (Default) The abbreviation only expands if it is the first word in the command.

  4. Add and manage zsh abbreviations

    main

    Use the abbr command to create abbreviations that expand into longer phrases when you press Space or Enter.

    By default, abbreviations only expand when they are the first word in a command (regular type). To make them expand anywhere on a line, use the --global or -g type.

    Key behaviors:

    • Expansion Trigger: Pressing [Space] or [Enter] triggers expansion. To prevent expansion, press [CTRL-SPACE] instead of [Space].
    • Overwrite Protection: abbr add will error if an abbreviation already exists. Use --force or -f to overwrite.
    • Command Conflict: The tool warns if an abbreviation would replace an existing command. Use --force to bypass this.
    # Add a regular user abbreviation (available in all sessions)
abbr gco="git checkout"

# Add a global abbreviation (expands anywhere on the line)
abbr -g gco="git checkout"

# Add a session-only abbreviation
abbr -S gco="git checkout"

  5. Configure zsh-abbr via environment variables

    main

    You can control the behavior of zsh-abbr using the following environment variables:

    VariableDescription
    IABBR_AUTOLOADWhether abbr load runs before every abbr command (0 or 1, default 1)
    IABBR_DEFAULT_BINDINGSUse default key bindings (0 or 1, default 1)
    IABBR_DEBUGEnable debugging logs (0 or 1, default 0)
    IABBR_DRY_RUNBehave as if --dry-run was passed (0 or 1, default 0)
    IABBR_FORCEBehave as if --force was passed (0 or 1, default 0)
    IABBR_QUIETBehave as if --quiet was passed (0 or 1, default 0)
    IABBR_USER_ABBREVIATIONS_FILEPath to the user abbreviations file. Default: ${XDG_CONFIG_HOME:-$HOME/.config}/zsh-abbr/user-abbreviations
    NO_COLORIf set, disables color output

  6. Use git shorthand for abbreviations

    main

    The abbr git (or abbr g) command is a shorthand for adding abbreviations that start with git. It automatically handles the git prefix for you.

    # These are equivalent:
abbr git gco="git checkout"
abbr g gco="git checkout"

# Or adding a specific git command:
abbr git co="git checkout"

  7. Erase, rename, and expand abbreviations

    main

    Manage existing abbreviations using the following commands:

    • Erase (erase | e): Removes an abbreviation. Use --session or --user to specify scope.
    • Rename (rename | R): Changes an abbreviation from an old name to a new name.
    • Expand (expand | x): Returns the full expansion string of a given abbreviation.
    # Erase a user abbreviation
abbr e gco

# Erase a global user abbreviation (note the semicolon to prevent expansion)
abbr e -g gco;

# Rename a global user abbreviation
abbr R -g gco gch

# Get the expansion of an abbreviation
abbr x gco

  8. Import aliases from Git, Fish, or Zsh

    main

    Convert existing command aliases into zsh-abbr abbreviations using these commands:

    • import-aliases: Adds abbreviations for all current shell aliases.
    • import-fish <file>: Imports abbreviations exported from the Fish shell.
    • import-git-aliases: Creates abbreviations for every Git alias available in the current session.
      • Use --file <config-file> to specify a custom Git config.
      • Use --prefix <prefix> to add a prefix to the abbreviation name.
      • Expansions are automatically prefixed with git .
    # Import all shell aliases as abbreviations
abbr import-aliases

# Import Git aliases with a custom prefix
abbr import-git-aliases --prefix gi

  9. List abbreviations and commands

    main

    View your configured abbreviations with the following commands:

    • list: Lists available abbreviations without their expansions (similar to Fish shell).
    • list-abbreviations (l): Lists all abbreviations including their expansions.
    • list-commands (L): Lists all abbreviations formatted as commands, suitable for exporting or piping to an alias file.
    abbr l
abbr L