Znap is the light-weight Git repo manager for Zsh that's easy to grok. While tailored to managing Zsh plugins and dotfiles specifically, Znap also makes it easier to work with multiple Git repos in general.
Enjoy using this software? Become a sponsor!
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
Recommended:
- Zsh 5.7.1 or newer
- Git 2.8 or newer
Minimum:
- Zsh 5.4.2
To update Znap and all of your plugins/repos simultaneously, run
% znap pull
Using Znap to manage your plugins can be as simple as putting this in your .zshrc
file:
# Download Znap, if it's not there yet.
[[ -f ~/Git/zsh-snap/znap.zsh ]] ||
git clone --depth 1 -- \
https://github.com/marlonrichert/zsh-snap.git ~/Git/zsh-snap
source ~/Git/zsh-snap/znap.zsh # Start Znap
# `znap prompt` makes your prompt visible in just 15-40ms!
znap prompt sindresorhus/pure
# `znap source` automatically downloads and starts your plugins.
znap source marlonrichert/zsh-autocomplete
znap source zsh-users/zsh-autosuggestions
znap source zsh-users/zsh-syntax-highlighting
# `znap eval` caches and runs any kind of command output for you.
znap eval iterm2 'curl -fsSL https://iterm2.com/shell_integration/zsh'
# `znap function` lets you lazy-load features you don't always need.
znap function _pyenv pyenv 'eval "$( pyenv init - --no-rehash )"'
compctl -K _pyenv pyenv
For more examples of what Znap can do for your dotfiles, please see the included .zshrc
file.
Additionaly, Znap makes it so that you actually need to have less in your .zshrc
file, by
automating several tasks for you.
Note that the above example does not include any call to
complist
,
compinit
, or
bashcompinit
in
the .zshrc
file. That is because Znap will run these for you as needed.
Znap compiles your scripts and functions in the background. 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
In any case, you can compile sources manually at any time with
znap compile [ <dir> | <file> ] ...
.
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 toznap 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/eval
.
When using git
2.31.0 or newer, Znap automatically enables git maintenance
in each repo that it
manages. This automatically optimizes your repos in the background, so that your git
and znap
commands will run faster.
To selectively disable this feature, add
zstyle ':znap:*:<glob pattern>' git-maintenance off
to your .zshrc
file. Next time you run znap pull
, git maintenance
will then be disabled for
each repo whose name matches <glob pattern>
.
Use *
as your glob
pattern to opt out of
this feature completely.
Znap also makes life on the command line easier. For a full list of available commands, just run
% znap
Exhaustive tab-completion is available, too. For examples of the most important command-line features, see below.
Note:
- The examples in this section you should run on the command line, not add to your
.zshrc
file!%
represents the prompt. You shouldn't type that part. 🙂
Znap can download multiple repos in parallel, then automatically find and install their executables and completion functions, with just one command:
% znap install asdf-vm/asdf aureliojargas/clitest bigH/git-fuzzy \
ekalinin/github-markdown-toc ohmyzsh/ohmyzsh zsh-users/zsh-completions
To remove these (and their repos), use znap uninstall
:
% znap uninstall asdf clitest git-fuzzy \
github-markdown-toc ohmyzsh zsh-completions
Executables are installed in ~/.local/bin
, while completion functions go to
${XDG_DATA_HOME:-~/.local/share}/zsh/site-functions
.
Some commands generate output that should be loaded as a function. You can install these generated functions as follows:
% znap fpath _kubectl 'kubectl completion zsh'
% znap fpath _rustup 'rustup completions zsh'
% znap fpath _cargo 'rustup completions zsh cargo'
These functions, too, are saved to ${XDG_DATA_HOME:-~/.local/share}/zsh/site-functions
.
Znap makes your repos dir and all of its subdirs available as named directories:
% cd ~znap # `cd` to your repos dir
% cd ~[github-markdown-toc] # `cd` to a repo
% ls ~[asdf]/completions # `ls` a subdir in a repo
© 2020-2021 Marlon Richert
This project is licensed under the MIT License. See the LICENSE file for details.