The zsh framework made to facilitate management, not dictate it.
Switch branches/tags
Clone or download
5paceToast Abandon r_update.sh
Really, compiling function definitions should not change all that much.
Latest commit 537752b Oct 14, 2018

README.adoc

Toasty Zsh

License

The zsh framework made to facilitate management, not dictate it.

Quickstart

  1. Clone this repository somewhere

  2. echo ZDOTDIR=/path/to/repo > ~/.zshenv

  3. Restart your z shell

Expanding on it

  • Drop files you want to be sourced during startup into $zd/source/

  • Drop functions you want to potentially use/autoload into $zd/functions/

  • Drop plugins you want to source on-demand into $zd/plugins/

  • Drop custom completions into $zd/completions/

  • Drop custom prompts into $zd/prompts/

ℹ️
Most of these are for mindspace separation, the completions, prompts and functions directories are functionally identical, and as such you can use any of them for any purpose.
⚠️
Don’t run compinit yourself! It happens at the very end (after sourcing zshrc.local) as is. All it’ll do is make your performance worse.
ℹ️
If you want $zd to be anywhere but ~/.zsh, set it in ~/.zshenv.

Full List of Supported Installation Methods

Local

  • Setting $ZDOTDIR (usually in ~/.zshenv) to point to the repository.

    ⚠️
    This may, however, dirty your repository, depending on what $ZDOTDIR ends up being used for.
  • Sourcing zshrc in ~/.zshrc.

  • Linking zshrc to ~/.zshrc.

Global

  • Cloning toasty-zsh into /etc/zsh (on distributions with sane/common zsh defaults).

  • Sourcing zshrc in /etc/zsh/zshrc.

  • Linking zshrc to /etc/zsh/zshrc.

⚠️
You may want to touch ~/.zshrc when installing globally, to avoid zsh complaining about it being missing.
ℹ️
If you have a global install of toasty-zsh, or some other framework, and have a local version, you can setopt NO_GLOBAL_RCS in ~/.zshenv to skip loading the global variant.

Structure

Toasty Zsh provides a structure under ~/.zsh for you to use. Everything except zshrc.local is optional.

$zshd

Dynamically set to wherever the Toasty Zsh repository copy is.

$zd

Your "Z Directory". Set to ~/.zsh by default. The rest of this list is inside of this.

completions/

Added to your $fpath. Serves to put custom completions into without muddying up your functions.

functions/

Added to your $fpath. Serves to put your functions into, for autoloading.

plugins/

Added to your $spath. Serves for optionally-sourced plugins. See Autosource for more details.

prompts/

Added to your $fpath. Serves to throw your custom prompts into without muddying up your functions.

source/

Added to your $apath. Serves for automatic sourcing on-demand/startup. See Sourceall for more details.

pre

Sourced right before running Sourceall, giving you a chance to edit the sane-default ${fpath,spath,apath} values.

zshrc.local

Sourced right before compinit.

API

Functions

Various functions for use. Some are used internally.

ℹ️
Enabling (autoloading) a function in zsh defers loading - it makes the function available from the moment you do it, but it won’t be actually loaded until you first use it, making them much more efficient than sourced files.

Autosource

Iterates over $spath until it finds a matching $1, then sources it.

Examples:

spath=( "$PWD" ) autosource a (1)
spath=( a b ) autosource c (2)
spath=( "$PWD" ) autosource foo/bar (3)
  1. will source ./a if it exists

  2. will source ./a/c, and then ./b/c if that fails

  3. will source ./foo/bar if it exists

⚠️
Relative entries will always be relative. If you set $spath to . and then change directories, it’ll continue using ., which is potentially insecure.
ℹ️
For convenience’s sake, $spath and $SPATH are bound - you can manipulate $SPATH (which is formatted like $PATH) to modify $spath.

Sourceall

Will source every file in every directory in $apath. If an argument is provided, will only source files that end in .$1.

Examples:

apath=( a b ) sourceall (1)
apath=( "$PWD" ) sourceall zsh (2)
  1. will source a/ and b/

  2. will source ./*.zsh

ℹ️
By default, Toasty Zsh will run sourceall zsh between sourcing $zd/pre and zshrc.local. By default, it only goes through $zshd/source and $zd/source. You can customize this behavior in $zd/pre.
⚠️
Sourceall does not recurse into subdirectories, though you can work around that by adding a 99-subdir.zsh file or similar where you call it with a custom $apath set.
ℹ️
As with $spath, $apath is bound to a $PATH-like $APATH.

Sprunge

Simple wrapper around Sprunge. Takes things in stdin, outputs the url into stdout.

Examples:

echo hi | sprunge (1)
sprunge < file (2)
bsdtar -cf - --format shar dir | sprunge (3)
  1. upload "hi\n" to sprunge.us

  2. upload file to sprunge.us

  3. upload a "shar" archive of dir to sprunge.us

Plugins

Plugins are just files you source! See Autosource for a convenient way to do so.

You can add your own by dropping them into a directory in your $spath (such as $zd/plugins).

Sudo

Press <esc> twice to either add or remove sudo from the beginning of your line.

If the current line is empty, operates on the previous line instead.

Xterm-Title

Sets up a simple hook system to print what’s currently being executed into an xterm-compatible terminal’s title.

⚠️
some prompts (such as Pure) do this for you aleady! If you use both, they won’t conflict, but you’d be wasting cycles and might see some strange text flashing through on every command.

External Projects

I didn’t write everything in here, some of it is bundled.

Note that you do not pay (except with drive space) for most of these unless you choose to use them.

Plugins

Sudo

From Oh My Zsh.

Prompts

Pure

From Pure.

Purer

From Purer.

Shellder

From Shellder.

Toasty

Written from scratch by me, but takes heavy inspiration from robbyrussel’s theme from Oh My Zsh.

Other

bindkeys.zsh

Written by me, but heavily inspired by similar content from Oh My Zsh and the Zsh Wiki.

Licenses