doc/grmlzshrc.t2t

   1 GRMLZSHRC
   2
   3 August, 2009
   4
   5 %!target: man
   6 %!postproc(man): "^(\.TH.*) 1 "  "\1 5 "
   7
   8
   9 = NAME =
  10 grmlzshrc - grml's zsh setup
  11
  12
  13 = SYNOPSIS =
  14 //zsh// [**options**]...
  15
  16
  17 = DESCRIPTION =
  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
  21 setup.
  22
  23 To use //grmlzshrc//, you need at least version 3.1.7 of zsh (although not all
  24 features are enabled in every version).
  25
  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
  29 VARIABLE (see below).
  30
  31 = STARTUP VARIABLES =
  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:
  34 \
  35 ``` % BATTERY=1 zsh
  36
  37 Or by setting them permanently in **zshrc.pre** (See AUXILIARY FILES below).
  38
  39 : **BATTERY**
  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.
  42
  43
  44 = FEATURE DESCRIPTION =
  45 This is an in depth description of non-standard features implemented by
  46 //grmlzshrc//.
  47
  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.
  53
  54 The **DIRSTACKFILE** is loaded each time zsh starts, therefore freshly started
  55 zshs inherit the dirstack of the zsh that most recently updated
  56 **DIRSTACKFILE**.
  57
  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.
  61 \
  62 ```
  63 zstyle ':chpwd:profiles:/usr/src/grml(|/|/*)'   profile grml
  64 zstyle ':chpwd:profiles:/usr/src/debian(|/|/*)' profile debian
  65 ```
  66
  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).
  70
  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
  73 be called.
  74
  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**:
  79 \
  80 ```
  81 /foo/bar
  82 /foo/bar/
  83 /foo/bar/baz
  84 ```
  85
  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.
  88
  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
  91 be there.
  92
  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:
  97 \
  98 ```
  99 function chpwd_profile_grml() {
 100     [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1
 101     ...
 102 }
 103 ```
 104
 105 The initial value for **$CHPWD_PROFILE** is 'default'.
 106
 107 === Signaling availabily/profile changes ===
 108
 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
 111 ways:
 112
 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
 115    //.zshrc.local//:
 116 \
 117 ```
 118 (( ${+functions[chpwd_profiles]} )) &&
 119     print "directory profiles active"
 120 ```
 121
 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:
 125 \
 126 ```
 127 function chpwd_profile_myprofilename() {
 128     [[ ${profile} == ${CHPWD_PROFILE} ]] && return 1
 129     print "chpwd(): Switching to profile: $profile"
 130   ...
 131 }
 132 ```
 133
 134 That makes sure you only get notified if a profile is **changed**,
 135 not everytime you change directory.
 136
 137 === Version requirement ===
 138 This feature requires zsh //4.3.3// or newer.
 139
 140
 141 == ACCEPTLINE WRAPPER ==
 142 The //accept-line// wiget is the one that is taking action when the **return**
 143 key is hit. //grmlzshrc// uses a wrapper around that widget, which adds new
 144 functionality.
 145
 146 This wrapper is configured via styles. That means, you issue commands, that look
 147 like:
 148 \
 149 ```
 150 zstyle 'context' style value
 151 ```
 152
 153 The context namespace, that we are using is 'acceptline'. That means, the actual
 154 context for your commands look like: **':acceptline:<subcontext>'**.
 155
 156 Where **<subcontext>** is one of: **default**, **normal**, **force**, **misc**
 157 or **empty**.
 158
 159
 160 === Recognized Contexts ===
 161 : **default**
 162 This is the value, the context is initialized with.
 163 The //compwarnfmt and //rehash// styles are looked up in this context.
 164
 165 : **normal**
 166 If the first word in the command line is either a command, alias, function,
 167 builtin or reserved word, you are in this context.
 168
 169 : **force**
 170 This is the context, that is used if you hit enter again, after being warned
 171 about the existence of a _completion for the non-existing command you
 172 entered.
 173
 174 : **empty**
 175 This is the context, you are in if the command line is empty or only
 176 consists of whitespace.
 177
 178 : **misc**
 179 This context is in effect, if you entered something that does not match any
 180 of the above. (e.g.: variable assignments).
 181
 182
 183 === Available Styles ===
 184 : **nocompwarn**
 185 If you set this style to true, the warning about non existent commands,
 186 for which completions exist will not be issued. (Default: **false**)
 187
 188 : **compwarnfmt**
 189 The message, that is displayed to warn about the _completion issue.
 190 (default: **'%c will not execute and completion %f exists.'**)
 191 '%c' is replaced by the command name, '%f' by the completion's name.
 192
 193 : **rehash**
 194 If this is set, we'll force rehashing, if appropriate. (Defaults to
 195 **true** in //grmlzshrc//).
 196
 197 : **actions**
 198 This can be a list of wigdets to call in a given context. If you need a
 199 specific order for these to be called, name them accordingly. The default value
 200 is an **empty list**.
 201
 202 : **default_action**
 203 The name of a widget, that is called after the widgets from 'actions'.
 204 By default, this will be '.accept-line' (which is the built-in accept-line
 205 widget).
 206
 207 : **call_default**
 208 If true in the current context, call the widget in the 'default_action'
 209 style. (The default is **true** in all contexts.)
 210
 211
 212 == PROMPT ==
 213
 214
 215 == GNU/SCREEN STATUS SETTING ==
 216 //grmlzshrc// sets screen's hardstatus lines to the currently running command
 217 or **'zsh'** if the shell is idling at its prompt. If the current working
 218 directory is inside a repository unter version control, screen status is set
 219 to: **'zsh: <repository name>'** via zsh's vcs_info.
 220
 221
 222 == PERSISTENT HISTORY ==
 223 If you got commands you consider important enough to be included in every
 224 shell's history, you can put them into ~/.important_commands and they will be
 225 available via the usual history lookup widgets.
 226
 227
 228 = REFERENCE =
 229 == KEYBINDINGS ==
 230 Apart from zsh's default key bindings, //grmlzshrc// comes with its own set of
 231 key bindings. Note that bindings like **ESC-e** can also be typed as **ALT-e**
 232 on PC keyboards.
 233
 234 : **ESC-e**
 235 Edit the current command buffer in your favourite editor.
 236
 237
 238 == SHELL FUNCTIONS ==
 239 //grmlzshrc// comes with a wide array of defined shell functions to ease the
 240 user's life.
 241
 242 : **2html()**
 243 Converts plaintext files to HTML using vim. The output is written to
 244 <filename>.html.
 245
 246 : **cl()**
 247 Changes current directory to the one supplied by argument and lists the files
 248 in it, including file names starting with ".".
 249
 250 : **doc()**
 251 Takes packagename as argument. Sets current working directory to
 252 /usr/share/doc/<packagename> and prints out a directory listing.
 253
 254 : **greph()**
 255 Searches the zsh command history for a regular expression.
 256
 257 : **hex()**
 258 Prints the hexadecimal representation of the number supplied as argument
 259 (base ten only).
 260
 261 : **is4()**
 262 Returns true, if zsh version is equal or greater than 4, else false.
 263
 264 : **is41()**
 265 Returns true, if zsh version is equal or greater than 4.1, else false.
 266
 267 : **is42()**
 268 Returns true, if zsh version is equal or greater than 4.2, else false.
 269
 270 : **is425()**
 271 Returns true, if zsh version is equal or greater than 4.2.5, else false.
 272
 273 : **is43()**
 274 Returns true, if zsh version is equal or greater than 4.3, else false.
 275
 276 : **is433()**
 277 Returns true, if zsh version is equal or greater than 4.3.3, else false.
 278
 279 : **isdarwin()**
 280 Returns true, if running on darwin, else false.
 281
 282 : **isgrml()**
 283 Returns true, if running on a grml system, else false.
 284
 285 : **isgrmlcd()**
 286 Returns true, if running on a grml system from a live cd, else false.
 287
 288 : **isgrmlsmall()**
 289 Returns true, if run on grml-small, else false.
 290
 291 : **isutfenv()**
 292 Returns true, if run within an utf environment, else false.
 293
 294 : **limg()**
 295 Lists images (i. e. files ending with ".jpg", ".gif" or ".png") in current
 296 directory.
 297
 298 : **mcd()**
 299 Creates directory including parent directories, if necessary. Then changes
 300 current working directory to it.
 301
 302 : **readme()**
 303 Opens all README-like files in current working directory with the program
 304 defined in the $PAGER environment variable.
 305
 306 : **shtar()**
 307 Lists the content of a gzipped tar archive in default pager.
 308
 309 : **sshot()**
 310 Creates directory named shots in user's home directory, if it does not yet
 311 exist and changes current working directory to it. Then sleeps 5 seconds,
 312 so you have plenty of time to switch desktops/windows. Then makes a screenshot
 313 of the current desktop. The result is stored in ~/shots to a timestamped
 314 jpg file.
 315
 316 : **startx()**
 317 Initializes an X session using startx(1) if /etc/X11/xorg.conf exists, else
 318 issues a Warning to use the grml-x(1) script. Can be overridden by using
 319 /usr/bin/startx directly.
 320
 321 : **urlencode()**
 322 Takes a string as its first argument and prints it RFC 2396 URL encoded to
 323 standard out.
 324
 325 : **viless()**
 326 Vim as pager.
 327
 328 : **xinit()**
 329 Initializes an X session using xinit(1) if /etc/X11/xorg.conf exists, else
 330 issues a Warning to use the grml-x(1) script. Can be overridden by using
 331 /usr/bin/xinit directly.
 332
 333
 334 == ALIASES ==
 335 //grmlzshrc// comes with a wide array of predefined aliases to ease the user's
 336 life. A few aliases (like those involving //grep// or //ls//) use the option
 337 //--color=auto// for colourizing output. That option is part of **GNU**
 338 implementations of these tools, and will only be used if such an implementation
 339 is detected.
 340
 341 : **cmplayer** (//mplayer -vo fbdev//)
 342 Video player with framebuffer as video output device, so you can watch
 343 videos on a virtual tty. Hint: Using fbdev2 allows you to use the shell
 344 while watching a movie.
 345
 346 : **da** (//du -sch//)
 347 Prints the summarized disk usage of the arguments as well as a grand total
 348 in human readable format.
 349
 350 : **fblinks** (//links2 -driver fb//)
 351 A Web browser on the framebuffer device. So you can browse images and click
 352 links on the virtual tty.
 353
 354 : **fbmplayer** (//mplayer -vo fbdev -fs -zoom//)
 355 Fullscreen Video player with the framebuffer as video output device. So you
 356 can watch videos on a virtual tty.
 357
 358 : **g** (//git//)
 359 Revision control system by Linus Torvalds.
 360
 361 : **grep** (//grep --color=auto//)
 362 Shows grep output in nice colors, if available.
 363
 364 : **GREP** (//grep -i --color=auto//)
 365 Case insensitive grep with colored output.
 366
 367 : **http** (//python -m SimpleHTTPServer//)
 368 Basic HTTP server implemented in python. Listens on port 8000/tcp and
 369 serves current directory. Implements GET and HEAD methods.
 370
 371 : **l** (//ls -lF --color=auto//)
 372 Lists files in long output format with indicator for filetype appended
 373 to filename. If the terminal supports it, with colored output.
 374
 375 : **la** (//ls -la --color=auto//)
 376 Lists files in long colored output format. Including file names
 377 starting with ".".
 378
 379 : **lh** (//ls -hAl --color=auto//)
 380 Lists files in long and human readable output format in nice colors,
 381 if available. Includes file names starting with "." except "." and
 382 "..".
 383
 384 : **ll** (//ls -l --color=auto//)
 385 Lists files in long colored output format.
 386
 387 : **j** (//jobs -l//)
 388 Prints status of jobs in the current shell session in long format.
 389
 390 : **ls** (//ls -b -CF --color=auto//)
 391 Lists directory printing octal escapes for nongraphic characters.
 392 Entries are listed by columns and an indicator for file type is appended
 393 to each file name. Additionally the output is colored, if the terminal
 394 supports it.
 395
 396 : **lsbig** (//ls -flh *(.OL[1,10])//)
 397 Displays the ten biggest files (long and human readable output format).
 398
 399 : **lsd** (//ls -d *(/)//)
 400 Shows directories.
 401
 402 : **lse** (//ls -d *(/^F)//)
 403 Shows empty directories.
 404
 405 : **lsnew** (//ls -rl *(D.om[1,10])//)
 406 Displays the ten newest files (long output format).
 407
 408 : **lsold** (//ls -rtlh *(D.om[1,10])//)
 409 Displays the ten oldest files (long output format).
 410
 411 : **lssmall** (//ls -Srl *(.oL[1,10])//)
 412 Displays the ten smallest files (long output format).
 413
 414 : **lsw** (//ls -ld *(R,W,X.^ND/)//)
 415 Displays all files which are world readable and/or world writable and/or
 416 world executable (long output format).
 417
 418 : **lsx** (//ls -l *(*)//)
 419 Lists only executable files.
 420
 421 : **md** (//mkdir -p//)
 422 Creates directory including parent directories, if necessary
 423
 424 : **screen** (///usr/bin/screen -c ${HOME}/.screenrc//)
 425 If invoking user is root, starts screen session with /etc/grml/screenrc
 426 as config file. If invoked by a regular user, start a screen session
 427 with users .screenrc config if it exists, else use /etc/grml/screenrc_grml
 428 as configuration.
 429
 430 : **rw-** (//chmod 600//)
 431 Grants read and write permission of a file to the owner and nobody else.
 432
 433 : **rwx** (//chmod 700//)
 434 Grants read, write and execute permission of a file to the owner and nobody
 435 else.
 436
 437 : **r--** (//chmod 644//)
 438 Grants read and write permission of a file to the owner and read-only to
 439 anybody else.
 440
 441 : **r-x** (//chmod 755//)
 442 Grants read, write and execute permission of a file to the owner and
 443 read-only plus execute permission to anybody else.
 444
 445
 446 = AUXILIARY FILES =
 447 This is a set of files, that - if they exist - can be used to customize the
 448 behaviour of //grmlzshrc//.
 449
 450 : **.zshrc.pre**
 451 Sourced at the very beginning of //grmlzshrc//. Among other things, it can
 452 be used to permantenly change //grmlzshrc//'s STARTUP VARIABLES (see above):
 453 \
 454 ```
 455 # show battery status in RPROMPT
 456 BATTERY=1
 457 # always load the complete setup, even for root
 458 GRML_ALWAYS_LOAD_ALL=1
 459 ```
 460
 461 : **.zshrc.local**
 462 Sourced right before loading //grmlzshrc// is finished. There is a global
 463 version of this file (/etc/zsh/zshrc.local) which is sourced before the
 464 user-specific one.
 465
 466 : **.zdirs**
 467 Directory listing for persistent dirstack (see above).
 468
 469 : **.important_commands**
 470 List of commands, used by persistent history (see above).
 471
 472
 473 = INSTALLATION ON NON-DEBIAN SYSTEMS =
 474 On Debian systems (http://www.debian.org) - and possibly Ubuntu
 475 (http://www.ubuntu.com) and similar systems - it is very easy to get
 476 //grmlzshrc// via grml's .deb repositories.
 477
 478 On non-debian systems, that is not an option, but all is not lost:
 479 \
 480 ```
 481 % wget -O .zshrc http://git.grml.org/f/grml-etc-core/etc/zsh/zshrc
 482 ```
 483
 484 If you would also like to get seperate function files (which you can put into
 485 your **$fpath**), you can browse and download them at:
 486
 487 http://git.grml.org/?p=grml-etc-core.git;a=tree;f=usr_share_grml/zsh;hb=HEAD
 488
 489
 490 = CONTRIBUTING =
 491 If you want to help to improve grml's zsh setup, clone the grml-etc-core
 492 repository from git.grml.org:
 493 \
 494 ``` % git clone git://git.grml.org/grml-etc-core.git
 495
 496 Make your changes, commit them; use '**git format-patch**' to create a series
 497 of patches and send those to the following address via '**git send-email**':
 498 \
 499 ``` grml-etc-core@grml.org
 500
 501 Doing so makes sure the right people get your patches for review and
 502 possibly inclusion.
 503
 504
 505 = STATUS =
 506 This manual page is supposed to be a **reference** manual for //grmlzshrc//.
 507 That means that in contrast to the existing refcard it should document **every**
 508 aspect of the setup. That is currently **not** the case. Not for a long time
 509 yet. Contributions are highly welcome.
 510
 511
 512 = AUTHORS =
 513 This manpage was written by Frank Terbeck <ft@grml.org> and Joerg Woelke
 514 <joewoe@fsmail.de>.
 515
 516
 517 = COPYRIGHT =
 518 Copyright (c) 2009, grml project <http://grml.org>
 519
 520 This manpage is distributed under the terms of the GPL version 2.
 521
 522 Most parts of grml's zshrc are distributed under the terms of GPL v2, too,
 523 except for **accept-line()** and **vcs_info()**, which are distributed under
 524 the same conditions as zsh itself (which is BSD-like).