X-Git-Url: http://git.grml.org/?a=blobdiff_plain;f=doc%2Fgrmlzshrc.t2t;h=46b0170e947cd6c779ee033204f09623e50dc03b;hb=5f07a91fbbec4a04c9dec58355ba94472cfbadb0;hp=ab49647ea5acc884c3ef224a3b28e99d3261eea5;hpb=4780a0efc8678fb270ea4f4e0e4ce1fd25889b9e;p=grml-etc-core.git diff --git a/doc/grmlzshrc.t2t b/doc/grmlzshrc.t2t index ab49647..46b0170 100644 --- a/doc/grmlzshrc.t2t +++ b/doc/grmlzshrc.t2t @@ -55,6 +55,15 @@ Deprecated. Use **GRML_DISPLAY_BATTERY** instead. 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_COMP_CACHING** +If set to //yes// (the default), the setup will enable zsh's completion caching +mechanism, with the caching data being placed into //$GRML_COMP_CACHE_DIR//. + +: **GRML_COMP_CACHE_DIR** +This defines where zsh's completion caching data will be placed, if +//$GRML_COMP_CACHING// is active. The default is //${ZDOTDIR:-$HOME}/.cache//. +The setup will ensure the directory exists before attempting to use it. + : **GRML_DISPLAY_BATTERY** If set to a value greater than zero, //grmlzshrc// will put the battery status into the right hand side interactive prompt. Supported OSes are //GNU/Linux//, @@ -64,6 +73,15 @@ into the right hand side interactive prompt. Supported OSes are //GNU/Linux//, 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". +: **GRML_NO_APT_ALIASES** +A non-empty value inhibits the definition of apt-specific short aliases, +such as ag, agi, ati etc. + +: **GRML_NO_SMALL_ALIASES** +A non-empty value inhibits the definition of 2-letter aliases such as da. +ls, ll, la and other common ls-related aliases are exempt from this, as are +the aliases inhibited by GRML_NO_APT_ALIASES. + : **GRMLSMALL_SPECIFIC** Set this to zero to remove items in zsh config, which do not work in grml-small. @@ -113,6 +131,38 @@ obtained with the zprof builtin command (see zshmodules(1) for details). Specifies the location of the completion dump file. Default: $HOME/.zcompdump. += GRML-ZSHRC SPECIFIC STYLES = + +Styles are a context sensitive configuration mechanism included with zsh. The +shell uses it extensively in sub-systems like the completion and the VCS info +system. It lives outside of the classic shell variable namespace, so it avoids +polluting it. New functionality in grml's zshrc will likely use styles instead +of variables. Some features of the setup (like the directory stack handling) +already use styles. Those styles are documented with the specific features. +This section documents more general styles. + +== Context: :grml:completion:compinit == +This context revolves around the zshrc's //compinit// function call, that +initialises zsh's function based completion system. + +: **arguments** +This style allows the injection of arguments to the command line that is used +to run compinit. It is a list style and its default is the empty list. Using +this style, it's possible to add **-i** to //compinit// in order to disable +//compaudit//. +\ +``` +zstyle ':grml:completion:compinit' arguments -i +``` +\ +Only do this, if you know what sort of security checks are disabled if +//compaudit// is not active and if that's acceptable with your specific setup. +\ +This style has to be set at the point that Grml's zshrc runs //compinit//. A +possible way to achieve this is to set it in //~/.zshrc.pre// (see AUXILIARY +FILES below for details). + + = FEATURE DESCRIPTION = This is an in depth description of non-standard features implemented by //grmlzshrc//. @@ -127,6 +177,62 @@ The **DIRSTACKFILE** is loaded each time zsh starts, therefore freshly started zshs inherit the dirstack of the zsh that most recently updated **DIRSTACKFILE**. +If you would like to //disable// the persistent dirstack feature altogether, +you can do that by setting the boolean //enable// style to //false// in the +right context (the default is //true//): +\ +``` +zstyle ':grml:chpwd:dirstack' enable false +``` + +It is possible to apply a filter to the names of directories that will be +committed to the persistent dirstack file. There are two ways to configure this +filter: A general function based filter and a pattern based filter. Both are +setup via styles in the **':grml:chpwd:dirstack'** context. + +To use a function based filter set the //filter// style for that context to the +name of a function to call every time a directory name is to be added to the +persistent dirstack. If the function's return value signals success (ie. return +value "0"), the directory name is filtered out and **not** added to the +persistent stack. Example: +\ +``` +function my_dirstack_filter() { [[ $1 == /tmp(|/*) ]] } +zstyle ':grml:chpwd:dirstack' filter my_dirstack_filter +``` + +The pattern based filter uses a list of patterns passed to the //exclude// +style in the aforementioned context. Each pattern is tested and the first that +matches will keep the directory name from being added to the persistent stack. +If none of the patterns matches, the name is added. example: +\ +``` +zstyle ':grml:chpwd:dirstack' exclude "/tmp(|/*)" "$HOME/tmp(|/*)" +``` + +The function based filter is more general, the pattern based filter easier to +set up. If both filter variants are used at the same time, the function based +filter will be executed //before// the pattern based one. + +If you would like to apply your filters while //loading// the persistent +dirstack file, set the //filter-on-load// boolean style (the default is +//false//): +\ +``` +zstyle ':grml:chpwd:dirstack' filter-on-load true +``` + +Setting the //filter-on-load// and //enable// styles needs to be done in +".zshrc.pre" because the styles need to be set when the main setup is +executing! The other styles do not have this limitation, but enabling the +system as well as the initial filtering will obviously be done using settings +and filters that are configured **at** **that** **point**. + +With respect to //filter-on-load//, the rule of thumb is: If you want to filter +on load, setup everything in ".zshrc.pre" otherwise ".zshrc.local" works just +as well. + + == DIRECTORY BASED PROFILES == If you need to perform certain actions each time you enter certain @@ -325,7 +431,7 @@ 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 +As usual, with promptinit themes, the user may switch to a different theme using the //prompt// utility: \ ``` @@ -374,8 +480,9 @@ to: **'zsh: '** 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. +shell's history, you can put them into $GRML_IMPORTANT_COMMANDS (which defaults +for backward compatibility to ~/.important_commands) and they will be available +via the usual history lookup widgets. = REFERENCE = @@ -402,10 +509,6 @@ already set otherwise. : **PAGER** Set less(1) as default pager, if not already set to something different. -: **SHELL** -Set explicitly to /bin/zsh, to prevent certain terminal emulators to -default to /bin/sh or /bin/bash. - == OPTIONS == Apart from zsh's default options, //grmlzshrc// sets some options @@ -509,7 +612,7 @@ 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. +Searches the last occurrence 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. @@ -521,7 +624,7 @@ Brings a job, which got suspended with CTRL-z back to foreground. === Customisation === To customise keybindings, you can just use zsh's bindkey utility. However, if -you plan to to use the `//zle-line-init//' or `//zle-line-finish//' hooks +you plan to use the `//zle-line-init//' or `//zle-line-finish//' hooks yourself, make sure you call the following functions in the respective hook: - **zle-line-init**: //zle-smkx// @@ -548,9 +651,6 @@ Lists files in current directory, which have been accessed within the last N days. N is an integer to be passed as first and only argument. If no argument is specified N is set to 1. -: **allulimit()** -Sets all ulimit values to "unlimited". - : **any()** Lists processes matching given pattern. @@ -706,11 +806,11 @@ Example usages: ``` : **profile()** -Runs a command in $SHELL with profiling enabled (See startup variable +Runs a command in zsh with profiling enabled (See startup variable ZSH_PROFILE_RC above). : **salias()** -Creates an alias whith sudo prepended, if $EUID is not zero. Run "salias -h" +Creates an alias with sudo prepended, if $EUID is not zero. Run "salias -h" for details. See also xunfunction() below. : **simple-extract()** @@ -979,11 +1079,11 @@ Executes the commands on the versioned patch queue from current repository. : **rmcdir** (//'cd ..; rmdir $OLDPWD || cd $OLDPWD//) rmdir current working directory -: **screen** (///usr/bin/screen -c ${HOME}/.screenrc//) +: **screen** (//screen -c file//) If invoking user is root, starts screen session with /etc/grml/screenrc -as config file. If invoked by a regular user, start a screen session -with users .screenrc config if it exists, else use /etc/grml/screenrc_grml -as configuration. +as config file. If invoked by a regular user and users .screenc does not exist, +starts screen with /etc/grml/screenrc_grml config if it exists, else fallbacks +to /etc/grml/screenrc. : **su** (//sudo su//) If user is running a Grml live system, don't ask for any password, if she