<body>
<div class="header" id="header">
<h1>GRMLZSHRC</h1>
-<h3>July, 2011</h3>
+<h3>September, 2014</h3>
</div>
<div class="body" id="body">
<h1>NAME</h1>
</p>
<pre>
-% BATTERY=1 zsh
+% GRML_DISPLAY_BATTERY=1 zsh
</pre>
<p>
Or by setting them permanently in <b>zshrc.pre</b> (See AUXILIARY FILES below).
</p>
<dl>
<dt><b>BATTERY</b></dt><dd>
-If set to a value greater than zero and <i>acpi</i> installed, <i>grmlzshrc</i> will
-put the battery status into the right hand side interactive prompt.
+Deprecated. Use <b>GRML_DISPLAY_BATTERY</b> instead.
<p></p>
</dd>
<dt><b>COMMAND_NOT_FOUND</b></dt><dd>
be found. The handler is defined by GRML_ZSH_CNF_HANDLER (see below).
<p></p>
</dd>
+<dt><b>GRML_COMP_CACHING</b></dt><dd>
+If set to <i>yes</i> (the default), the setup will enable zsh's completion caching
+mechanism, with the caching data being placed into <i>$GRML_COMP_CACHE_DIR</i>.
+<p></p>
+</dd>
+<dt><b>GRML_COMP_CACHE_DIR</b></dt><dd>
+This defines where zsh's completion caching data will be placed, if
+<i>$GRML_COMP_CACHING</i> is active. The default is <i>${ZDOTDIR:-$HOME}/.cache</i>.
+The setup will ensure the directory exists before attempting to use it.
+<p></p>
+</dd>
+<dt><b>GRML_DISPLAY_BATTERY</b></dt><dd>
+If set to a value greater than zero, <i>grmlzshrc</i> will put the battery status
+into the right hand side interactive prompt. Supported OSes are <i>GNU/Linux</i>,
+<i>FreeBSD</i>, <i>OpenBSD</i> and <i>Darwin</i>.
+<p></p>
+</dd>
<dt><b>GRML_ZSH_CNF_HANDLER</b></dt><dd>
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".
<p></p>
</dd>
+<dt><b>GRML_NO_APT_ALIASES</b></dt><dd>
+A non-empty value inhibits the definition of apt-specific short aliases,
+such as ag, agi, ati etc.
+<p></p>
+</dd>
+<dt><b>GRML_NO_SMALL_ALIASES</b></dt><dd>
+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.
+<p></p>
+</dd>
<dt><b>GRMLSMALL_SPECIFIC</b></dt><dd>
Set this to zero to remove items in zsh config, which do not work in
grml-small.
zshs inherit the dirstack of the zsh that most recently updated
<b>DIRSTACKFILE</b>.
</p>
+<p>
+If you would like to <i>disable</i> the persistent dirstack feature altogether,
+you can do that by setting the boolean <i>enable</i> style to <i>false</i> in the
+right context (the default is <i>true</i>):
+
+</p>
+<pre>
+zstyle ':grml:chpwd:dirstack' enable false
+</pre>
+<p>
+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 <b>':grml:chpwd:dirstack'</b> context.
+</p>
+<p>
+To use a function based filter set the <i>filter</i> 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 <b>not</b> added to the
+persistent stack. Example:
+
+</p>
+<pre>
+function my_dirstack_filter() { [[ $1 == /tmp(|/*) ]] }
+zstyle ':grml:chpwd:dirstack' filter my_dirstack_filter
+</pre>
+<p>
+The pattern based filter uses a list of patterns passed to the <i>exclude</i>
+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:
+
+</p>
+<pre>
+zstyle ':grml:chpwd:dirstack' exclude "/tmp(|/*)" "$HOME/tmp(|/*)"
+</pre>
+<p>
+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 <i>before</i> the pattern based one.
+</p>
+<p>
+If you would like to apply your filters while <i>loading</i> the persistent
+dirstack file, set the <i>filter-on-load</i> boolean style (the default is
+<i>false</i>):
+
+</p>
+<pre>
+zstyle ':grml:chpwd:dirstack' filter-on-load true
+</pre>
+<p>
+Setting the <i>filter-on-load</i> and <i>enable</i> 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 <b>at</b> <b>that</b> <b>point</b>.
+</p>
+<p>
+With respect to <i>filter-on-load</i>, the rule of thumb is: If you want to filter
+on load, setup everything in ".zshrc.pre" otherwise ".zshrc.local" works just
+as well.
+</p>
<h2>DIRECTORY BASED PROFILES</h2>
<p>
If you need to perform certain actions each time you enter certain
non-empty, <b>grml-chroot</b> is used.
</p>
<p>
-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 <i>prompt</i> utility:
</p>
<h2>PERSISTENT HISTORY</h2>
<p>
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.
</p>
<h1>REFERENCE</h1>
<h2>ENVIRONMENT VARIABLES</h2>
</dd>
<dt><b>PAGER</b></dt><dd>
Set less(1) as default pager, if not already set to something different.
-<p></p>
-</dd>
-<dt><b>SHELL</b></dt><dd>
-Set explicitly to /bin/zsh, to prevent certain terminal emulators to
-default to /bin/sh or /bin/bash.
</dd>
</dl>
<h2>OPTIONS</h2>
If no argument is specified N is set to 1.
<p></p>
</dd>
-<dt><b>allulimit()</b></dt><dd>
-Sets all ulimit values to "unlimited".
-<p></p>
-</dd>
<dt><b>any()</b></dt><dd>
Lists processes matching given pattern.
<p></p>
<p></p>
</dd>
<dt><b>bk()</b></dt><dd>
-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.
<p></p>
</dd>
<dt><b>cdrecord()</b></dt><dd>
<p></p>
</dd>
<dt><b>checkhome()</b></dt><dd>
-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.
<p></p>
</dd>
<dt><b>cl()</b></dt><dd>
Reloads an autoloadable shell function (See autoload in zshbuiltins(1)).
<p></p>
</dd>
+<dt><b>grml_vcs_info_toggle_colour()</b></dt><dd>
+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.
+<p></p>
+</dd>
<dt><b>hgdi()</b></dt><dd>
Use GNU diff with options -ubwd for mercurial.
<p></p>
Returns true, if running on darwin, else false.
<p></p>
</dd>
+<dt><b>isfreebsd()</b></dt><dd>
+Returns true, if running on FreeBSD, else false.
+<p></p>
+</dd>
<dt><b>isgrml()</b></dt><dd>
Returns true, if running on a grml system, else false.
<p></p>
Returns true, if run on grml-small, else false.
<p></p>
</dd>
+<dt><b>islinux()</b></dt><dd>
+Returns true, if running on Linux, else false.
+<p></p>
+</dd>
<dt><b>iso2utf()</b></dt><dd>
Changes every occurrence of the string iso885915 or ISO885915 in
environment variables to UTF-8.
<p></p>
</dd>
+<dt><b>isopenbsd()</b></dt><dd>
+Returns true, if running on OpenBSD, else false.
+<p></p>
+</dd>
<dt><b>isutfenv()</b></dt><dd>
Returns true, if run within an utf environment, else false.
<p></p>
<p></p>
</dd>
<dt><b>profile()</b></dt><dd>
-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).
<p></p>
</dd>
Prints status of jobs in the current shell session in long format.
<p></p>
</dd>
-<dt><b>l</b> (<i>ls -lF --color=auto</i>)</dt><dd>
+<dt><b>l</b> (<i>ls -l --color=auto</i>)</dt><dd>
Lists files in long output format with indicator for filetype appended
to filename. If the terminal supports it, with colored output.
<p></p>
Opens syslog in pager.
<p></p>
</dd>
-<dt><b>ls</b> (<i>ls -CF --color=auto</i>)</dt><dd>
+<dt><b>ls</b> (<i>ls -C --color=auto</i>)</dt><dd>
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.
rmdir current working directory
<p></p>
</dd>
-<dt><b>screen</b> (<i>/usr/bin/screen -c ${HOME}/.screenrc</i>)</dt><dd>
+<dt><b>screen</b> (<i>screen -c file</i>)</dt><dd>
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.
<p></p>
</dd>
<dt><b>su</b> (<i>sudo su</i>)</dt><dd>
-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.
<p></p>
</dd>
<pre>
# show battery status in RPROMPT
-BATTERY=1
+GRML_DISPLAY_BATTERY=1
# always load the complete setup, even for root
GRML_ALWAYS_LOAD_ALL=1
</pre>
% wget -O .zshrc http://git.grml.org/f/grml-etc-core/etc/zsh/zshrc
</pre>
<p>
-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 <b>$fpath</b>), you can browse and download them at:
</p>
<p>
projects / grml.org.git / blobdiff