belak / zsh-utils Goto Github PK

View Code? Open in Web Editor NEW

150.0 7.0 11.0 36 KB

A minimal, opinionated set of ZSH plugins designed to be small, simple, and focused.

License: MIT License

Shell 100.00%

zsh zsh-utils

zsh-utils's Introduction

zsh-utils

A minimal, opinionated set of ZSH plugins designed to be small, simple, and focused.

This includes a number of simple plugins designed to smooth away some of the rough edges of zsh without getting in your way. The idea is that you should be able to say "I'd like to enable the history features of ZSH" (or other similar features) without needing to know the gritty details and without worrying that a bunch of unrelated settings will be enabled.

All the plugins are designed to work with no configuration and no additional dependencies, but shouldn't conflict with additional configuration you want to do.

Driving Principles

Many other zsh config frameworks and modules do too much, are overly complex, don't work well out of the box, and have many unmaintained modules. zsh-utils aims to be small, simple, and focused.

Don't reinvent the wheel. If there's an existing plugin elsewhere which works well it should be preferred (such as zsh-completions and zsh-syntax-highlighting.
Clear is better than clever. The code should be easy to maintain for anyone with a decent knowledge of zsh. Comments should be included when anything needs explanation.
Avoid configuration when possible. Most modules should be self-contained and work out of the box without any necessary configuration. These plugins make a number of opinionated decisions, so some settings may be provided to disable those.

Recommended Installation

Officially antigen is recommended, but it should be possible to load with other plugin managers like zgen or zplug as well.

The following example can be placed in your .zshrc. It will install antigen if it's missing, load antigen, install the zsh-utils repo, and load any specified plugins.

[[ ! -d "$HOME/.antigen" ]] && git clone https://github.com/zsh-users/antigen.git "$HOME/.antigen"
source "$HOME/.antigen/antigen.zsh"

# Set the default plugin repo to be zsh-utils
antigen use belak/zsh-utils --branch=main

# Specify completions we want before the completion module
antigen bundle zsh-users/zsh-completions

# Specify plugins we want
antigen bundle editor@main
antigen bundle history@main
antigen bundle prompt@main
antigen bundle utility@main
antigen bundle completion@main

# Specify additional external plugins we want
antigen bundle zsh-users/zsh-syntax-highlighting

# Load everything
antigen apply

# Set any settings or overrides here
prompt belak
bindkey -e

Provided Plugins

completion - Load and initialize the built-in zsh completion system
editor - Override and fill in the gaps of the default keybinds
history - Load and initilize the built-in zsh history system
prompt - Load and initialize the build-in zsh prompt system
utility - Common shell utilities, aimed at making cross platform work less painful

Plugin Details

For more specific information about the plugins, check out PLUGINS.md.

zsh-utils's People

Contributors

Stargazers

Watchers

Forkers

jsvana tumd hurricanehrndz chrisands tomfromberlin blaradox gregorgebhardt alex-bartleynees lethang7794 robmsmt a322655

zsh-utils's Issues

Update README Antigen instructions

The antigen installation instructions on the README seem to be out of date. Antigen seems to still have issues with repositories that don't use "master" as their default branch. Here is the relevant issue.

Add option, or default, to zcompile .zcompdump

This provides a performance improvement on subsequent Zsh startup. There are even tricks to compile it in the background so it doesn't even effect performance when you do run it, although zcompile shouldn't really take long AGAIK from what it actually does.

Should the completions plugin be enhanced to include more zstyles?

I've spent entirely too much time looking at the zstyle completions available in other projects and cherry picking them into my own config. I'm no completions expert - in fact, completions still feel like a dark art to me (despite pouring over the docs and how-to).

I think robust completions and are a big reason why people stick with the big frameworks (OMZ and Prezto). It's just not something anyone but the most advanced Zsh users seem to grok, but everyone notices and benefits from having good defaults. Which brings me to my point - zsh-utils only includes 2 completion zstyles. Should it include more?

zstyle ':completion::complete:*' use-cache on
zstyle ':completion::complete:*' cache-path "$_zcompcache"

I'm wondering if it makes sense to borrow from other mature projects. For example, both Grml-zshrc and Prezto have variations on the following settings:

zstyle ':completion:*:default'         list-colors ${(s.:.)LS_COLORS}
zstyle ':completion:*:history-words'   list false
zstyle ':completion:*:history-words'   menu yes
zstyle ':completion:*:history-words'   remove-all-dups yes
zstyle ':completion:*:history-words'   stop yes
zstyle ':completion:*:manuals' separate-sections true
zstyle ':completion:*:manuals.(^1*)' insert-sections true

Maybe there's some reasoning here I don't know about why zsh-utlis has an anemic completions plugin, so I wanted to start a convo about so I can get a sense for the project goals and completions philosophy prior to submitting a PR.

References:

Grml zshrc:

$  grep ':completion:' ~/code/github.com/grml/grml-etc-core/etc/zsh/zshrc
    zstyle -a ':grml:completion:compinit' arguments tmp
    zstyle ':completion:*:approximate:'    max-errors 'reply=( $((($#PREFIX+$#SUFFIX)/3 )) numeric )'
    zstyle ':completion:*:complete:-command-::commands' ignored-patterns '(aptitude-*|*\~)'
    zstyle ':completion:*:correct:*'       insert-unambiguous true
    zstyle ':completion:*:corrections'     format $'%{\e[0;31m%}%d (errors: %e)%{\e[0m%}'
    zstyle ':completion:*:correct:*'       original true
    zstyle ':completion:*:default'         list-colors ${(s.:.)LS_COLORS}
    zstyle ':completion:*:descriptions'    format $'%{\e[0;31m%}completing %B%d%b%{\e[0m%}'
    # zstyle ':completion:*:*:cd:*:directory-stack' menu yes select
    zstyle ':completion:*:expand:*'        tag-order all-expansions
    zstyle ':completion:*:history-words'   list false
    zstyle ':completion:*:history-words'   menu yes
    zstyle ':completion:*:history-words'   remove-all-dups yes
    zstyle ':completion:*:history-words'   stop yes
    zstyle ':completion:*'                 matcher-list 'm:{a-z}={A-Z}'
    zstyle ':completion:*:matches'         group 'yes'
    zstyle ':completion:*'                 group-name ''
        zstyle ':completion:*'               menu select=5
    zstyle ':completion:*:messages'        format '%d'
    zstyle ':completion:*:options'         auto-description '%d'
    zstyle ':completion:*:options'         description 'yes'
    zstyle ':completion:*:processes'       command 'ps -au$USER'
    zstyle ':completion:*:*:-subscript-:*' tag-order indexes parameters
    zstyle ':completion:*'                 verbose true
    zstyle ':completion:*:-command-:*:'    verbose false
    zstyle ':completion:*:warnings'        format $'%{\e[0;31m%}No matches for:%{\e[0m%} %d'
    zstyle ':completion:*:*:zcompile:*'    ignored-patterns '(*~|*.zwc)'
    zstyle ':completion:correct:'          prompt 'correct to: %e'
    zstyle ':completion::(^approximate*):*:functions' ignored-patterns '_*'
    zstyle ':completion:*:processes-names' command 'ps c -u ${USER} -o command | uniq'
    zstyle ':completion:*:manuals'    separate-sections true
    zstyle ':completion:*:manuals.*'  insert-sections   true
    zstyle ':completion:*:man:*'      menu yes select
    zstyle ':completion:*:sudo:*' command-path /usr/local/sbin \
    zstyle ':completion:*' special-dirs ..
        zstyle ':completion:*' completer _oldlist _expand _force_rehash _complete _files _ignored
        zstyle -e ':completion:*' completer '
    zstyle ':completion:*:urls' local 'www' '/var/www/' 'public_html'
        zstyle ':completion:*' use-cache  yes
        zstyle ':completion:*:complete:*' cache-path "${GRML_COMP_CACHE_DIR}"
    zstyle ':completion:*:hosts' hosts $hosts
zstyle ':completion:hist-complete:*' completer _history

Oh-My-Zsh:

$ grep ':completion:' ~/code/github.com/ohmyzsh/ohmyzsh/lib/completion.zsh
zstyle ':completion:*:*:*:*:*' menu select
  zstyle ':completion:*' matcher-list 'r:|=*' 'l:|=* r:|=*'
    zstyle ':completion:*' matcher-list 'm:{a-zA-Z-_}={A-Za-z_-}' 'r:|=*' 'l:|=* r:|=*'
    zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}' 'r:|=*' 'l:|=* r:|=*'
