The grml project provides a fairly exhaustive interactive setup (referred to
as //grmlzshrc// throughout this document) for the amazing unix shell zsh
(http://zsh.sourceforge.net). This is the reference manual for that
-setup (which is currently vastly incomplete; patches welcome).
+setup.
To use //grmlzshrc//, you need at least version 3.1.7 of zsh (although not all
features are enabled in every version).
//grmlzshrc//.
== DIRSTACK HANDLING ==
+The dirstack in //grmlzshrc// has a persistent nature. It is stored into a
+file each time zsh's working directory is changed. That file can be configured
+via the **DIRSTACKFILE** variable and it defaults to **~/.zdirs**. The
+**DIRSTACKSIZE** variable defaults to **20** in this setup.
+
+The **DIRSTACKFILE** is loaded each time zsh starts, therefore freshly started
+zshs inherit the dirstack of the zsh that most recently updated
+**DIRSTACKFILE**.
== DIRECTORY BASED PROFILES ==
+If you want certain settings to be active in certain directories (and
+automatically switch back and forth between them), this is what you want.
+\
+```
+zstyle ':chpwd:profiles:/usr/src/grml(|/|/*)' profile grml
+zstyle ':chpwd:profiles:/usr/src/debian(|/|/*)' profile debian
+```
+
+When that's done and you enter a directory that matches the pattern
+in the third part of the context, a function called chpwd_profile_grml,
+for example, is called (if it exists).
+
+If no pattern matches (read: no profile is detected) the profile is
+set to 'default', which means chpwd_profile_default is attempted to
+be called.
+
+A word about the context (the ':chpwd:profiles:*' stuff in the zstyle
+command) which is used: The third part in the context is matched against
+**$PWD**. That's why using a pattern such as /foo/bar(|/|/*) makes sense.
+Because that way the profile is detected for all these values of **$PWD**:
+\
+```
+/foo/bar
+/foo/bar/
+/foo/bar/baz
+```
+
+So, if you want to make double damn sure a profile works in /foo/bar
+and everywhere deeper in that tree, just use (|/|/*) and be happy.
+
+The name of the detected profile will be available in a variable called
+'profile' in your functions. You don't need to do anything, it'll just
+be there.
+
+Then there is the parameter **$CHPWD_PROFILE** which is set to the profile,
+that was active up to now. That way you can avoid running code for a
+profile that is already active, by running code such as the following
+at the start of your function:
+\
+```
+function chpwd_profile_grml() {
+ [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1
+ ...
+}
+```
+
+The initial value for **$CHPWD_PROFILE** is 'default'.
+
+=== Signaling availabily/profile changes ===
+
+If you use this feature and need to know whether it is active in your
+current shell, there are several ways to do that. Here are two simple
+ways:
+
+a) If knowing if the profiles feature is active when zsh starts is
+ good enough for you, you can put the following snippet into your
+ //.zshrc.local//:
+\
+```
+(( ${+functions[chpwd_profiles]} )) &&
+ print "directory profiles active"
+```
+
+b) If that is not good enough, and you would prefer to be notified
+ whenever a profile changes, you can solve that by making sure you
+ start **every** profile function you create like this:
+\
+```
+function chpwd_profile_myprofilename() {
+ [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1
+ print "chpwd(): Switching to profile: $profile"
+ ...
+}
+```
+
+That makes sure you only get notified if a profile is **changed**,
+not everytime you change directory.
+
+=== Version requirement ===
+This feature requires zsh //4.3.3// or newer.
+
== ACCEPTLINE WRAPPER ==
+The //accept-line// wiget is the one that is taking action when the **return**
+key is hit. //grmlzshrc// uses a wrapper around that widget, which adds new
+functionality.
+
+This wrapper is configured via styles. That means, you issue commands, that look
+like:
+\
+```
+zstyle 'context' style value
+```
+
+The context namespace, that we are using is 'acceptline'. That means, the actual
+context for your commands look like: **':acceptline:<subcontext>'**.
+
+Where **<subcontext>** is one of: **default**, **normal**, **force**, **misc**
+or **empty**.
+
+
+=== Recognized Contexts ===
+: **default**
+This is the value, the context is initialized with.
+The //compwarnfmt and //rehash// styles are looked up in this context.
+
+: **normal**
+If the first word in the command line is either a command, alias, function,
+builtin or reserved word, you are in this context.
+
+: **force**
+This is the context, that is used if you hit enter again, after being warned
+about the existence of a _completion for the non-existing command you
+entered.
+
+: **empty**
+This is the context, you are in if the command line is empty or only
+consists of whitespace.
+
+: **misc**
+This context is in effect, if you entered something that does not match any
+of the above. (e.g.: variable assignments).
+
+
+=== Available Styles ===
+: **nocompwarn**
+If you set this style to true, the warning about non existent commands,
+for which completions exist will not be issued. (Default: **false**)
+
+: **compwarnfmt**
+The message, that is displayed to warn about the _completion issue.
+(default: **'%c will not execute and completion %f exists.'**)
+'%c' is replaced by the command name, '%f' by the completion's name.
+
+: **rehash**
+If this is set, we'll force rehashing, if appropriate. (Defaults to
+**true** in //grmlzshrc//).
+
+: **actions**
+This can be a list of wigdets to call in a given context. If you need a
+specific order for these to be called, name them accordingly. The default value
+is an **empty list**.
+
+: **default_action**
+The name of a widget, that is called after the widgets from 'actions'.
+By default, this will be '.accept-line' (which is the built-in accept-line
+widget).
+
+: **call_default**
+If true in the current context, call the widget in the 'default_action'
+style. (The default is **true** in all contexts.)
+
== PROMPT ==
+
== GNU/SCREEN STATUS SETTING ==
+//grmlzshrc// sets screen's hardstatus lines to the currently running command
+or **'zsh'** if the shell is idling at its prompt. If the current working
+directory is inside a repository unter version control, screen status is set
+to: **'zsh: <repository name>'** via zsh's vcs_info.
+
== PERSISTENT HISTORY ==
+If you got commands you consider important enough to be included in every
+shell's history, you can put them into ~/.important_commands and they will be
+available via the usual history lookup widgets.
= REFERENCE =
user-specific one.
+
= INSTALLATION ON NON-DEBIAN SYSTEMS =
possibly inclusion.
+= STATUS =
+This manual page is supposed to be a **reference** manual for //grmlzshrc//.
+That means that in contrast to the existing refcard it should document **every**
+aspect of the setup. That is currently **not** the case. Not for a long time
+yet. Contributions are highly welcome.
+
+
= AUTHOR =
This manpage was written by Frank Terbeck <ft@grml.org>.
projects / grml-etc-core.git / blobdiff