README.adoc

March 22, 2019 · View on GitHub

: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

Clone this repository somewhere
echo ZDOTDIR=/path/to/repo > ~/.zshenv
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 <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.

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]