X-Git-Url: http://git.grml.org/?a=blobdiff_plain;f=doc%2Fgrmlzshrc.t2t;h=11261767db31d34ab74bec535288cfe9c7aa2146;hb=95d0e2fdb605d14b4974a877406c990bd3a89426;hp=89766845797037a84d6725fa7fb453edb2f10eb9;hpb=af590e794babec91bc586d0808b44aa52bdc3b75;p=grml-etc-core.git diff --git a/doc/grmlzshrc.t2t b/doc/grmlzshrc.t2t index 8976684..1126176 100644 --- a/doc/grmlzshrc.t2t +++ b/doc/grmlzshrc.t2t @@ -1,6 +1,6 @@ GRMLZSHRC -July, 2011 +September, 2014 %!target: man %!postproc(man): "^(\.TH.*) 1 " "\1 5 " @@ -44,18 +44,31 @@ zshenv file. Some of the behaviour of //grmlzshrc// can be altered by setting certain shell variables. These may be set temporarily when starting zsh like this: \ -``` % BATTERY=1 zsh +``` % GRML_DISPLAY_BATTERY=1 zsh Or by setting them permanently in **zshrc.pre** (See AUXILIARY FILES below). : **BATTERY** -If set to a value greater than zero and //acpi// installed, //grmlzshrc// will -put the battery status into the right hand side interactive prompt. +Deprecated. Use **GRML_DISPLAY_BATTERY** instead. : **COMMAND_NOT_FOUND** 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//, +//FreeBSD//, //OpenBSD// and //Darwin//. + : **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". @@ -105,6 +118,9 @@ Import "/etc/default/locale", if set to zero (default). A non zero value causes shell functions to be profiled. The results can be obtained with the zprof builtin command (see zshmodules(1) for details). +: **COMPDUMPFILE** +Specifies the location of the completion dump file. Default: $HOME/.zcompdump. + = FEATURE DESCRIPTION = This is an in depth description of non-standard features implemented by @@ -120,6 +136,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 @@ -310,6 +382,53 @@ 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='%~ %# ' +``` + +You also add your own tokens by using the \`grml_theme_add_token()' function. +Call the function without arguments for detailed documentation about that +procedure. == GNU/SCREEN STATUS SETTING == //grmlzshrc// sets screen's hardstatus lines to the currently running command @@ -348,10 +467,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 @@ -464,6 +579,23 @@ Display help on keybindings and zsh line editor. Press consecutively to page thr 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 +yourself, make sure you call the following functions in the respective hook: + +- **zle-line-init**: //zle-smkx// +- **zle-line-finish**: //zle-rmkx// + + +This is **required** so the keybindings set up by //grmlzshrc// work. The +reason for this is to turn the terminal into the right mode while zsh's line +editor (zle) is running. This enables us to query //terminfo// about escape +sequences for special keys and thus simplify and generalise our keybinding +section. + + == SHELL FUNCTIONS == //grmlzshrc// comes with a wide array of defined shell functions to ease the user's life. @@ -477,9 +609,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. @@ -490,9 +619,9 @@ else start a new screen. This is especially useful for roadwarriors using GNU screen and ssh. : **bk()** -Simple backup of a file or directory using cp(1). The target file name is the -original name plus a time stamp attached. Symlinks and file attributes like mode, -ownership and timestamps are preserved. +Simple backup management of a file or directory using standard unix programs. +The target file name is the original name plus a time stamp attached. Symlinks +and file attributes like mode, ownership and timestamps are preserved. : **cdrecord()** If the original cdrecord is not installed, issues a warning to the user to @@ -514,8 +643,8 @@ builtin or reserved word. If the option -c is given, only returns true, if command is a program. : **checkhome()** -Changes directory to $HOME on first invocation of zsh. This is neccessary on -grml systems with autologin. +Changes directory to $HOME on first invocation of zsh. This is necessary on +Grml systems with autologin. : **cl()** Changes current directory to the one supplied by argument and lists the files @@ -524,6 +653,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. @@ -545,6 +677,15 @@ Edit given shell function. : **freload()** Reloads an autoloadable shell function (See autoload in zshbuiltins(1)). +: **grml_vcs_info_toggle_colour()** +Toggles between coloured and uncoloured formats in vcs_info configuration. +This is useful with prompts that break if colour codes are in vcs_info +format expansions (like the `clint' prompt and every other prompt that +uses %v to expand the contents of `$vcs_into_msg_0_'). If you are using +customised vcs_info formats, you shouldn't be using this function, since +it will set all formats to grml's default values (either coloured or plain) +again. + : **hgdi()** Use GNU diff with options -ubwd for mercurial. @@ -576,6 +717,9 @@ Returns true, if zsh version is equal or greater than 4.3.3, else false. : **isdarwin()** Returns true, if running on darwin, else false. +: **isfreebsd()** +Returns true, if running on FreeBSD, else false. + : **isgrml()** Returns true, if running on a grml system, else false. @@ -585,10 +729,16 @@ Returns true, if running on a grml system from a live cd, else false. : **isgrmlsmall()** Returns true, if run on grml-small, else false. +: **islinux()** +Returns true, if running on Linux, else false. + : **iso2utf()** Changes every occurrence of the string iso885915 or ISO885915 in environment variables to UTF-8. +: **isopenbsd()** +Returns true, if running on OpenBSD, else false. + : **isutfenv()** Returns true, if run within an utf environment, else false. @@ -614,7 +764,7 @@ 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()** @@ -784,9 +934,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. @@ -812,7 +959,7 @@ Runs the function H-Glob() to expand or explain wildcards. : **j** (//jobs -l//) Prints status of jobs in the current shell session in long format. -: **l** (//ls -lF --color=auto//) +: **l** (//ls -l --color=auto//) Lists files in long output format with indicator for filetype appended to filename. If the terminal supports it, with colored output. @@ -834,11 +981,10 @@ Lists files in long colored output format. : **llog** (//$PAGER /var/log/syslog//) Opens syslog in pager. -: **ls** (//ls -b -CF --color=auto//) -Lists directory printing octal escapes for nongraphic characters. -Entries are listed by columns and an indicator for file type is appended -to each file name. Additionally the output is colored, if the terminal -supports it. +: **ls** (//ls -C --color=auto//) +Lists directory, entries are listed by columns and an indicator for +file type is appended to each file name. Additionally the output is +colored, if the terminal supports it. : **lsa** (//ls -a .*(.)//) Lists dot files in current working directory. @@ -891,14 +1037,14 @@ 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-CD, dont ask for any password, if she +If user is running a Grml live system, don't ask for any password, if she wants a root shell. : **term2iso** (//echo 'Setting terminal to iso mode' ; print -n '\e%@'//) @@ -937,7 +1083,7 @@ be used to permantenly change //grmlzshrc//'s STARTUP VARIABLES (see above): \ ``` # show battery status in RPROMPT -BATTERY=1 +GRML_DISPLAY_BATTERY=1 # always load the complete setup, even for root GRML_ALWAYS_LOAD_ALL=1 ``` @@ -965,7 +1111,7 @@ On non-debian systems, that is not an option, but all is not lost: % wget -O .zshrc http://git.grml.org/f/grml-etc-core/etc/zsh/zshrc ``` -If you would also like to get seperate function files (which you can put into +If you would also like to get separate function files (which you can put into your **$fpath**), you can browse and download them at: http://git.grml.org/?p=grml-etc-core.git;a=tree;f=usr_share_grml/zsh;hb=HEAD @@ -1114,7 +1260,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.