NAME

-grmlzshrc - grml's zsh setup +grmlzshrc - Grml's zsh setup

SYNOPSIS

@@ -23,7 +23,7 @@ grmlzshrc - grml's zsh setup

DESCRIPTION

-The grml project provides a fairly exhaustive interactive setup (referred to +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. @@ -36,10 +36,21 @@ features are enabled in every version). grmlzshrc behaves differently depending on which user loads it. For the root user (EUID == 0) only a subset of features is loaded by default. This behaviour can be altered by setting the GRML_ALWAYS_LOAD_ALL STARTUP -VARIABLE (see below). Also the umask(1) for the root user is set to 022, -while for regular users it is set to 002. So read/write permissions -for the regular user and her group are set for new files (keep that -in mind on systems, where regular users share a common group). +VARIABLE (see below). +

+Users may want to keep an up-to-date version of the setup (possibly from the +git-sources) in ~/.zshrc. If that happens on a system where the global +zshrc is also a grmlzshrc (but possibly an older one), you can inhibit +loading the global version by doing: + +

+echo setopt no_global_rcs >> ~/.zshenv
+

+Note, that this will disable ANY global files, except for the global +zshenv file.

STARTUP VARIABLES

@@ -50,7 +61,6 @@ variables. These may be set temporarily when starting zsh like this:

 % BATTERY=1 zsh

Or by setting them permanently in zshrc.pre (See AUXILIARY FILES below).

@@ -65,10 +75,6 @@ A non zero value activates a handler, which is called when a command can not be found. The handler is defined by GRML_ZSH_CNF_HANDLER (see below).

GRML_ALWAYS_LOAD_ALL

-Enables the whole grml setup for root, if set to a non zero value. -

GRML_ZSH_CNF_HANDLER

This variable contains the handler to be used by COMMAND_NOT_FOUND (see above) and defaults to "/usr/share/command-not-found/command-not-found". @@ -84,7 +90,7 @@ Where zsh saves the history. Default: ${HOME}/.zsh_history.

HISTSIZE

-Number of commands to be kept in the history. On a grml-CD this defaults to +Number of commands to be kept in the history. On a Grml-CD this defaults to 500, on a hard disk installation to 5000.

@@ -113,7 +119,7 @@ than the defined number of seconds (default: 5).

SAVEHIST

-Number of commands to be stored in ${HISTFILE}. Defaults to 1000 on a grml-CD +Number of commands to be stored in ${HISTFILE}. Defaults to 1000 on a Grml-CD and to 10000 on an installation on hard disk.

@@ -150,98 +156,127 @@ zshs inherit the dirstack of the zsh that most recently updated

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. +If you need to perform certain actions each time you enter certain +directory-trees, this is the feature you are looking for. +

Initialisation

+To initialise the system, you need to call the function `chpwd_profiles' at +some point in your `zshrc.local'; preferably after you configured the +system. The configuration of the system is described further below. +

+If you need to do initialisations the first time `chpwd_profiles' is called +(which should be in your configuration file), you can do that in a function +called "chpwd_profiles_init". That function needs to be defined before +`chpwd_profiles' is called for this to work. +

+During the first call of `chpwd_profiles' (and therefore all its profile +functions) the parameter `$CHPWD_PROFILES_INIT' exists and is set to `1'. In +all other cases, the parameter does not exist at all. +

Styles and Profile-names

+To store its configuration, the system uses functions and styles +(zsh's context sensitive configuration system), such as this: +

 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). +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. +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: +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
+  /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. +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. +'profile' in your functions. You don't need to do anything, it'll just be +there.

Controlling Profile Execution

-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: +During its initialisation run, the system creates a parameter $CHPWD_PROFILE, +which is set to the profile that was is currently active (the default value is +"default"). 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'. +If you know you are going to do that all the time for each and every +directory-profile function you are ever going to write, you may also set the +`re-execute' style to `false' (which only defaults to `true' for backwards +compatibility), like this: +

+  zstyle ':chpwd:profiles:*' re-execute false
+

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: +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: - +a) If knowing if the profiles feature is active when zsh starts is good +enough for you, you can use the following snippet:

-(( ${+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: - +(( ${+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. +That makes sure you only get notified if a profile is changed, not +everytime you change directory. (To avoid this, you may also set the newer +`re-execute' style like described further above instead of the test on top of +the function. +

Leaving Profiles

+When the system switches from one profile to another, it executes a function +named "chpwd_leave_profile_<PREVIOUS-PROFILE-NAME>()" before calling the +profile-function for the new profile.

Version requirement

@@ -261,7 +296,6 @@ 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>'. @@ -334,6 +368,58 @@ style. (The default is true in all contexts.)

PROMPT

+The grmlzshrc now supplies three prompt themes compatible with zsh's +promptinit system. The three themes are called grml, grml-large and +grml-chroot. +

+By default, grml is used, unless $GRMLPROMPT is set to a value larger +than zero, in which case grml-large is used. Lastly, if $GRML_CHROOT is +non-empty, grml-chroot is used. +

+As usual, with promtinit themes, the user may switch to a different theme using +the prompt utility: + +

+    prompt grml-large
+

+That will use the grml-large prompt theme. +

+The themes are highly customisable. The main source of documentation about +customisation is the main grml theme's doc-string, that is available via +the following command: + +

+    prompt -h grml
+

+The other themes also come with doc-strings, but the main theme's is the +canonical reference about all of them. +

+This feature requires version 4.3.7 of the shell. Older versions will use +the classic grml prompt as a fallback. +

+A note to people who like customisation: If you are not using a prompt +theme for your customisation, but you're either statically setting $PS1 (or +$PROMPT) or you're constructing one of those variables in zsh's \`precmd()' +function, make sure you are turning the zsh's prompt theme system off +before doing so. A correct example customisation could look like this: + +

+    # Turn the prompt system off:
+    prompt off
+    # Customise the prompt yourself:
+    PS1='%~ %# '
+

GNU/SCREEN STATUS SETTING

grmlzshrc sets screen's hardstatus lines to the currently running command @@ -354,10 +440,6 @@ available via the usual history lookup widgets. behaviour of applications.

BROWSER: -If X is running this is set to "firefox", otherwise to "w3m". -
-
COLORTERM: Set to "yes". Some applications read this to learn about properties of the terminal they are running in. @@ -382,11 +464,6 @@ already set otherwise. Set less(1) as default pager, if not already set to something different.
QTDIR: -Holds the path to shared files for the C++ application framework QT -(version 3 or 4). -
-
SHELL: Set explicitly to /bin/zsh, to prevent certain terminal emulators to default to /bin/sh or /bin/bash. @@ -510,10 +587,21 @@ Deletes a word left of the cursor; seeing '/' as additional word separator. Jump right after the first word.
CTRL-x-M(): +Create directory under cursor or the selected area. +To select an area press ctrl-@ and use the cursor. +Use case: you type "mv abc ~/testa/testb/testc/" and remember that the +directory does not exist yet -> press CTRL-xM and problem solved. +
+
CTRL-x-p: Searches the last occurence of string before the cursor in the command history.
CTRL-x-z: +Display help on keybindings and zsh line editor. Press consecutively to page through content. +
+
CTRL-z: Brings a job, which got suspended with CTRL-z back to foreground.

GRMLZSHRC

June, 2010

July, 2011