1 * ZSH configuration "framework"
3 This is my zsh configuration. Well, more a framework of it.
4 It is setting quite a lot of defaults, but at the same time
5 tries to be as user configurable as makes sense. So most of the
6 settings should be easy (enough) to adjust. I've taken out the most
7 personal stuff, if you want to see my full config you need to merge
8 this repository together with the one over at [[http://git.ganneff.de/cgi-bin/gitweb.cgi?p%3Dzsh-ganneff.git%3Ba%3Dsummary][git.ganneff.de Git -
9 zsh-ganneff.git/summary]]
11 ** The boring stuff, license / copyright
12 It is hard to say what exact license applies: It consists of a lot of
13 snippets taken from a lot of places all over the net, many of which I
14 don't remember anymore. Also, many of which are probably small enough
15 that no copyright would apply.
17 For those I still remember where it is from, I tried to mark them as such,
18 giving credit where its due. Those I know are also listed at the end
19 of this README file. If you find something in here thats from you and
20 want to be mentioned, just mail me.
22 For stuff that is from me, use the following license terms:
24 Copyright (C) 2013, Joerg Jaspert <joerg@ganneff.de>
26 Permission is hereby granted, free of charge, to any person obtaining a
27 copy of this software and associated documentation files (the
28 "Software"), to deal in the Software without restriction, including
29 without limitation the rights to use, copy, modify, merge, publish,
30 distribute, sublicense, and/or sell copies of the Software, and to
31 permit persons to whom the Software is furnished to do so, subject to
32 the following conditions:
34 The above copyright notice and this permission notice shall be included
35 in all copies or substantial portions of the Software.
37 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
38 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
39 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
40 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
41 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
42 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
43 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
46 To correctly use this fileset for zsh, you need to understand the
47 order in which things are loaded by zsh.
49 Note: Wherever $ZDOTDIR is unset, $HOME is used instead
51 1. /etc/zsh/zshenv This is not overridable and not affected by the
52 RCS/GLOBAL_RCS variables explained below!
55 - If the shell is a *login* shell, it continues with
59 - If the shell is *interactive*, it continues with
63 - If the shell is a *login* shell, it continues with
68 On logout it is easier: If the shell exits (not due to exec'ing another
69 process, but logout/exit), it reads
74 There are 2 variables affecting the above ordering.
76 - RCS :: If this is unset, none of the (remaining) startup files
78 - GLOBAL_RCS :: If this is unset, none of the startup files in /etc/zsh
81 Note: These variables do NOT affect /etc/zsh/zshenv, which is
85 For the impatient. Assuming you are in your homedirectory, be careful,
86 it will create a .zsh/ and a .zshenv then. You can also put them
87 anywhere else you like, you only have to adjust the .zshenv symlink.
90 git clone git://git.ganneff.de/zsh.git
91 ln -sf .zsh/zshenv.home ${HOME}/.zshenv
94 The config will detect where your checkout is, if you symlinked
95 =${HOME}/.zshenv= to the checked out =.zsh/zshenv.home=, so you are not forced
96 to put it directly in your home (besides the =${HOME}/.zshenv= which is
97 forced by zsh - somehow it needs to find the rest).
100 1. At startup zsh will read =${HOME}/.zshenv= which sets the environment to load
101 all the rest from =${ZDOTDIR}=. =${ZDOTDIR}= will be defined as the
102 directory to which the symlink =${HOME}/.zshenv= points[fn:1] or
103 =${HOME}/.zsh=. All other files are thus loaded from that directory.
104 2. Next various variables are defined, /${OSNAME}/, /${USER}/, /${UID}/,
105 /${HOST}/, /${DOMAIN}/ and /${DISTRI}/ and then
106 =${ZDOTDIR}/zshenv.local= is loaded.
107 3. /${PATH}/ as well as /${FPATH}/ is setup. Only unique entries and
108 entries that actually exist on the system are kept. That enables us
109 to define a wide range of possibilities in
110 =${ZDOTDIR}/zshenv.local= - the system will only get what it
111 actually can deal with.
112 4. Next file loaded is =${ZDOTDIR}/.zshrc=, which contains the actual
114 1. Depending on the zstyles/variables for debug and zrecompile,
115 functions are setup to support them.
116 2. All files in =${ZDOTDIR}= matching the pattern /??_*.zsh/ are
118 + The file itself is loaded
119 + Then we check a number of subdirectories for the "basename" of
120 the file (the name matching the * in the above pattern)[fn:2]
121 and load the files from there. See [[*Variable%20shell%20configuration][Variable shell configuration]]
123 + Last we check if the same file, with appended /.local/ exists
125 3. If it exists, =${ZDOTDIR}/.zshlate= is loaded
126 4. If configured too, the ZSH startup time is shown
129 If the file =${ZDOTDIR}/zshenv.local= exists it will be read at the
130 very beginning of the zsh startup. At this point only /${ZDOTDIR}/ and
131 the basic /${OSNAME}/, /${USER}/, /${UID}/, /${HOST}/, /${DOMAIN}/ and
132 /${DISTRI}/ have been setup[fn:4], so it is generally not a good idea
133 to do much in this file.
135 For that reason the file is kept simple, if (maybe) long. You can
136 either copy single statements out of =${ZDOTDIR}/zshenv.local.sample=
137 or copy the whole file and then edit it.
139 In general the values defined in that file are commented there, the
140 following rules apply:
142 + Commented entries show the default if the option is not given
143 + Boolean values can be *true*, *yes*, *on*, *1* to enable them,
144 anything else to disable.
145 + Any other value - see its description in the file
147 ** Variable shell configuration
148 If you got a better name, tell me. But that is basically what we do:
149 Configure zsh based on a series of variables. As already written in
150 [[*Startup%20described][Startup described]] we setup a series of variables and load our
151 configuration based on those. This allows us to overwrite or amend
152 configuration depending on where we are - without having to touch the
153 masterfiles. This configuration framework delivers one actual example
154 for this, if you use it on a Debian system you will find extra aliases
155 dealing with its packaging system.
157 Using it is simple: Create the right directory, put a file in, restart
161 User bob wants to set an extra alias on machines inside the bob-lost.de
162 domain, but only if that machine is running Debian. So he executes:
164 mkdir -p ${ZDOTDIR}/net:bob-lost.de/distri:Debian
165 echo 'alias ag=apt-get' >| ${ZDOTDIR}/net:bob-lost.de/distri:Debian/Aliases.zsh
169 User alice wants to adjust the named directory hash table on all her
170 machines, and change one setopt on the machine weirdone.alice-wins.de,
171 but only if that machine is running Debian linux, not if it is booted in
172 kfreebsd or Hurd or RedHat or whatever. So she executes:
174 mkdir -p ${ZDOTDIR}/net:alice-wins.de/host:weirdone/sys:linux/distri:Debian
175 echo 'hash -d foo=/home/alice/foo' >| ${ZDOTDIR}/40_Hashes.zsh.local
176 echo 'setopt beep' >| ${ZDOTDIR}/net:alice-wins.de/host:weirdone/sys:linux/distri:Debian/Options.zsh
179 Of course those examples are constructed and not entirely real-world
180 usable. So here is a real one, from me myself and I for you:
181 On the host franck.debian.org I want a change in my default prompt,
182 adding one variable information to it. So I have the file
183 =${ZDOTDIR}/net:debian.org/host:franck/Prompts.zsh= with the following
188 # Want one more piece in my prompt here, dinstall status
189 zstyle ':prompt:ganneff:left:full:setup' items \
190 ulcorner line openparentheses user at host pts closeparentheses line history \
191 line dinstall line shell-level line flexline openparentheses path closeparentheses line urcorner newline \
192 llcorner line rc openparentheses time closeparentheses line vcs line change-root pipe space
194 zstyle ':prompt:ganneff:extra:dinstall' pre '${PR_CYAN}'
195 zstyle ':prompt:ganneff:extra:dinstall' post '${PR_NO_COLOR}'
196 zstyle ':prompt:ganneff:extra:dinstall' token '$DINSTALL'
197 zstyle ':prompt:ganneff:extra:dinstall' precmd jj_update_dinstall
201 jj_update_dinstall () {
202 DINSTALL="${${(z)${(f)mapfile[/srv/ftp.debian.org/web/dinstall.status]}[2]}[3,-1]}"
211 The prompt i use is based on various others.
212 - The "design" is taken from Phil!'s ZSH prompt, as found on
213 http://aperiodic.net/phil/prompt/
215 - The tech using zstyle is inspired by the prompt as used by
216 the grml-live system <http://grml.org>, see
217 http://git.grml.org/?p=grml-etc-core.git;a=summary for details
219 A good number of their support functions are also taken, though
220 they got renamed from grml_* to ganneff_* to have a single namespace
221 here. (And to direct flames about the bugs to me... :) )
223 - The winch function as seen in the prompt theme "bart", delivered
227 - The is-{alias,builtin,callable,command,function} and zpgrep function
228 have been taken from "zoppo", see [[https://github.com/zoppo][zoppo]] for more of it, which is
229 licensed "under WTFPL unless otherwise noted".
231 - zbell function is Written by Jean-Philippe Ouellet <jpo@vt.edu>
232 and available under the ISC license, taken from [[https://gist.github.com/jpouellet/5278239][hist gist on github]]
236 [fn:1] Actually, the symlink points to the file zshenv.home inside that directory
238 [fn:2] For 01_Terminfo.zsh this would be Terminfo.zsh
240 [fn:3] For 01_Terminfo.zsh this would be, who would have guessed, 01_Terminfo.zsh.local
242 [fn:4] And maybe /${PS4}/ and, /${INITLOG}/ if you turned on tracing in =${HOME}/.zshenv=.