sdarshanam / zsh-snap

⚡️ Znap! A fast & light-weight Git repo manager & Zsh plugin manager.

⚡️Znap!

Znap is the light-weight Git repo manager & Zsh plugin manager that's easy to grok. While tailored to Zsh plugins specifically, Znap can help you manage Git repos of any kind.

Enjoy using this software? Become a sponsor!.

Installation

Just copy-paste the following into your command line and press Enter:

git clone --depth 1 -- https://github.com/marlonrichert/zsh-snap.git
source zsh-snap/install.zsh

Requirements

Recommended:

• Tested to work with Zsh 5.7 or newer.

Minimum:

• Should theoretically work with Zsh 5.3, but I'm unable to test that. Definitely won't work with anything older.

Features & Usage

Please see the included .zshrc file for examples of how to use Znap in your dotfiles.

Install executables

Download repos simultaneously & symlink their executables to ~/.local/bin:

znap install aureliojargas/clitest bigH/git-fuzzy ekalinin/github-markdown-toc

To remove repos & symlinks, use znap uninstall:

znap uninstall clitest git-fuzzy github-markdown-toc

Automatic compinit and bashcompinit

You no longer need to call complist, compinit or bashcompinit in your .zshrc file. Znap will run these for you as needed.

Named dirs

Znap makes your Git repos dir and all its subdirs of available as named directories:

% ls ~znap  # `ls` your repos dir
% cd ~znap  # `cd` to your repos dir
% cd ~[github-markdown-toc] # `cd` to a repo
% ls ~[asdf]/completions    # `ls` a subdir in a repo
% rm ~[git-fuzzy]           # remove a repo

Automatic cache invalidation

Znap automatically regenerates your comp dump file whenever you install or update a repo or change your .zshrc file.

Znap also automatically regenerates its internal cache for each command when…

• …a cache file is older than the Git index of its associated repo.
• …the last argument of the znap eval statements that produced it has changed. So, if the last argument znap eval contains a variable, then its cached output will be regenerated whenever the variable changes. See the example .zshrc file for a practical use of this.
• …the cache file is missing. You can delete them manually from $XDG_CACHE_HOME/zsh-snap.

Asynchronous compilation

While you are using Zsh, Znap compiles your scripts and functions in the background, when the Zsh Line Editor is idle. This way, your shell will start up even faster next time!

Should you not want this feature, you can disable it with zstyle ':znap:*' auto-compile no. Or if you want to exclude specific files only, you can do so by passing them as absolute-path patterns to the auto-compile-ignore setting. For example:

zstyle ':znap:*' auto-compile-ignore "${ZDOTDIR:-$HOME}/.z*" '**/.editorconfig' '**.md'

In any case, you can compile sources manually at any time with znap compile.

znap command

Usage: znap <command> [ <argument> ... ]

Commands:
  clean     remove outdated .zwc binaries from directories
  clone     make shallow git clones in parallel
  compdef   add output of command as completion function
  compile   compile asynchronously
  eval      eval (cached) output of command
  function  create lazily loaded functions
  help      print help text for command
  ignore    add local exclude patterns to repo
  install   symlink executables from repos to ~/.local/bin
  multi     run tasks in parallel
  prompt    instant prompt from repo
  pull      update repos in parallel
  restart   validate dotfiles & safely restart Zsh
  source    source plugin or repo submodules & scripts
  status    show one-line git status for each repo
  uninstall remove repo and symlinked executables

For more info on a command, type `znap help <command>`.

Author

© 2020 Marlon Richert

License

This project is licensed under the MIT License. See the LICENSE file for details.