zstyle ':completion:*' special-dirs true
zstyle ':completion:*' list-colors ''
zstyle ':completion:*:*:kill:*:processes' list-colors '=(#b) #([0-9]#) ([0-9a-z-]#)*=01;34=0=01'
  zstyle ':completion:*:*:*:*:processes' command "ps -u $USERNAME -o pid,user,comm"
  zstyle ':completion:*:*:*:*:processes' command "ps -u $USERNAME -o pid,user,comm -w -w"
zstyle ':completion:*:cd:*' tag-order local-directories directory-stack path-directories
zstyle ':completion:*' use-cache yes
zstyle ':completion:*' cache-path $ZSH_CACHE_DIR
zstyle ':completion:*:*:*:users' ignored-patterns \

Prezto:

$ grep ':completion:' ~/code/github.com/sorin-ionescu/prezto/modules/completion/init.zsh
zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}
zstyle ':completion:*:default' list-prompt '%S%M matches%s'
zstyle ':completion::complete:*' use-cache on
zstyle ':completion::complete:*' cache-path "${XDG_CACHE_HOME:-$HOME/.cache}/prezto/zcompcache"
if zstyle -t ':prezto:module:completion:*' case-sensitive; then
  zstyle ':completion:*' matcher-list 'r:|[._-]=* r:|=*' 'l:|=* r:|=*'
  zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}' 'r:|[._-]=* r:|=*' 'l:|=* r:|=*'
