6 %!postproc(man): "^(\.TH.*) 1 " "\1 5 "
10 grmlzshrc - grml's zsh setup
14 //zsh// [**options**]...
18 The grml project provides a fairly exhaustive interactive setup (referred to
19 as //grmlzshrc// throughout this document) for the amazing unix shell zsh
20 (http://zsh.sourceforge.net). This is the reference manual for that
23 To use //grmlzshrc//, you need at least version 3.1.7 of zsh (although not all
24 features are enabled in every version).
26 //grmlzshrc// behaves differently depending on which user loads it. For the
27 root user (**EUID** == 0) only a subset of features is loaded by default. This
28 behaviour can be altered by setting the **GRML_ALWAYS_LOAD_ALL** STARTUP
32 Some of the behaviour of //grmlzshrc// can be altered by setting certain shell
33 variables. These may be set temporarily when starting zsh like this:
37 Or by setting them permanently in **zshrc.pre** (See AUXILIARY FILES below).
40 If set to a value greater than zero and //acpi// installed, //grmlzshrc// will
41 put the battery status into the right hand side interactive prompt.
44 = FEATURE DESCRIPTION =
45 This is an in depth description of non-standard features implemented by
48 == DIRSTACK HANDLING ==
49 The dirstack in //grmlzshrc// has a persistent nature. It is stored into a
50 file each time zsh's working directory is changed. That file can be configured
51 via the **DIRSTACKFILE** variable and it defaults to **~/.zdirs**. The
52 **DIRSTACKSIZE** variable defaults to **20** in this setup.
54 The **DIRSTACKFILE** is loaded each time zsh starts, therefore freshly started
55 zshs inherit the dirstack of the zsh that most recently updated
58 == DIRECTORY BASED PROFILES ==
59 If you want certain settings to be active in certain directories (and
60 automatically switch back and forth between them), this is what you want.
63 zstyle ':chpwd:profiles:/usr/src/grml(|/|/*)' profile grml
64 zstyle ':chpwd:profiles:/usr/src/debian(|/|/*)' profile debian
67 When that's done and you enter a directory that matches the pattern
68 in the third part of the context, a function called chpwd_profile_grml,
69 for example, is called (if it exists).
71 If no pattern matches (read: no profile is detected) the profile is
72 set to 'default', which means chpwd_profile_default is attempted to
75 A word about the context (the ':chpwd:profiles:*' stuff in the zstyle
76 command) which is used: The third part in the context is matched against
77 **$PWD**. That's why using a pattern such as /foo/bar(|/|/*) makes sense.
78 Because that way the profile is detected for all these values of **$PWD**:
86 So, if you want to make double damn sure a profile works in /foo/bar
87 and everywhere deeper in that tree, just use (|/|/*) and be happy.
89 The name of the detected profile will be available in a variable called
90 'profile' in your functions. You don't need to do anything, it'll just
93 Then there is the parameter **$CHPWD_PROFILE** which is set to the profile,
94 that was active up to now. That way you can avoid running code for a
95 profile that is already active, by running code such as the following
96 at the start of your function:
99 function chpwd_profile_grml() {
100 [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1
105 The initial value for **$CHPWD_PROFILE** is 'default'.
107 === Signaling availabily/profile changes ===
109 If you use this feature and need to know whether it is active in your
110 current shell, there are several ways to do that. Here are two simple
113 a) If knowing if the profiles feature is active when zsh starts is
114 good enough for you, you can put the following snippet into your
118 (( ${+functions[chpwd_profiles]} )) &&
119 print "directory profiles active"
122 b) If that is not good enough, and you would prefer to be notified
123 whenever a profile changes, you can solve that by making sure you
124 start **every** profile function you create like this:
127 function chpwd_profile_myprofilename() {
128 [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1
129 print "chpwd(): Switching to profile: $profile"
134 That makes sure you only get notified if a profile is **changed**,
135 not everytime you change directory.
137 === Version requirement ===
138 This feature requires zsh //4.3.3// or newer.
141 == ACCEPTLINE WRAPPER ==
145 == GNU/SCREEN STATUS SETTING ==
147 == PERSISTENT HISTORY ==
153 == SHELL FUNCTIONS ==
154 //grmlzshrc// comes with a wide array of defined shell functions to ease the
158 Takes a string as its first argument and prints it RFC 2396 URL encoded to
163 This is a set of files, that - if they exist - can be used to customize the
164 behaviour of //grmlzshrc//.
167 Sourced at the very beginning of //grmlzshrc//. Among other things, it can
168 be used to permantenly change //grmlzshrc//'s STARTUP VARIABLES (see above):
171 # show battery status in RPROMPT
173 # always load the complete setup, even for root
174 GRML_ALWAYS_LOAD_ALL=1
178 Sourced right before loading //grmlzshrc// is finished. There is a global
179 version of this file (/etc/zsh/zshrc.local) which is sourced before the
183 = INSTALLATION ON NON-DEBIAN SYSTEMS =
187 If you want to help to improve grml's zsh setup, clone the grml-etc-core
188 repository from git.grml.org:
190 ``` % git clone git://git.grml.org/grml-etc-core.git
192 Make your changes, commit them; use '**git format-patch**' to create a series
193 of patches and send those to the following address via '**git send-email**':
195 ``` grml-etc-core@grml.org
197 Doing so makes sure the right people get your patches for review and
202 This manual page is supposed to be a **reference** manual for //grmlzshrc//.
203 That means that in contrast to the existing refcard it should document **every**
204 aspect of the setup. That is currently **not** the case. Not for a long time
205 yet. Contributions are highly welcome.
209 This manpage was written by Frank Terbeck <ft@grml.org>.
213 Copyright (c) 2009, grml project <http://grml.org>
215 This manpage is distributed under the terms of the GPL version 2.
217 Most parts of grml's zshrc are distributed under the terms of GPL v2, too,
218 except for **accept-line()** and **vcs_info()**, which are distributed under
219 the same conditions as zsh itself (which is BSD-like).