X-Git-Url: http://git.grml.org/?a=blobdiff_plain;f=doc%2Fgrmlzshrc.t2t;h=7c75e50b756770b5bdcf57e227f86747adb3d90a;hb=47c6a05460e70adcd1f99dc950d44d6f8c0a61d9;hp=ab7b6e8cca1a280ed37ce2bfa658a88612a49a23;hpb=a9d3f362e00b85b8cc76fab6054191841d75e044;p=grml-etc-core.git diff --git a/doc/grmlzshrc.t2t b/doc/grmlzshrc.t2t index ab7b6e8..7c75e50 100644 --- a/doc/grmlzshrc.t2t +++ b/doc/grmlzshrc.t2t @@ -56,9 +56,6 @@ put the battery status into the right hand side interactive prompt. 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". @@ -124,83 +121,117 @@ 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. + +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. -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: + +=== Controlling Profile Execution === + +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//: -\ -``` -(( ${+functions[chpwd_profiles]} )) && - print "directory profiles active" -``` +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: -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_()" before calling the +profile-function for the new profile. + === Version requirement === This feature requires zsh //4.3.3// or newer. @@ -279,6 +310,50 @@ 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 @@ -382,6 +457,11 @@ A wildcard character never matches a leading '.'. : **nohup** Do not send the hangup signal (HUP:1) to running jobs when the shell exits. +: **nonomatch** +If a pattern for filename generation has no matches, do not print an error +and leave it unchanged in the argument list. This also applies to file +expansion of an initial `~' or `='. + : **notify** Report the status of background jobs immediately, rather than waiting until just before printing a prompt. @@ -488,6 +568,9 @@ in it, including file names starting with ".". : **dchange()** Shows the changelog of given package in $PAGER. +: **dcopyright()** +Shows the copyright of given package in $PAGER. + : **debian2hd()** Tells the user to use grml-debootstrap, if she wants to install debian to harddisk. @@ -581,9 +664,6 @@ Example usages: Runs a command in $SHELL with profiling enabled (See startup variable ZSH_PROFILE_RC above). -: **refunc()** -Reloads functions given as parameters. - : **salias()** Creates an alias whith sudo prepended, if $EUID is not zero. Run "salias -h" for details. See also xunfunction() below. @@ -751,9 +831,6 @@ grep-excuses(1)). : **grep** (//grep --color=auto//) Shows grep output in nice colors, if available. -: **grml-rebuildfstab** (//rebuildfstab -v -r -config//) -Scans for new devices and updates /etc/fstab according to the findings. - : **grml-version** (//cat /etc/grml_version//) Prints version of running grml. @@ -825,9 +902,15 @@ Lists symbolic links in current directory. : **lsnew** (//ls -rl *(D.om[1,10])//) Displays the ten newest files (long output format). +: **lsnewdir** (//ls -rthdl *(/om[1,10]) .*(D/om[1,10])//) +Displays the ten newest directories and ten newest .directories. + : **lsold** (//ls -rtlh *(D.om[1,10])//) Displays the ten oldest files (long output format). +: **lsolddir** (//ls -rthdl *(/Om[1,10]) .*(D/Om[1,10])//) +Displays the ten oldest directories and ten oldest .directories. + : **lss** (//ls -l *(s,S,t)//) Lists files in current directory that have the setuid, setgid or sticky bit set. @@ -1075,7 +1158,7 @@ Beckert . = COPYRIGHT = -Copyright (c) 2009-2011 Grml project +Copyright (c) 2009-2013 Grml project This manpage is distributed under the terms of the GPL version 2.