zstyle ':completion:*:*:*:*:*' menu select
zstyle ':completion:*:matches' group 'yes'
zstyle ':completion:*:options' description 'yes'
zstyle ':completion:*:options' auto-description '%d'
zstyle ':completion:*:corrections' format ' %F{green}-- %d (errors: %e) --%f'
zstyle ':completion:*:descriptions' format ' %F{yellow}-- %d --%f'
zstyle ':completion:*:messages' format ' %F{purple} -- %d --%f'
zstyle ':completion:*:warnings' format ' %F{red}-- no matches found --%f'
zstyle ':completion:*' format ' %F{yellow}-- %d --%f'
zstyle ':completion:*' group-name ''
zstyle ':completion:*' verbose yes
zstyle ':completion:*' completer _complete _match _approximate
zstyle ':completion:*:match:*' original only
zstyle ':completion:*:approximate:*' max-errors 1 numeric
zstyle -e ':completion:*:approximate:*' max-errors 'reply=($((($#PREFIX+$#SUFFIX)/3>7?7:($#PREFIX+$#SUFFIX)/3))numeric)'
zstyle ':completion:*:functions' ignored-patterns '(_*|pre(cmd|exec))'
zstyle ':completion:*:*:-subscript-:*' tag-order indexes parameters
zstyle ':completion:*:*:cd:*' tag-order local-directories directory-stack path-directories
zstyle ':completion:*:*:cd:*:directory-stack' menu yes select
zstyle ':completion:*:-tilde-:*' group-order 'named-directories' 'path-directories' 'users' 'expand'
zstyle ':completion:*' squeeze-slashes true
zstyle ':completion:*:history-words' stop yes
zstyle ':completion:*:history-words' remove-all-dups yes
zstyle ':completion:*:history-words' list false
zstyle ':completion:*:history-words' menu yes
zstyle ':completion::*:(-command-|export):*' fake-parameters ${${${_comps[(I)-value-*]#*,}%%,*}:#-*-}
zstyle -a ':prezto:module:completion:*:hosts' etc-host-ignores '_etc_host_ignores'
zstyle -e ':completion:*:hosts' hosts 'reply=(
zstyle ':completion:*:*:*:users' ignored-patterns \
zstyle ':completion:*:(rm|kill|diff):*' ignore-line other
zstyle ':completion:*:rm:*' file-patterns '*:all-files'
zstyle ':completion:*:*:*:*:processes' command 'ps -u $LOGNAME -o pid,user,command -w'
zstyle ':completion:*:*:kill:*:processes' list-colors '=(#b) #([0-9]#) ([0-9a-z-]#)*=01;36=0=01'
zstyle ':completion:*:*:kill:*' menu yes select
zstyle ':completion:*:*:kill:*' force-list always
zstyle ':completion:*:*:kill:*' insert-ids single
zstyle ':completion:*:manuals' separate-sections true
zstyle ':completion:*:manuals.(^1*)' insert-sections true
zstyle ':completion:*:*:mpg123:*' file-patterns '*.(mp3|MP3):mp3\ files *(-/):directories'
zstyle ':completion:*:*:mpg321:*' file-patterns '*.(mp3|MP3):mp3\ files *(-/):directories'
zstyle ':completion:*:*:ogg123:*' file-patterns '*.(ogg|OGG|flac):ogg\ files *(-/):directories'
zstyle ':completion:*:*:mocp:*' file-patterns '*.(wav|WAV|mp3|MP3|ogg|OGG|flac):ogg\ files *(-/):directories'
  zstyle ':completion:*:*:mutt:*' menu yes select
  zstyle ':completion:*:mutt:*' users ${${${(f)"$(<"$HOME/.mutt/aliases")"}#alias[[:space:]]}%%[[:space:]]*}
zstyle ':completion:*:(ssh|scp|rsync):*' tag-order 'hosts:-host:host hosts:-domain:domain hosts:-ipaddr:ip\ address *'
zstyle ':completion:*:(scp|rsync):*' group-order users files all-files hosts-domain hosts-host hosts-ipaddr
zstyle ':completion:*:ssh:*' group-order users hosts-domain hosts-host users hosts-ipaddr
zstyle ':completion:*:(ssh|scp|rsync):*:hosts-host' ignored-patterns '*(.|:)*' loopback ip6-loopback localhost ip6-localhost broadcasthost
zstyle ':completion:*:(ssh|scp|rsync):*:hosts-domain' ignored-patterns '<->.<->.<->.<->' '^[-[:alnum:]]##(.[-[:alnum:]]##)##' '*@*'
zstyle ':completion:*:(ssh|scp|rsync):*:hosts-ipaddr' ignored-patterns '^(<->.<->.<->.<->|(|::)([[:xdigit:].]##:(#c,2))##(|%*))' '127.0.0.<->' '255.255.255.255' '::1' 'fe80::*'

Is it worth adding Directory and Environment plugins?

There are a few default modules in Prezto that aren't included with zsh-utils (https://github.com/sorin-ionescu/prezto/blob/51c4ff6de4e2d1afd30e52ba19b21b1128fd1ed5/runcoms/zpreztorc#L33-L42):

environment (sets job options, colorizes man pages)
directory (sets directory options and some helpful aliases)
terminal (sets terminal title - there's other plugins for this already)
spectrum (sets some color/effects helpers - seems better as a separate plugin - not core to Zsh)
history-substring-search (a submodule of an existing plugin: zsh-users/zsh-history-substring-search)

Of course the goal isn't to just be a Prezto knockoff, and most of these are better off as separate plugins (terminal, spectrum, and hist-sub-search). But, the environment and directory plugins seem like they have some value. They are simple enough in functionally that they don't merit their own plugin, and their purpose is closely related to setting/configuring Zsh's behavior.

My question is - is it worth adding variations of these to zsh-utils? Were they purposely excluded?

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.