GRMLZSHRC
-August, 2009
+September, 2014
%!target: man
%!postproc(man): "^(\.TH.*) 1 " "\1 5 "
= NAME =
-grmlzshrc - grml's zsh setup
+grmlzshrc - Grml's zsh setup
= SYNOPSIS =
= 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.
behaviour can be altered by setting the **GRML_ALWAYS_LOAD_ALL** STARTUP
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 =
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".
+
+: **GRMLSMALL_SPECIFIC**
+Set this to zero to remove items in zsh config, which do not work in
+grml-small.
+
+: **HISTFILE**
+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
+500, on a hard disk installation to 5000.
+
+: **MAILCHECK**
+Sets the frequency in seconds for zsh to check for new mail. Defaults to 30.
+A value of zero turns off checking.
+
+: **NOCOR**
+Non zero values deactivate automatic correction of commands.
+
+: **NOMENU**
+If set to zero (default), allows selection from a menu, if there are at least
+five possible options of completion.
+
+: **NOPRECMD**
+A non zero value disables precmd and preexec commands. These are functions
+that are run before every command (setting xterm/screen titles etc.).
+
+: **REPORTTIME**
+Show time (user, system and cpu) used by external commands, if they run longer
+than the defined number of seconds (default: 5).
+
+: **SAVEHIST**
+Number of commands to be stored in ${HISTFILE}. Defaults to 1000 on a Grml-CD
+and to 10000 on an installation on hard disk.
+
+: **watch**
+As in tcsh(1) an array of login/logout events to be reported by the shell
+builtin "log". For details see zshparam(1). Defaults to (notme root).
+
+: **ZSH_NO_DEFAULT_LOCALE**
+Import "/etc/default/locale", if set to zero (default).
+
+: **ZSH_PROFILE_RC**
+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 =
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// needs to be done in ".zshrc.pre" because the
+style needs to be set when the main setup is executing! The other styles do not
+have this limitation, but the initial filtering will obviously be done using
+the filters that are configured **at** **that** **point**. 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 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//:
-\
-```
-(( ${+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_<PREVIOUS-PROFILE-NAME>()" before calling the
+profile-function for the new profile.
+
=== Version requirement ===
This feature requires zsh //4.3.3// or newer.
== 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
= REFERENCE =
+== ENVIRONMENT VARIABLES ==
+//grmlzshrc// sets some environment variables, which influence the
+behaviour of applications.
+
+: **COLORTERM**
+Set to "yes". Some applications read this to learn about properties
+of the terminal they are running in.
+
+: **EDITOR**
+If not already set, sets the default editor. Falls back to vi(1),
+if vim(1) is not available.
+
+: **LESS_TERMCAP_***
+Some environment variables that add colour support to less(1) for viewing
+man pages. See termcap(5) for details.
+
+: **MAIL**
+The mailbox file for the current user is set to /var/mail/$USER, if not
+already set otherwise.
+
+: **PAGER**
+Set less(1) as default pager, if not already set to something different.
+
+
+== OPTIONS ==
+Apart from zsh's default options, //grmlzshrc// sets some options
+that change the behaviour of zsh. Options that change Z-shell's default
+settings are marked by <grml>. But note, that zsh's defaults vary depending
+on its emulation mode (csh, ksh, sh, or zsh). For details, see zshoptions(1).
+
+: **append_history**
+Zsh sessions, that use //grmlzshrc//, will append their history list to the
+history file, rather than replace it. Thus, multiple parallel zsh sessions
+will all have the new entries from their history lists added to the history
+file, in the order that they exit. The file will still be periodically
+re-written to trim it when the number of lines grows 20% beyond the value
+specified by $SAVEHIST.
+
+: **auto_cd** <grml>
+If a command is issued that can't be executed as a normal command, and the
+command is the name of a directory, perform the cd command to that directory.
+
+: **auto_pushd** <grml>
+Make cd push the old directory onto the directory stack.
+
+: **completeinword** <grml>
+If the cursor is inside a word, completion is done from both ends;
+instead of moving the cursor to the end of the word first and starting
+from there.
+
+: **extended_glob** <grml>
+Treat the '#', '~' and '^' characters as active globbing pattern characters.
+
+: **extended_history** <grml>
+Save each command's beginning timestamp (in seconds since the epoch) and the
+duration (in seconds) to the history file.
+
+: **hash_list_all**
+Whenever a command completion is attempted, make sure the entire command
+path is hashed first. This makes the first completion slower.
+
+: **histignorealldups** <grml>
+If a new command line being added to the history list duplicates an
+older one, the older command is removed from the list, even if it is
+not the previous event.
+
+: **histignorespace** <grml>
+Remove command lines from the history list when the first character on
+the line is a space, or when one of the expanded aliases contains a
+leading space. Note that the command lingers in the internal history
+until the next command is entered before it vanishes.
+
+: **longlistjobs** <grml>
+List jobs in long format by default.
+
+: **nobeep** <grml>
+Avoid to beep on errors in zsh command line editing (zle).
+
+: **noglobdots**
+A wildcard character never matches a leading '.'.
+
+: **nohup** <grml>
+Do not send the hangup signal (HUP:1) to running jobs when the shell exits.
+
+: **nonomatch** <grml>
+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.
+
+: **pushd_ignore_dups** <grml>
+Don't push multiple copies of the same directory onto the directory stack.
+
+: **share_history** <grml>
+As each line is added to the history file, it is checked to see if anything
+else was written out by another shell, and if so it is included in the
+history of the current shell too. Using !-style history, the commands from
+the other sessions will not appear in the history list unless you explicitly
+type the "history" command. This option is activated for zsh versions >= 4,
+only.
+
+
== KEYBINDINGS ==
Apart from zsh's default key bindings, //grmlzshrc// comes with its own set of
key bindings. Note that bindings like **ESC-e** can also be typed as **ALT-e**
: **ESC-e**
Edit the current command buffer in your favourite editor.
+: **ESC-v**
+Deletes a word left of the cursor; seeing '/' as additional word separator.
+
+: **CTRL-x-1**
+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.
+
+
+=== 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.
-: **2html()**
-Converts plaintext files to HTML using vim. The output is written to
-<filename>.html.
+: **855resolution()**
+If 915resolution is available, issues a warning to the user to run it instead
+to modify the resolution on intel graphics chipsets.
-: **agoogle()**
-Searches for USENET postings from authors using google groups.
+: **accessed()**
+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.
-: **aoeu(), asdf(), uiae()**
-Pressing the 'asdf' keys toggles between dvorak or neon and us keyboard
-layout.
+: **any()**
+Lists processes matching given pattern.
-: **audioburn()**
-Burns the files in ~/ripps (see audiorip() below) to an audio CD.
-Then prompts the user if she wants to remove that directory. You might need
-to tell audioburn which cdrom device to use like:
-"DEVICE=/dev/cdrom audioburn"
-
-: **audiorip()**
-Creates directory ~/ripps, if it does not exist. Then rips audio CD into
-it. Then prompts the user if she wants to burn a audio CD with audioburn()
-(see above). You might need to tell audiorip which cdrom device to use like:
-"DEVICE=/dev/cdrom audioburn"
+: **asc()**
+Login on the host provided as argument using autossh. Then reattach a GNU screen
+session if a detached session is around or detach a currently attached screen or
+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
+use the wodim binary instead. Wodim is the debian fork of Joerg Schillings
+cdrecord.
+
+: **cdt()**
+Creates a temporary directory using mktemp. Then changes current
+working directory to it.
-: **brltty()**
-The brltty(1) program provides a braille display, so a blind person can access
-the console screen. This wrapper function works around problems with some
-environments (f. e. utf8).
+: **changed()**
+Lists files in current directory, which have been changed 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.
+
+: **check_com()**
+Returns true if given command exists either as program, function, alias,
+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 necessary on
+Grml systems with autologin.
: **cl()**
Changes current directory to the one supplied by argument and lists the files
in it, including file names starting with ".".
-: **debbug()**
-Searches the Debian bug tracking system (bugs.debian.org) for Bug numbers,
-email addresses of submitters or any string given on the command line.
+: **dchange()**
+Shows the changelog of given package in $PAGER.
+
+: **dcopyright()**
+Shows the copyright of given package in $PAGER.
-: **debbugm()**
-Shows bug report for debian given by number in mailbox format.
+: **debian2hd()**
+Tells the user to use grml-debootstrap, if she wants to install debian to
+harddisk.
-: **doc()**
-Takes packagename as argument. Sets current working directory to
-/usr/share/doc/<packagename> and prints out a directory listing.
+: **deswap()**
+A trick from $LINUX-KERNELSOURCE/Documentation/power/swsusp.txt. It brings
+back interactive responsiveness after suspend, when the system is swapping
+heavily.
-: **fluxkey-change()**
-Switches the key combinations for changing current workspace under fluxbox(1)
-from Alt-[0-9] to Alt-F[0-9] and vice versa by rewriting $HOME/.fluxbox/keys.
-Requires the window manager to reread configuration to take effect.
+: **dnews()**
+Shows the NEWS file for the given package in $PAGER.
-: **genthumbs()**
-A simple thumbnails generator. Resizes images (i. e. files that end in ".jpg",
-".jpeg", ".gif" or ".png") to 100x200. Output files are named "thumb-<original
-filename>". Creates an index.html with title "Images" showing the
-thumbnails as clickable links to the respective original file.
-//Warning:// On start genthumbs() silently removes a possibly existing "index.html"
-and all files and/or directories beginning with "thumb-" in current directory!
+: **edalias()**
+Edit given alias.
-: **greph()**
-Searches the zsh command history for a regular expression.
+: **edfunc()**
+Edit given shell function.
-: **hex()**
-Prints the hexadecimal representation of the number supplied as argument
-(base ten only).
+: **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.
+
+: **hgstat()**
+Displays diffstat between the revision given as argument and tip (no
+argument means last revision).
+
+: **hidiff()**
+Outputs highlighted diff; needs highstring(1).
: **is4()**
Returns true, if zsh version is equal or greater than 4, 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.
: **isgrmlsmall()**
Returns true, if run on grml-small, else false.
-: **isutfenv()**
-Returns true, if run within an utf environment, else false.
+: **islinux()**
+Returns true, if running on Linux, else false.
-: **lcheck()**
-Lists libraries that define the symbol containing the string given as
-parameter.
+: **iso2utf()**
+Changes every occurrence of the string iso885915 or ISO885915 in
+environment variables to UTF-8.
-: **limg()**
-Lists images (i. e. files ending with ".jpg", ".gif" or ".png") in current
-directory.
+: **isopenbsd()**
+Returns true, if running on OpenBSD, else false.
-: **mcd()**
+: **isutfenv()**
+Returns true, if run within an utf environment, else false.
+
+: **mkcd()**
Creates directory including parent directories, if necessary. Then changes
current working directory to it.
-: **minimal-shell()**
-Spawns a absolute minimal Korn shell. It references no files in /usr, so
-that file system can be unmounted.
-
-: **mkiso()**
-Creates an iso9660 filesystem image with Rockridge and Joliet extensions
-enabled using mkisofs(8). Prompts the user for volume name, filename and
-target directory.
+: **modified()**
+Lists files in current directory, which have been modified 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.
-: **peval()**
-Evaluates a perl expression; useful as command line
-calculator, therefore also available as "calc".
-
-: **purge()**
-Removes typical temporary files (i. e. files like "*~", ".*~", "#*#", "*.o",
-"a.out", "*.core", "*.cmo", "*.cmi" and ".*.swp") from current directory.
-Asks for confirmation.
-
-: **readme()**
-Opens all README-like files in current working directory with the program
-defined in the $PAGER environment variable.
+: **nt()**
+A helper function for the "e" glob qualifier to list all files newer
+than a reference file.
+\
+Example usages:
+```
+% NTREF=/reference/file
+% ls -l *(e:nt:)
+% # Inline:
+% ls -l *(e:'nt /reference/file':)
+```
-: **regcheck()**
-Checks whether a regular expression (first parameter) matches a string
-(second parameter) using perl.
+: **profile()**
+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"
+for details. See also xunfunction() below.
+
+: **simple-extract()**
+Tries to uncompress/unpack given files with the appropriate programs. If an URI
+starting with https, http or ftp is provided simple-extract tries to download
+and then uncompress/unpack the file. The choice is made along the filename
+ending. simple-extract will not delete the original archive (even on .gz,.bz2 or
+.xz) unless you use the '-d' option.
+
+: **sll()**
+Prints details of symlinks given as arguments.
+
+: **ssl-cert-fingerprints**
+Prints the SHA512, SHA256, SHA1 and MD5 digest of a x509 certificate.
+First and only parameter must be a file containing a certificate. Use
+/dev/stdin as file if you want to pipe a certificate to these
+functions.
+
+: **ssl-cert-info**
+Prints all information of a x509 certificate including the SHA512,
+SHA256, SHA1 and MD5 digests. First and only parameter must be a file
+containing a certificate. Use /dev/stdin as file if you want to pipe a
+certificate to this function.
+
+: **ssl-cert-sha512(), ssl-cert-sha256(), ssl-cert-sha1(), ssl-cert-md5()**
+Prints the SHA512, SHA256, SHA1 respective MD5 digest of a x509
+certificate. First and only parameter must be a file containing a
+certificate. Use /dev/stdin as file if you want to pipe a certificate
+to this function.
+
+: **Start(), Restart(), Stop(), Force-Reload(), Reload()**
+Functions for controlling daemons.
+```
+Example usage:
+% Restart ssh
+```
-: **shtar()**
-Lists the content of a gzipped tar archive in default pager.
+: **trans()**
+Translates a word from german to english (-D) or vice versa (-E).
-: **shzip()**
-Shows the content of a zip archive in default pager.
+: **uchange()**
+Shows upstreams changelog of a given package in $PAGER.
-: **slow_print()**
-Prints the arguments slowly by sleeping 0.08 seconds between each character.
+: **uprint()**
+Works around the "print -l ${(u)foo}"-limitation on zsh older than 4.2.
-: **sshot()**
-Creates directory named shots in user's home directory, if it does not yet
-exist and changes current working directory to it. Then sleeps 5 seconds,
-so you have plenty of time to switch desktops/windows. Then makes a screenshot
-of the current desktop. The result is stored in ~/shots to a timestamped
-jpg file.
+: **utf2iso()**
+Changes every occurrence of the string UTF-8 or utf-8 in environment
+variables to iso885915.
-: **startx()**
-Initializes an X session using startx(1) if /etc/X11/xorg.conf exists, else
-issues a Warning to use the grml-x(1) script. Can be overridden by using
-/usr/bin/startx directly.
+: **vim()**
+Wrapper for vim(1). It tries to set the title and hands vim the environment
+variable VIM_OPTIONS on the command line. So the user may define command
+line options, she always wants, in her .zshrc.local.
-: **status()**
-Shows some information about current system status.
+: **whatwhen()**
+Searches the history for a given pattern and lists the results by date.
+The first argument is the search pattern. The second and third ones are
+optional and denote a search range (default: -100).
-: **udiff()**
-Makes a unified diff of the command line arguments trying hard to find a
-smaller set of changes. Descends recursively into subdirectories. Ignores
-hows some information about current status.
+: **xcat()**
+Tries to cat(1) file(s) given as parameter(s). Always returns true.
+See also xunfunction() below.
-: **urlencode()**
-Takes a string as its first argument and prints it RFC 2396 URL encoded to
-standard out.
+: **xsource()**
+Tries to source the file(s) given as parameter(s). Always returns true.
+See zshbuiltins(1) for a detailed description of the source command.
+See also xunfunction() below.
-: **viless()**
-Vim as pager.
+: **xtrename()**
+Changes the title of xterm window from within screen(1). Run without
+arguments for details.
-: **vim()**
-Wrapper for vim(1). It tries to set the title and hands vim the environment
-variable VIM_OPTIONS on the command line. So the user may define command
-line options, she always wants, in her .zshrc.local.
+: **xunfunction()**
+Removes the functions salias, xcat, xsource, xunfunction and zrcautoload.
-: **xinit()**
-Initializes an X session using xinit(1) if /etc/X11/xorg.conf exists, else
-issues a Warning to use the grml-x(1) script. Can be overridden by using
-/usr/bin/xinit directly.
+: **zrcautoload()**
+Wrapper around the autoload builtin. Loads the definitions of functions
+from the file given as argument. Searches $fpath for the file. See also
+xunfunction() above.
-: **zg()**
-Search for patterns in grml's zshrc using perl. zg takes no or exactly one
-option plus a non empty pattern. Run zg without any arguments for a listing
-of available command line switches. For a zshrc not in /etc/zsh, set the
-GRML_ZSHRC environment variable.
+: **zrclocal()**
+Sources /etc/zsh/zshrc.local and ${HOME}/.zshrc.local. These are the files
+where own modifications should go. See also zshbuiltins(1) for a description
+of the source command.
== ALIASES ==
/etc/apt/sources.list. An update should always be performed before an
upgrade or dist-upgrade; run by sudo, if necessary.
-: **calc** (//peval//)
-Evaluates a perl expression (see peval() above); useful as a command line
-calculator.
-
-: **CH** (//./configure --help//)
-Lists available compilation options for building program from source.
-
-: **cmplayer** (//mplayer -vo fbdev//)
-Video player with framebuffer as video output device, so you can watch
-videos on a virtual tty. Hint: Using fbdev2 allows you to use the shell
-while watching a movie.
-
-: **CO** (//./configure//)
-Prepares compilation for building program from source.
-
: **da** (//du -sch//)
Prints the summarized disk usage of the arguments as well as a grand total
in human readable format.
-: **default** (//echo -en [ escape sequence ]//)
-Sets font of xterm to "-misc-fixed-medium-r-normal-*-*-140-*-*-c-*-iso8859-15"
-using escape sequence.
+: **dbp** (//dpkg-buildpackage//)
+Builds binary or source packages from sources (See: dpkg-buildpackage(1)).
+
+: **debs-by-size** (//grep-status -FStatus -sInstalled-Size,Package -n "install ok installed" | paste -sd " \n" | sort -rn//)
+Prints installed Packages sorted by size (descending).
: **dir** (//ls -lSrah//)
Lists files (including dot files) sorted by size (biggest last) in long and
human readable output format.
-: **fblinks** (//links2 -driver fb//)
-A Web browser on the framebuffer device. So you can browse images and click
-links on the virtual tty.
-
-: **fbmplayer** (//mplayer -vo fbdev -fs -zoom//)
-Fullscreen Video player with the framebuffer as video output device. So you
-can watch videos on a virtual tty.
-
-: **g** (//git//)
-Revision control system by Linus Torvalds.
+: **ge** (//grep-excuses//)
+Searches the testing excuses files for a specific maintainer (See:
+grep-excuses(1)).
: **grep** (//grep --color=auto//)
Shows grep output in nice colors, if available.
-: **GREP** (//grep -i --color=auto//)
-Case insensitive grep with colored output.
-
-: **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.
+: **hbp** (//hg-buildpackage//)
+Helper program to maintain Debian packages with mercurial.
+
: **http** (//python -m SimpleHTTPServer//)
Basic HTTP server implemented in python. Listens on port 8000/tcp and
serves current directory. Implements GET and HEAD methods.
: **help-zshglob** (//H-Glob()//)
Runs the function H-Glob() to expand or explain wildcards.
-: **hide** (//echo -en [ escape sequence ]//)
-Tries to hide xterm window using escape sequence.
-
-: **huge** (//echo -en [ escape sequence ]//)
-Sets huge font in xterm ("-misc-fixed-medium-r-normal-*-*-210-*-*-c-*-iso8859-15")
-using escape sequence.
-
: **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.
: **lad** (//ls -d .*(/)//)
Lists the dot directories (not their contents) in current directory.
-: **large** (//echo -en [ escape sequence ]//)
-Sets large font in xterm ("-misc-fixed-medium-r-normal-*-*-150-*-*-c-*-iso8859-15")
-using escape sequence.
-
: **lh** (//ls -hAl --color=auto//)
Lists files in long and human readable output format in nice colors,
if available. Includes file names starting with "." except "." and
: **ll** (//ls -l --color=auto//)
Lists files in long colored output format.
-: **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.
+: **llog** (//$PAGER /var/log/syslog//)
+Opens syslog in pager.
+
+: **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.
: **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.
: **lsx** (//ls -l *(*)//)
Lists only executable files.
-: **md** (//mkdir -p//)
-Creates directory including parent directories, if necessary
-
-: **medium** (//echo -en [ escape sequence ]//)
-Sets medium sized font
-("-misc-fixed-medium-r-normal--13-120-75-75-c-80-iso8859-15") in xterm
-using escape sequence.
-
-: **screen** (///usr/bin/screen -c ${HOME}/.screenrc//)
-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.
-
-: **rw-** (//chmod 600//)
-Grants read and write permission of a file to the owner and nobody else.
-
-: **rwx** (//chmod 700//)
-Grants read, write and execute permission of a file to the owner and nobody
-else.
+: **mdstat** (//cat /proc/mdstat//)
+Lists all active md (i.e. linux software raid) devices with some information
+about them.
-: **r--** (//chmod 644//)
-Grants read and write permission of a file to the owner and read-only to
-anybody else.
+: **mq** (//hg -R $(readlink -f $(hg root)/.hg/patches)//)
+Executes the commands on the versioned patch queue from current repository.
-: **r-x** (//chmod 755//)
-Grants read, write and execute permission of a file to the owner and
-read-only plus execute permission to anybody else.
+: **rmcdir** (//'cd ..; rmdir $OLDPWD || cd $OLDPWD//)
+rmdir current working directory
-: **semifont** (//echo -en [ escape sequence ]//)
-Sets font of xterm to
-"-misc-fixed-medium-r-semicondensed-*-*-120-*-*-*-*-iso8859-15" using
-escape sequence.
-
-: **small** (//echo -en [ escape sequence ]//)
-Sets small xterm font ("6x10") using escape sequence.
-
-: **smartfont** (//echo -en [ escape sequence ]//)
-Sets font of xterm to "-artwiz-smoothansi-*-*-*-*-*-*-*-*-*-*-*-*" using
-escape sequence.
+: **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 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.
-: **tiny** (//echo -en [ escape sequence ]//)
-Sets tiny xterm font
-("-misc-fixed-medium-r-normal-*-*-80-*-*-c-*-iso8859-15") using escape
-sequence.
+: **term2iso** (//echo 'Setting terminal to iso mode' ; print -n '\e%@'//)
+Sets mode from UTF-8 to ISO 2022 (See:
+http://www.cl.cam.ac.uk/~mgk25/unicode.html#term).
-: **truec** (//truecrypt [ mount options ]//)
-Mount a truecrypt volume with some reasonable mount options
-("rw,sync,dirsync,users,uid=1000,gid=users,umask=077" and "utf8", if
-available).
+: **term2utf** (//echo 'Setting terminal to utf-8 mode'; print -n '\e%G'//)
+Sets mode from ISO 2022 to UTF-8 (See:
+http://www.cl.cam.ac.uk/~mgk25/unicode.html#term).
+
+: **tlog** (//tail -f /var/log/syslog//)
+Prints syslog continuously (See tail(1)).
: **up** (//aptitude update ; aptitude safe-upgrade//)
Performs a system update followed by a system upgrade using aptitude; run
by sudo, if necessary. See au and ag above.
-: **?** (//qma zshall//)
-Runs the grml script qma (quick manual access) to build the collected man
-pages for the z-shell. This compressed file is kept at
-~/man/zshall.txt.lzo Once it is built, the second use of the alias '?' is
-fast. See "man qma" for further information.
+: **url-quote** (//autoload -U url-quote-magic ; zle -N self-insert url-quote-magic//)
+After calling, characters of URLs as typed get automatically escaped, if necessary, to
+protect them from the shell.
+
+: **$(uname -r)-reboot** (//kexec -l --initrd=/boot/initrd.img-"$(uname -r)" --command-line=\"$(cat /proc/cmdline)\" /boot/vmlinuz-"$(uname -r)"//)
+Reboots using kexec(8) and thus reduces boot time by skipping hardware initialization of BIOS/firmware.
+
+: **...** (//cd ../..///)
+Changes current directory two levels higher.
= AUXILIARY FILES =
\
```
# show battery status in RPROMPT
-BATTERY=1
+GRML_DISPLAY_BATTERY=1
# always load the complete setup, even for root
GRML_ALWAYS_LOAD_ALL=1
```
% 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
= STATUS =
-This manual page is supposed to be a **reference** manual for //grmlzshrc//.
+This manual page is the **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.
+aspect of the setup.
+
+This manual is currently not complete. If you want to help improving it, visit
+the following pages:
+
+http://wiki.grml.org/doku.php?id=zshrcmanual
+
+http://lists.mur.at/pipermail/grml/2009-August/004609.html
+
+Contributions are highly welcome.
= AUTHORS =
-This manpage was written by Frank Terbeck <ft@grml.org> and Joerg Woelke
-<joewoe@fsmail.de>.
+This manpage was written by Frank Terbeck <ft@grml.org>, Joerg Woelke
+<joewoe@fsmail.de>, Maurice McCarthy <manselton@googlemail.com> and Axel
+Beckert <abe@deuxchevaux.org>.
= COPYRIGHT =
-Copyright (c) 2009, grml project <http://grml.org>
+Copyright (c) 2009-2013 Grml project <http://grml.org>
This manpage is distributed under the terms of the GPL version 2.
Most parts of grml's zshrc are distributed under the terms of GPL v2, too,
-except for **accept-line()** and **vcs_info()**, which are distributed under
-the same conditions as zsh itself (which is BSD-like).
+except for **accept-line()** which are distributed under the same conditions
+as zsh itself (which is BSD-like).
projects / grml-etc-core.git / blobdiff