:icons: font :source-highlighter: pygments :toc: preamble // Links :license: LICENSE.md :example: examples/zshrc.local :img-license: https://img.shields.io/github/license/5pacetoast/toasty-zsh.svg :license-omz: third-party-licenses/LICENSE.OMZ.md :license-pure: third-party-licenses/LICENSE.pure.txt :license-purer: third-party-licenses/LICENSE.purer.txt :license-shellder: third-party-licenses/LICENSE.shellder.txt :repo-omz: https://github.com/robbyrussell/oh-my-zsh[Oh My Zsh] :repo-pure: https://github.com/sindresorhus/pure[Pure] :repo-purer: https://github.com/dfurnes/purer[Purer] :repo-shellder: https://github.com/simnalamburt/shellder[Shellder] :brpaste: https://brpaste.xyz[BRPaste] :sprunge: http://sprunge.us[Sprunge] :zshwiki: http://zshwiki.org[Zsh Wiki] // Github-specific workarounds ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[] = Toasty Zsh image::{img-license}[License, link={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/` NOTE: 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. WARNING: 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. NOTE: 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. + WARNING: 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`. WARNING: You may want to `touch ~/.zshrc` when installing globally, to avoid zsh complaining about it being missing. NOTE: 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 <> 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 <> for more details. pre:: Sourced right before running <>, 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. NOTE: 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: [source,sh] ---- 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 WARNING: Relative entries will always be relative. If you set `$spath` to `.` and then change directories, it'll continue using `.`, which is potentially insecure. NOTE: 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: [source,sh] ---- apath=( a b ) sourceall # <1> apath=( "$PWD" ) sourceall zsh # <2> ---- <1> will source `a/*` and `b/*` <2> will source `./*.zsh` NOTE: 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`. WARNING: 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. NOTE: As with `$spath`, `$apath` is bound to a `$PATH`-like `$APATH`. ==== Brpaste Simple wrapper around {brpaste}. Takes thing in stdin, or uses the first argument as the file to upload. Outputs the paste url. Examples: [source,sh] ---- echo hi | brpaste # <1> brpaste file # <2> bsdtar -cf- --format shar dir | brpaste # <3> brpaste file | xsel -ib # <4> ---- <1> upload "hi\n" to brpaste.xyz <2> upload file to brpaste.xyz <3> upload a "shar" archive of dir to brpaste.xyz <4> upload file to brpaste.xyz and place the non-raw link into the clipboard ==== Sprunge Simple wrapper around {sprunge}. Takes things in stdin, outputs the url into stdout. Examples: [source,sh] ---- 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 <> 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 `` 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. WARNING: some prompts (such as {repo-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 {repo-omz}. === Prompts Pure:: From {repo-pure}. Purer:: From {repo-purer}. Shellder:: From {repo-shellder}. Toasty:: Written from scratch by me, but takes heavy inspiration from robbyrussel's theme from {repo-omz}. === Other `bindkeys.zsh`:: Written by me, but heavily inspired by similar content from {repo-omz} and the {zshwiki}. === Licenses - Oh My Zsh link:{license-omz}[LICENSE] - Pure link:{license-pure}[LICENSE] - Purer link:{license-purer}[LICENSE] - Shellder link:{license-shellder}[LICENSE]