Add zsh anything.el plugin
[zsh.git] / .zsh / README.org
1 * ZSH configuration "framework"
2
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]]
10
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.
16
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.
21
22 For stuff that is from me, use the following license terms:
23
24 Copyright (C) 2013, Joerg Jaspert <joerg@ganneff.de>
25
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:
33
34 The above copyright notice and this permission notice shall be included
35 in all copies or substantial portions of the Software.
36
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.
44 * Usage
45 ** Basics
46 To correctly use this fileset for zsh, you need to understand the
47 order in which things are loaded by zsh.
48
49 Note: Wherever $ZDOTDIR is unset, $HOME is used instead
50 - Always
51 1. /etc/zsh/zshenv This is not overridable and not affected by the
52 RCS/GLOBAL_RCS variables explained below!
53 2. $ZDOTDIR/.zshenv
54
55 - If the shell is a *login* shell, it continues with
56 3. /etc/zsh/zprofile
57 4. $ZDOTDIR/.zprofile
58
59 - If the shell is *interactive*, it continues with
60 5. /etc/zsh/zshrc
61 6. $ZDOTDIR/.zshrc
62
63 - If the shell is a *login* shell, it continues with
64 7. /etc/zsh/zlogin
65 8. $ZDOTDIR/zlogin
66
67
68 On logout it is easier: If the shell exits (not due to exec'ing another
69 process, but logout/exit), it reads
70
71 1. $ZDOTDIR/.zlogout
72 2. /etc/zsh/zlogout
73
74 There are 2 variables affecting the above ordering.
75
76 - RCS :: If this is unset, none of the (remaining) startup files
77 are sourced.
78 - GLOBAL_RCS :: If this is unset, none of the startup files in /etc/zsh
79 are sourced.
80
81 Note: These variables do NOT affect /etc/zsh/zshenv, which is
82 ALWAYS read!
83
84 ** Howto
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.
88
89 #+BEGIN_SRC shell
90 git clone git://git.ganneff.de/zsh.git
91 ln -sf .zsh/zshenv.home ${HOME}/.zshenv
92 #+END_SRC
93
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).
98
99 ** Startup described
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
113 magic.
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
117 loaded.
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]]
122 below for details.
123 + Last we check if the same file, with appended /.local/ exists
124 and load that.[fn:3]
125 3. If it exists, =${ZDOTDIR}/.zshlate= is loaded
126 4. If configured too, the ZSH startup time is shown
127
128 ** zstyle options
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.
134
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.
138
139 In general the values defined in that file are commented there, the
140 following rules apply:
141
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
146
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.
156
157 Using it is simple: Create the right directory, put a file in, restart
158 zsh.
159
160 Example:
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:
163 #+BEGIN_SRC shell
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
166 #+END_SRC
167
168 Example 2:
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:
173 #+BEGIN_SRC shell
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
177 #+END_SRC
178
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
184 content:
185 #+BEGIN_SRC shell
186 # -*- mode: sh;-*-
187
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
193
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
198
199 zmodload zsh/mapfile
200
201 jj_update_dinstall () {
202 DINSTALL="${${(z)${(f)mapfile[/srv/ftp.debian.org/web/dinstall.status]}[2]}[3,-1]}"
203 }
204 #+END_SRC
205
206
207 ** Plugins
208 This framework by default has most of its function included directly,
209 configurable using the zstyle way described already. But there are as
210 many different needs to a shell as there are users of it, so besides
211 all the other flexibility already given, one can easily include
212 "plugins" from wherever.
213
214 Plugins are simply files that contain zsh code. Which can do whatever
215 it wants with your shell, so be careful. One exception: Unless the
216 zstyle /:ganneff:config:pluginbindkeys/ is true, plugins are forbidden to
217 bind keys.
218
219 Two ways to do it:
220 1. Place the plugin you want to load into =${ZDOTDIR}/plugins= or any
221 subdirectory of it, and add the full path and filename, relative to
222 =${ZDOTDIR}/plugins= to the zstyle /ganneff:config:plugins/ in your
223 =${ZDOTDIR}/zshenv.local=.
224 2. For oh-my-zsh style plugins, put the plugin directory into a
225 subdirectory of =${ZDOTDIR}/plugins/ohmy= and add the name to the
226 zstyle /ganneff:config:ohmyplugins/ in your =${ZDOTDIR}/zshenv.local=
227
228 * Sources
229 ** Prompt
230
231 The prompt i use is based on various others.
232 - The "design" is taken from Phil!'s ZSH prompt, as found on
233 http://aperiodic.net/phil/prompt/
234
235 - The tech using zstyle is inspired by the prompt as used by
236 the grml-live system <http://grml.org>, see
237 http://git.grml.org/?p=grml-etc-core.git;a=summary for details
238 on theirs.
239 A good number of their support functions are also taken, though
240 they got renamed from grml_* to ganneff_* to have a single namespace
241 here. (And to direct flames about the bugs to me... :) )
242
243 - The winch function as seen in the prompt theme "bart", delivered
244 with zsh
245
246 ** Various
247 - The is-{alias,builtin,callable,command,function} and zpgrep function
248 have been taken from "zoppo", see [[https://github.com/zoppo][zoppo]] for more of it, which is
249 licensed "under WTFPL unless otherwise noted".
250
251 - zbell function is Written by Jean-Philippe Ouellet <jpo@vt.edu>
252 and available under the ISC license, taken from [[https://gist.github.com/jpouellet/5278239][his gist on github]]
253
254 - extract/ls_archive is from [[https://github.com/sorin-ionescu][Sorin Ionescu]] and available under the MIT
255 License.
256
257 - git-escape-magic is Copyright (c) 2011, 2012 Akinori MUSHA and
258 licensed under the 2-clause BSD license. It is available
259 [[https://github.com/knu/zsh-git-escape-magic][from his github]] repository.
260
261 * Footnotes
262
263 [fn:1] Actually, the symlink points to the file zshenv.home inside that directory
264
265 [fn:2] For 01_Terminfo.zsh this would be Terminfo.zsh
266
267 [fn:3] For 01_Terminfo.zsh this would be, who would have guessed, 01_Terminfo.zsh.local
268
269 [fn:4] And maybe /${PS4}/ and, /${INITLOG}/ if you turned on tracing in =${HOME}/.zshenv=.
270
271