From 5d2b2a776e3ae1145c25d147869371c3ddf1b274 Mon Sep 17 00:00:00 2001 From: Hector Date: Thu, 1 Feb 2018 15:19:47 -0800 Subject: [PATCH 1/3] Proposed enhancements to runcoms repo documentation --- runcoms/README.md | 216 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 177 insertions(+), 39 deletions(-) diff --git a/runcoms/README.md b/runcoms/README.md index 9df890e51a..cc8a4e3518 100644 --- a/runcoms/README.md +++ b/runcoms/README.md @@ -10,61 +10,199 @@ in */etc* by default. User-local configuration files have the same name as their global counterparts but are prefixed with a dot (hidden). Zsh looks for these files in the path -stored in the `$ZDOTDIR` environmental variable. However, if said variable is -not defined, Zsh will use the user's home directory. +stored in the `$ZDOTDIR` environment variable. However, if said variable is +not defined, Zsh will use the user's home directory. This is found on the +config scripts as `${ZDOTDIR:-$HOME}` and is a `zsh` idiomatic way of doing +something like this: -File Descriptions ------------------ - -The configuration files are read in the following order: - 01. /etc/zshenv - 02. ~/.zshenv - 03. /etc/zprofile - 04. ~/.zprofile - 05. /etc/zshrc - 06. ~/.zshrc - 07. ~/.zpreztorc - 08. /etc/zlogin - 09. ~/.zlogin - 10. ~/.zlogout - 11. /etc/zlogout +```bash +if [[ -n $ZDOTDIR ]]; then + DOTFILES_PATH=$ZDOTDIR +else + DOTFILES_PATH=$HOME +fi +source $DOTFILES_PATH/.zshenv -### zshenv +#pro tip! set $ZDOTDIR on /etc/zshenv to ~/.zconf to have all runcoms live there instead of cluttering ~ =) +``` +the above is the same as: `source ${ZDOTDIR:-$HOME}/.zshenv` is equivalent to: -This file is sourced by all instances of Zsh, and thus, it should be kept as -small as possible and should only define environment variables. -### zprofile +Sourcing of these confguration files depends mostly on 2 things: -This file is similar to zlogin, but it is sourced before zshrc. It was added -for [KornShell][1] fans. See the description of zlogin below for what it may -contain. +1. Whether you are running a *login shell* +2. Whether the `RCS` and `GLOBAL_RCS` options are set. They are usually + set by default -zprofile and zlogin are not meant to be used concurrently but can be done so. -### zshrc +File Descriptions +----------------- -This file is sourced by interactive shells. It should define aliases, -functions, shell options, and key bindings. -### zpreztorc +| always runs | when `GLOBAL_RCS` is set | when `RCS` is set | Purpose | stuff that usually goes there, and notes | +|------------------|-----------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/etc/zshenv` | | | system provided minimal environment | Always runs! should be minimal set ZDOTDIR, minimal environment. system paths +| | | `${ZDOTDIR:-$HOME}/.zshenv` | user environment overrides non-interactive, non-login shells (when invoked via shebang in a script or via `zsh -c [script]` or when invoked by `make` | personal environment overrides, such as `MANPATH`, `TERM`, `fpath` *non interactive scripts should have their environment completly set up here* ) +| | `/etc/zshprofile` | | system profile for login shells (`zsh -ls zsh - or via _ssh forced command_`) | minimal system paths for remote interaction, site `fpath`, site `$LOCALE`, lang. +| | | `${ZDOTDIR:-$HOME}/.zshprofile` | personal preferences for interactive login shells | your preferred `$LOCALE`, `$LANG`, `readlne` config, `cdpath`, session managers, additional `fpath` ) login shells (but non necessarily **ineractive** as when invoked via _ssh remote cmd_ ) will read config up to this point +| | `/etc/zshrc` | | system provided startup script, for interactive shells, (local shells that live in an `XTerm`, `URxvt`, `gnome-terminal`) or subshells (like running `xterm` from the command prompt of a _login xterm_, | site login accounting, security monitors, site command logging policy +| | | `${ZDOTDIR:-$HOME}/.zshrc` | user customization of their *interactive* environment for terminals | sourcing custom completions (`gcloud.comp.inc`), custom user frameworks (zprezto is invoked here), additional path required by custom software installed in `/opt/*` +| | `/etc/zshlogin` | | additional customization for interactive **login** shells, such as those accessed via ssh | tmux attach to existing session +| | | `${ZDOTDIR:-$HOME}/.zshlogin` | user script for *login shell startup* (this shell is a session leader, and allocates a `ptty` | aliases, keybindings, personal startup programs, time tracking apps, session managers, quote of the day, fortunes +| .. | ... your shell session happens here ... | +| | | `${ZDOTDIR:-$HOME}/.zshlogout` | personal cleanup tasks | setting personal `crontabs` or `at` tasks, logging checout to your time tracking software, fortune to say goodbye. +| `/etc/zshlogout` | | | site cleanup tasks | site command logging policy stop, login accounting records, security context spindown, etcThe configuration files are read in the following order: + +Discussion +---------- + +There are several places to add personal configuration and preferences in +the files already provided for startup, it’s just a matter of placing them +in the appropriate place. Most of them should probably go in +`${ZDOTDIR:-$HOME}/.zshrc` **before** invoking zprezto init, to choose +the modules that should get loaded, and using the appropriate `zstyle` +calls form preferences (`zstyle` is a kind of _registry_ for shell configuration +native to `zsh`) + + +Any tweaks to prezto’s behavior should go **after** invoking zprezto init +in `zshrc` or, in `${ZDOTDIR:-$HOME}/.zlogin` . Note however that the +`zlogin` (sysem or user) files will be sourced **only for login shells**. + +That means, when logging in to a remote system via ssh for example or +when calling say, `XTerm` or your favorite emulator by specifying you +want a **login** shell (by calling `zsh -ls` instead of plain `zsh`). +Otherwise, the `zlogin` files are ignored. + +Also, note that another difference between interactive login shells and +plain interactive shells, is that, besides sourcing `zlogin` files, +interactive login shells also allocate a pseudo-tty (you can see them when +invoking `w`. Login shells have a pty assigned, while interactive non-login +shells don't.) + +Why is this designed this way? because login shells are assumed to be +the main point of interaction with a user while non login shells would +be spawned as _sub-shells_ of a *login shell* , when executing scripts +that call `zsh` as a command interpreter, for example, when the *shebang* is +`#!/usr/bin/env zsh` or equivalent. + +When launching a new terminal within an *X11* session, it is safe to +assume that you are *already logged in* so any terminal emulator will +launch an *interactive-non-login* shell. Which is, _per specification_ +the correct behavior, but not the behavior most users *expect*. + + +There is a reason for this _specified_ behaviour: `zlogin` files should +be used for *interaction oriented settings* such as custom completion, +keybindings, `tmux` session setup, and most `alias`es. + +The advantage of grouping all interaction oriented settings in +`.zlogin` is that non-interactive shells (executing scripts via +`zsh -c [script]`, the *shebang*, subshells or `make` invoked shells, +for example) will not be burdened by additional config settings making +them faster and more responsive, as _keybindings_ and _aliases_ are not +even loaded at startup, after all, an _executable non-interactive script_, +should never call on keybindings or aliases (assuming they were properly +written to be portable) + + +Finally, it is a common source of frustration amongst graphical environment +users, to spend some time adding their customizations to `.zlogin` only +to see them ignored when launching a new `XTerm` or `tmux` pane. + +This can be solved by calling (or aliasing) your terminal emulator with +the required option to invoke a *login* shell, for `XTerm`, for example +you would call `xterm -e zsh -ls` on tmux you may add one of the following +lines to your `.tmux.conf`: + +```config +#tmux.conf: + + set -g default-command 'exec /usr/bin/zsh -ls' #this will make zsh a login shell AND a session leader + set -g default-shell '/usr/bin/zsh -ls' +``` + +Here is an examplefor *i3wm* on ubuntu +```bash + +#i3wm.conf: + ... + set $XTERM_CMD='xterm -e zsh -ls` + bind $mod+x $XTERM_CMD + ... +``` +if you want to replace your non-login shell on your emulator with a brand-new +shiny *login* shell you can issue `exec zsh -ls` at your command prompt. +Doing this, however **will not write that terminal’s history to file** unless +`INC_APPEND_HISTORY` was set when you strted the shell + +`INC_APPEND_HISTORY` makes `zsh` append history entries as soon as the +command is finished. *zprezto* helpfuly sets `INC_APPEND_HISTORY`, +`INC_APPEND_HISTORY_TIME`, and `SHARE_HISTORY` which makes your history +available immediately from different terminals on command completion, +and records execution time on the history file. Pretty neat, huh?) + +You could tack-on all interactive customizations on `zshrc` but you will +end up with bloated shells on non-interactive environments. Perhaps desktop +workstation users will not notice any difference, but in resource-constrained +environments it may be significant in terms of execution time and energy +consumption (v.gr when running a Raspberry PI on batteries or on a cell +phone environment such as `termux`) + +You may be thinking... why is `zpreztorc` not invoked on `.zlogin` instead +of `.zshrc`? I believe it was a wise design decision, in order to +eliminate complexity by having the whole of *prezto* configured and +launched from a single point, as some of the modules need to be sourced +early in the startup process, `editor` and `gnu-utls` come to mind. +If invoked later on the startup, such as would be the case in `.zlogin` +would makee it easier to conflict with stuff users may add on `zshrc`. +Also, it avoids **not being loaded** and causing user frustration if +the user launches *non-login shells* from graphical environments, as +discussed above. + +## Conclusion + +For customization of your environment, use your `.zshrc` after zprezto +has been invoked, or before to remove or activate packages via `zstyle` +calls + + or + +use `.zshlogin` to override or tweak zprezto behavior. there is also +`.zpreztorc` but you may want to leave that one alone. + +In any case, this question is often brought up by users that use the +distributed *runcoms* **as is** which is a terrible idea, since doing +`git pull` to update your distribution will clobber your customizations. + +it’s a better idea to *copy* the distributed *runcoms* to your `$ZDOTDIR` a +nd merge any changes an update may bring, if any (they are usually +confined to `.zpreztorc`) + -This file configures Prezto. -### zlogin +Troubleshooting +--------------- + +1. if prezto and some of your settings are loaded, but others are not; +make sure you are running an *interactive login shell* (you should have +a tty allocated, visible on the `w` list) and the `$TTY` variable should +be set, if that is not the case, check the above discussion, you can +'replace' your shell _in situ_ by issuing the command `exec zsh -l` -This file is sourced by login shells after zshrc, and thus, it should contain -commands that need to execute at login. It is usually used for messages such as -[fortune][2], [msgs][3], or for the creation of files. -This is not the file to define aliases, functions, shell options, and key -bindings. It should not change the shell environment. +2. if you notice that none of your settings are loaded, check that +`/etc/zshenv` does not disable them. In any case + +```bash +setopt global_rcs +setopt rcs +``` + +in `/etc/zshenv` should set them both. This issue would be extremely rare. -### zlogout -This file is sourced by login shells during logout. It should be used for -displaying messages and the deletion of files. Authors ------- From f602176ee00b59929bfcb3a73cdbd1c524294b35 Mon Sep 17 00:00:00 2001 From: Hector Date: Wed, 7 Feb 2018 05:12:39 -0800 Subject: [PATCH 2/3] Addressed Belak's feedback for more concise docs Also, modified wording to avoid disparraging efforts on configuration style before the team addresses them --- runcoms/README.md | 209 ++++++++++++---------------------------------- 1 file changed, 52 insertions(+), 157 deletions(-) diff --git a/runcoms/README.md b/runcoms/README.md index cc8a4e3518..54fa380486 100644 --- a/runcoms/README.md +++ b/runcoms/README.md @@ -5,15 +5,9 @@ Zsh has several system-wide and user-local configuration files. Prezto has one user-local configuration file. -System-wide configuration files are installation-dependent but are installed -in */etc* by default. +System-wide configuration files are installation-dependent but are installed in */etc* by default. -User-local configuration files have the same name as their global counterparts -but are prefixed with a dot (hidden). Zsh looks for these files in the path -stored in the `$ZDOTDIR` environment variable. However, if said variable is -not defined, Zsh will use the user's home directory. This is found on the -config scripts as `${ZDOTDIR:-$HOME}` and is a `zsh` idiomatic way of doing -something like this: +User-local configuration files have the same name as their global counterparts but are prefixed with a dot (hidden). Zsh looks for these files in the path stored in the `$ZDOTDIR` environment variable. However, if said variable is not defined, Zsh will use the user's home directory. This is found on the config scripts as `${ZDOTDIR:-$HOME}` and is a `zsh` idiomatic way of doing something like this: ```bash @@ -26,171 +20,68 @@ source $DOTFILES_PATH/.zshenv #pro tip! set $ZDOTDIR on /etc/zshenv to ~/.zconf to have all runcoms live there instead of cluttering ~ =) ``` -the above is the same as: `source ${ZDOTDIR:-$HOME}/.zshenv` is equivalent to: +the above is the same as: `source ${ZDOTDIR:-$HOME}/.zshenv` -Sourcing of these confguration files depends mostly on 2 things: +File Descriptions +----------------- -1. Whether you are running a *login shell* -2. Whether the `RCS` and `GLOBAL_RCS` options are set. They are usually - set by default +| system/site config
(`/etc/zsh/**`) [2] | User configuration
(`${ZDOTDIR:-$HOME}`) [3] | Purpose | stuff that usually goes there, and notes | +---------------- -File Descriptions ------------------ +| ----------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/zshenv` [1] | | system provided minimal environment | Should be minimal set ZDOTDIR, minimal environment. system paths +| | `.zshenv` | user environment overrides non-interactive, non-login shells (when invoked via _shebang_ in a script or via `zsh -c [script]` or when invoked by `make` | Personal environment overrides, such as `MANPATH`, `TERM`, `fpath` (*non interactive scripts should have their environment completly set up here* ) +| `/zprofile` | | system profile for login shells (`zsh -lsi` `zsh -`` or via _ssh forced command_ ) | Required system paths for remote interaction, site `fpath`, site `$LOCALE`, `$LANG.` +| | `.zprofile` | personal preferences for interactive login shells | your preferred `$LOCALE`, `$LANG`, `readlne` config, `cdpath`, session managers, additional `fpath` user functions, login shells (but non necessarily **ineractive** as when invoked via _ssh remote cmd_ ) will read config up to this point +| `/zshrc` | | system provided startup script, for interactive shells, (local shells that live in an `XTerm`, `URxvt`, `gnome-terminal`) or subshells (like running `xterm` from the command prompt of a _login xterm_, | site login accounting, security monitors, site command logging policy +| | `.zshrc` | user customization of their *interactive* environment for terminals | sourcing custom shell additions (`gcloud.comp.inc`), custom user frameworks (**zprezto** is invoked here), additional path required by custom software installed in `/opt/` +| `/zlogin` | | additional customization for interactive **login** shells, such as those accessed via ssh | `tmux attach` to existing session +| | `.zlogin` | user script for *login shell startup* (this shell is a session leader, and allocates a `ptty`) | aliases, keybindings, personal startup programs, time tracking apps, session managers, quote of the day, fortunes +| ... your shell.. | ..session... | ..happens... | ..here ... | +| | `.zlogout` | personal cleanup tasks | unmounting your *fuse* personal fylesystems, async encryption of sensitive directoriesm backup kickoff, setting personal `crontabs` or `at` tasks, logging checout to your time tracking software, fortune to say goodbye. +| `/zlogout` [1] | | site cleanup tasks | site command logging policy stop, login accounting records, security context spindown, etc, -| always runs | when `GLOBAL_RCS` is set | when `RCS` is set | Purpose | stuff that usually goes there, and notes | -|------------------|-----------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `/etc/zshenv` | | | system provided minimal environment | Always runs! should be minimal set ZDOTDIR, minimal environment. system paths -| | | `${ZDOTDIR:-$HOME}/.zshenv` | user environment overrides non-interactive, non-login shells (when invoked via shebang in a script or via `zsh -c [script]` or when invoked by `make` | personal environment overrides, such as `MANPATH`, `TERM`, `fpath` *non interactive scripts should have their environment completly set up here* ) -| | `/etc/zshprofile` | | system profile for login shells (`zsh -ls zsh - or via _ssh forced command_`) | minimal system paths for remote interaction, site `fpath`, site `$LOCALE`, lang. -| | | `${ZDOTDIR:-$HOME}/.zshprofile` | personal preferences for interactive login shells | your preferred `$LOCALE`, `$LANG`, `readlne` config, `cdpath`, session managers, additional `fpath` ) login shells (but non necessarily **ineractive** as when invoked via _ssh remote cmd_ ) will read config up to this point -| | `/etc/zshrc` | | system provided startup script, for interactive shells, (local shells that live in an `XTerm`, `URxvt`, `gnome-terminal`) or subshells (like running `xterm` from the command prompt of a _login xterm_, | site login accounting, security monitors, site command logging policy -| | | `${ZDOTDIR:-$HOME}/.zshrc` | user customization of their *interactive* environment for terminals | sourcing custom completions (`gcloud.comp.inc`), custom user frameworks (zprezto is invoked here), additional path required by custom software installed in `/opt/*` -| | `/etc/zshlogin` | | additional customization for interactive **login** shells, such as those accessed via ssh | tmux attach to existing session -| | | `${ZDOTDIR:-$HOME}/.zshlogin` | user script for *login shell startup* (this shell is a session leader, and allocates a `ptty` | aliases, keybindings, personal startup programs, time tracking apps, session managers, quote of the day, fortunes -| .. | ... your shell session happens here ... | -| | | `${ZDOTDIR:-$HOME}/.zshlogout` | personal cleanup tasks | setting personal `crontabs` or `at` tasks, logging checout to your time tracking software, fortune to say goodbye. -| `/etc/zshlogout` | | | site cleanup tasks | site command logging policy stop, login accounting records, security context spindown, etcThe configuration files are read in the following order: - -Discussion ----------- - -There are several places to add personal configuration and preferences in -the files already provided for startup, it’s just a matter of placing them -in the appropriate place. Most of them should probably go in -`${ZDOTDIR:-$HOME}/.zshrc` **before** invoking zprezto init, to choose -the modules that should get loaded, and using the appropriate `zstyle` -calls form preferences (`zstyle` is a kind of _registry_ for shell configuration -native to `zsh`) - - -Any tweaks to prezto’s behavior should go **after** invoking zprezto init -in `zshrc` or, in `${ZDOTDIR:-$HOME}/.zlogin` . Note however that the -`zlogin` (sysem or user) files will be sourced **only for login shells**. - -That means, when logging in to a remote system via ssh for example or -when calling say, `XTerm` or your favorite emulator by specifying you -want a **login** shell (by calling `zsh -ls` instead of plain `zsh`). -Otherwise, the `zlogin` files are ignored. - -Also, note that another difference between interactive login shells and -plain interactive shells, is that, besides sourcing `zlogin` files, -interactive login shells also allocate a pseudo-tty (you can see them when -invoking `w`. Login shells have a pty assigned, while interactive non-login -shells don't.) - -Why is this designed this way? because login shells are assumed to be -the main point of interaction with a user while non login shells would -be spawned as _sub-shells_ of a *login shell* , when executing scripts -that call `zsh` as a command interpreter, for example, when the *shebang* is -`#!/usr/bin/env zsh` or equivalent. - -When launching a new terminal within an *X11* session, it is safe to -assume that you are *already logged in* so any terminal emulator will -launch an *interactive-non-login* shell. Which is, _per specification_ -the correct behavior, but not the behavior most users *expect*. - - -There is a reason for this _specified_ behaviour: `zlogin` files should -be used for *interaction oriented settings* such as custom completion, -keybindings, `tmux` session setup, and most `alias`es. - -The advantage of grouping all interaction oriented settings in -`.zlogin` is that non-interactive shells (executing scripts via -`zsh -c [script]`, the *shebang*, subshells or `make` invoked shells, -for example) will not be burdened by additional config settings making -them faster and more responsive, as _keybindings_ and _aliases_ are not -even loaded at startup, after all, an _executable non-interactive script_, -should never call on keybindings or aliases (assuming they were properly -written to be portable) - - -Finally, it is a common source of frustration amongst graphical environment -users, to spend some time adding their customizations to `.zlogin` only -to see them ignored when launching a new `XTerm` or `tmux` pane. - -This can be solved by calling (or aliasing) your terminal emulator with -the required option to invoke a *login* shell, for `XTerm`, for example -you would call `xterm -e zsh -ls` on tmux you may add one of the following -lines to your `.tmux.conf`: - -```config -#tmux.conf: +[1]: These files are always triggered, regardless of settings +[2]: These are provided by your distribution and/or modified by your site admin. they will run only if `GLOBAL_RCS` is set (std) +[3]: Here is where you add your preferences for different kinds of shells, will run only if `RCS` is set (std) - set -g default-command 'exec /usr/bin/zsh -ls' #this will make zsh a login shell AND a session leader - set -g default-shell '/usr/bin/zsh -ls' -``` +## Make Prezto your own: Configuration and personal preferences -Here is an examplefor *i3wm* on ubuntu -```bash +That is quite a few files to configure a shell. Why so many? Mostly to accomodate different roles for shell software. Shell scripts probably don't need aliases or keybindings, but a human user will certainly appreciate it, Logging in to a XTerminal or remotely logging in via ssh are also different, but possible scenarios that require different configurations so, depending on the way you are connected or using yor computer, you'd need different sets of configuration, Since each kind of session will only read up to a certain point in the `runcoms` chain, it is important to place the correct configuration directves on the appropriate files, this way we can have speedy shells that don't waste a lot of energy, or can have all kinds of user optimization such as aliases and keymaps -#i3wm.conf: - ... - set $XTERM_CMD='xterm -e zsh -ls` - bind $mod+x $XTERM_CMD - ... -``` -if you want to replace your non-login shell on your emulator with a brand-new -shiny *login* shell you can issue `exec zsh -ls` at your command prompt. -Doing this, however **will not write that terminal’s history to file** unless -`INC_APPEND_HISTORY` was set when you strted the shell - -`INC_APPEND_HISTORY` makes `zsh` append history entries as soon as the -command is finished. *zprezto* helpfuly sets `INC_APPEND_HISTORY`, -`INC_APPEND_HISTORY_TIME`, and `SHARE_HISTORY` which makes your history -available immediately from different terminals on command completion, -and records execution time on the history file. Pretty neat, huh?) - -You could tack-on all interactive customizations on `zshrc` but you will -end up with bloated shells on non-interactive environments. Perhaps desktop -workstation users will not notice any difference, but in resource-constrained -environments it may be significant in terms of execution time and energy -consumption (v.gr when running a Raspberry PI on batteries or on a cell -phone environment such as `termux`) - -You may be thinking... why is `zpreztorc` not invoked on `.zlogin` instead -of `.zshrc`? I believe it was a wise design decision, in order to -eliminate complexity by having the whole of *prezto* configured and -launched from a single point, as some of the modules need to be sourced -early in the startup process, `editor` and `gnu-utls` come to mind. -If invoked later on the startup, such as would be the case in `.zlogin` -would makee it easier to conflict with stuff users may add on `zshrc`. -Also, it avoids **not being loaded** and causing user frustration if -the user launches *non-login shells* from graphical environments, as -discussed above. - -## Conclusion - -For customization of your environment, use your `.zshrc` after zprezto -has been invoked, or before to remove or activate packages via `zstyle` -calls - - or - -use `.zshlogin` to override or tweak zprezto behavior. there is also -`.zpreztorc` but you may want to leave that one alone. - -In any case, this question is often brought up by users that use the -distributed *runcoms* **as is** which is a terrible idea, since doing -`git pull` to update your distribution will clobber your customizations. - -it’s a better idea to *copy* the distributed *runcoms* to your `$ZDOTDIR` a -nd merge any changes an update may bring, if any (they are usually -confined to `.zpreztorc`) - - - -Troubleshooting ---------------- +Prezto leverages these good design decisions to provide a great, fast, featureful user experience, and to avoid consuming any more resources than necessary. So, with this in mind you have the flexibility to adapt the `zsh` features that prezto surfaces to your workload and tastes, ranging from the prompt theme, shortcut keys, favorite editor and pager, aliases and even syntax highlighting.! Prezto is designed in such a way to allow you to configure other aspects of your shell in the appropriate files wthout breaking the framework or forcing you to write your preferences in a particular plugin structure. In the end, its a matter of editing one ofthe files mentioned above. + +That being said, you can use the runcoms files as-is, replacing what used to be on your system, or merge your customizations with prezto's runcoms. When you update your distribution, be careful not to clobber your changes if you decided to use the files as-is. Another way of maintaining your configuration is to copy prezto's runcoms instead of symlinking them, and keep track of them independently of the core prezto distribution. If you're just starting with zsh, the first approach is faster and easier to get you going, while copying and merging the runcoms independently gives you maximum flexibility for advanced use cases. + +For a more detailed discussion on the zsh startup process and how prezto integrates with it, see *further reading* below. + + +## Common pitfalls: 1. if prezto and some of your settings are loaded, but others are not; make sure you are running an *interactive login shell* (you should have -a tty allocated, visible on the `w` list) and the `$TTY` variable should +a `tty` allocated, visible on the `w` list) and the `$TTY` variable should be set, if that is not the case, check the above discussion, you can 'replace' your shell _in situ_ by issuing the command `exec zsh -l` +you can configure your graphical environment or `tmux` to lauch nteractive login sessions by default: +here are some examples: + +```sh +#tmux.conf: +set -g default-command 'exec /usr/bin/zsh -ls' # this will make zsh a login shell +set -g default-shell '/usr/bin/zsh -ls' # USE ONLY ONE OF THESE TWO LINES! + # or you may end up with nested shells +``` +Here is an examplefor *i3wm* on ubuntu + +```sh +#i3wm.conf: +set $XTERM_CMD='xterm -e zsh -ls` +bind $mod+x $XTERM_CMD 2. if you notice that none of your settings are loaded, check that `/etc/zshenv` does not disable them. In any case @@ -211,7 +102,11 @@ Authors - [Sorin Ionescu](https://github.com/sorin-ionescu) +Further reading +---------------- + [1]: http://www.kornshell.com [2]: http://en.wikipedia.org/wiki/Fortune_(Unix) [3]: http://www.manpagez.com/man/1/msgs [4]: https://github.com/sorin-ionescu/prezto/issues + From 5ec8ce51751673bbb4e3f1c1d84858ea48fd21e5 Mon Sep 17 00:00:00 2001 From: Hector Lecuanda Date: Sat, 10 Feb 2018 22:17:09 -0800 Subject: [PATCH 3/3] Reformat to 80col wide text. Fixed table alignment --- runcoms/README.md | 111 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 78 insertions(+), 33 deletions(-) diff --git a/runcoms/README.md b/runcoms/README.md index 54fa380486..5ce92b6b65 100644 --- a/runcoms/README.md +++ b/runcoms/README.md @@ -3,11 +3,17 @@ Configuration Files Zsh has several system-wide and user-local configuration files. -Prezto has one user-local configuration file. +Prezto has one user-local configuration file: `.zpreztorc` -System-wide configuration files are installation-dependent but are installed in */etc* by default. +System-wide configuration files are installation-dependent but are installed +in `/etc` by default. -User-local configuration files have the same name as their global counterparts but are prefixed with a dot (hidden). Zsh looks for these files in the path stored in the `$ZDOTDIR` environment variable. However, if said variable is not defined, Zsh will use the user's home directory. This is found on the config scripts as `${ZDOTDIR:-$HOME}` and is a `zsh` idiomatic way of doing something like this: +User-local configuration files have the same name as their global counterparts +but are prefixed with a dot (hidden). Zsh looks for these files in the path +stored in the `$ZDOTDIR` environment variable. However, if said variable is +not defined, Zsh will use the user's home directory. This is found on the +config scripts as `${ZDOTDIR:-$HOME}` and is a `zsh` idiomatic way of doing +something like this: ```bash @@ -18,7 +24,8 @@ else fi source $DOTFILES_PATH/.zshenv -#pro tip! set $ZDOTDIR on /etc/zshenv to ~/.zconf to have all runcoms live there instead of cluttering ~ =) +# pro tip! set $ZDOTDIR on /etc/zshenv to ~/.zconf to have all runcoms +# in ~./.zconf instead of cluttering your $HOME! =) (mkdir ~/.zconf first!) ``` the above is the same as: `source ${ZDOTDIR:-$HOME}/.zshenv` @@ -27,36 +34,73 @@ File Descriptions ----------------- -| system/site config
(`/etc/zsh/**`) [2] | User configuration
(`${ZDOTDIR:-$HOME}`) [3] | Purpose | stuff that usually goes there, and notes | ----------------- - -| ----------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/zshenv` [1] | | system provided minimal environment | Should be minimal set ZDOTDIR, minimal environment. system paths -| | `.zshenv` | user environment overrides non-interactive, non-login shells (when invoked via _shebang_ in a script or via `zsh -c [script]` or when invoked by `make` | Personal environment overrides, such as `MANPATH`, `TERM`, `fpath` (*non interactive scripts should have their environment completly set up here* ) -| `/zprofile` | | system profile for login shells (`zsh -lsi` `zsh -`` or via _ssh forced command_ ) | Required system paths for remote interaction, site `fpath`, site `$LOCALE`, `$LANG.` -| | `.zprofile` | personal preferences for interactive login shells | your preferred `$LOCALE`, `$LANG`, `readlne` config, `cdpath`, session managers, additional `fpath` user functions, login shells (but non necessarily **ineractive** as when invoked via _ssh remote cmd_ ) will read config up to this point -| `/zshrc` | | system provided startup script, for interactive shells, (local shells that live in an `XTerm`, `URxvt`, `gnome-terminal`) or subshells (like running `xterm` from the command prompt of a _login xterm_, | site login accounting, security monitors, site command logging policy -| | `.zshrc` | user customization of their *interactive* environment for terminals | sourcing custom shell additions (`gcloud.comp.inc`), custom user frameworks (**zprezto** is invoked here), additional path required by custom software installed in `/opt/` -| `/zlogin` | | additional customization for interactive **login** shells, such as those accessed via ssh | `tmux attach` to existing session -| | `.zlogin` | user script for *login shell startup* (this shell is a session leader, and allocates a `ptty`) | aliases, keybindings, personal startup programs, time tracking apps, session managers, quote of the day, fortunes -| ... your shell.. | ..session... | ..happens... | ..here ... | -| | `.zlogout` | personal cleanup tasks | unmounting your *fuse* personal fylesystems, async encryption of sensitive directoriesm backup kickoff, setting personal `crontabs` or `at` tasks, logging checout to your time tracking software, fortune to say goodbye. -| `/zlogout` [1] | | site cleanup tasks | site command logging policy stop, login accounting records, security context spindown, etc, +| system/site config
(`/etc/zsh/**`) [2] | User configuration
(`${ZDOTDIR:-$HOME}`) [3] | Purpose | stuff that usually goes there, and notes | +|----------------------------------------------|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/zshenv` [1] | | system provided minimal environment | Should be minimal set ZDOTDIR, minimal environment. system paths | +| | `.zshenv` | user environment overrides non-interactive, non-login shells (when invoked via _shebang_ in a script or via `zsh -c [script]` or when invoked by `make` | Personal environment overrides, such as `MANPATH`, `TERM`, `fpath` (*non interactive scripts should have their environment completly set up here* ) | +| `/zprofile` | | system profile for login shells (`zsh -lsi` `zsh -`` or via _ssh forced command_ ) | Required system paths for remote interaction, site `fpath`, site `$LOCALE`, `$LANG.` | +| | `.zprofile` | personal preferences for interactive login shells | your preferred `$LOCALE`, `$LANG`, `readlne` config, `cdpath`, session managers, additional `fpath` user functions, login shells (but non necessarily **ineractive** as when invoked via _ssh remote cmd_ ) will read config up to this point | +| `/zshrc` | | system provided startup script, for interactive shells, (local shells that live in an `XTerm`, `URxvt`, `gnome-terminal`) or subshells (like running `xterm` from the command prompt of a _login xterm_, | site login accounting, security monitors, site command logging policy | +| | `.zshrc` | user customization of their *interactive* environment for terminals | sourcing custom shell additions (`gcloud.comp.inc`), custom user frameworks (**zprezto** is invoked here), additional path required by custom software installed in `/opt/` | +| `/zlogin` | | additional customization for interactive **login** shells, such as those accessed via ssh | `tmux attach` to existing session | +| | `.zlogin` | user script for *login shell startup* (this shell is a session leader, and allocates a `ptty`) | aliases, keybindings, personal startup programs, time tracking apps, session managers, quote of the day, fortunes | +| ... your shell.. | ..session... | ..happens... | ..here ... | +| | `.zlogout` | personal cleanup tasks | unmounting your *fuse* personal fylesystems, async encryption of sensitive directoriesm backup kickoff, setting personal `crontabs` or `at` tasks, logging checout to your time tracking software, fortune to say goodbye. | +| `/zlogout` [1] | | site cleanup tasks | site command logging policy stop, login accounting records, security context spindown, etc, | [1]: These files are always triggered, regardless of settings -[2]: These are provided by your distribution and/or modified by your site admin. they will run only if `GLOBAL_RCS` is set (std) -[3]: Here is where you add your preferences for different kinds of shells, will run only if `RCS` is set (std) +[2]: These are provided by your distribution and/or modified by your site +admin. they will run only if `GLOBAL_RCS` is set (std) +[3]: Here is where you add your preferences for different kinds of shells, +will run only if `RCS` is set (std) ## Make Prezto your own: Configuration and personal preferences -That is quite a few files to configure a shell. Why so many? Mostly to accomodate different roles for shell software. Shell scripts probably don't need aliases or keybindings, but a human user will certainly appreciate it, Logging in to a XTerminal or remotely logging in via ssh are also different, but possible scenarios that require different configurations so, depending on the way you are connected or using yor computer, you'd need different sets of configuration, Since each kind of session will only read up to a certain point in the `runcoms` chain, it is important to place the correct configuration directves on the appropriate files, this way we can have speedy shells that don't waste a lot of energy, or can have all kinds of user optimization such as aliases and keymaps - -Prezto leverages these good design decisions to provide a great, fast, featureful user experience, and to avoid consuming any more resources than necessary. So, with this in mind you have the flexibility to adapt the `zsh` features that prezto surfaces to your workload and tastes, ranging from the prompt theme, shortcut keys, favorite editor and pager, aliases and even syntax highlighting.! Prezto is designed in such a way to allow you to configure other aspects of your shell in the appropriate files wthout breaking the framework or forcing you to write your preferences in a particular plugin structure. In the end, its a matter of editing one ofthe files mentioned above. - -That being said, you can use the runcoms files as-is, replacing what used to be on your system, or merge your customizations with prezto's runcoms. When you update your distribution, be careful not to clobber your changes if you decided to use the files as-is. Another way of maintaining your configuration is to copy prezto's runcoms instead of symlinking them, and keep track of them independently of the core prezto distribution. If you're just starting with zsh, the first approach is faster and easier to get you going, while copying and merging the runcoms independently gives you maximum flexibility for advanced use cases. - -For a more detailed discussion on the zsh startup process and how prezto integrates with it, see *further reading* below. +That is quite a few files to configure a shell. Why so many? Mostly to +accomodate different roles for shell software. Automated Shell scripts +probably don't need aliases or keybindings, but a human user will certainly +appreciate it, as shortcuts can make you more productive. When Logging via an +XTerminal or remotely logging in using ssh may look like similar tasks, but +resource and configuration-wise they are worlds appart. So, so far we already +have 4 possible scenarios that require very different configuration on your +shell. doing it manually is cumbersome, time consuming and error prone, Enter +_Prezto_: Instantly awesome `zsh` ready to use no matter how you connect or +use your computer. It even offers _feature parity_ between different OSs, as +long as they run `zsh` + +So, depending on the way you are connected or using yor computer, you'd need +different sets of configuration, Since each kind of session will only read up +to a certain point in the `runcoms` chain, it is important to place the +correct configuration directves on the appropriate files, this way we can have +speedy shells that don't waste a lot of energy, or can have all kinds of user +optimization such as aliases and keymaps + +Prezto leverages these good design decisions to provide a great, fast, +featureful user experience, and to avoid consuming any more resources than +necessary. So, with this in mind you have the flexibility to adapt the `zsh` +features that prezto surfaces to your workload and tastes, ranging from the +prompt theme, shortcut keys, favorite editor and pager, aliases and even +syntax highlighting.! **Prezto is designed in such a way to allow you to +configure other aspects of your shell in the appropriate files wthout breaking +the framework** or forcing you to write your preferences in a particular +plugin structure. In the end, its a matter of editing one ofthe files +mentioned above. + +That being said, you can use the runcoms files _as-is_, replacing your old +files with prezto's baseline, or you can merge your customizations with +prezto's runcoms.! + +When you update your distribution with `git`, be careful not to clobber your +changes if you decided to use the files as-is. Another way of maintaining your +configuration is to copy prezto's runcoms instead of symlinking them, and keep +track of them independently of the core prezto distribution. If you're just +starting with `zsh`, the first approach is faster and easier to get you going, +while copying and merging the runcoms independently gives you *maximum +flexibility for advanced use* cases. + +For a more detailed discussion on the zsh startup process and how prezto +integrates with it, see *further reading* below. ## Common pitfalls: @@ -67,14 +111,15 @@ a `tty` allocated, visible on the `w` list) and the `$TTY` variable should be set, if that is not the case, check the above discussion, you can 'replace' your shell _in situ_ by issuing the command `exec zsh -l` -you can configure your graphical environment or `tmux` to lauch nteractive login sessions by default: -here are some examples: +you can configure your graphical environment or `tmux` to lauch nteractive +login sessions by default: here are some examples: ```sh #tmux.conf: -set -g default-command 'exec /usr/bin/zsh -ls' # this will make zsh a login shell -set -g default-shell '/usr/bin/zsh -ls' # USE ONLY ONE OF THESE TWO LINES! - # or you may end up with nested shells +set -g default-command 'exec /usr/bin/zsh -ls' # make zsh a login shell +set -g default-shell '/usr/bin/zsh -ls' # USE ONLY ONE OF THESE TWO + # LINES! or you may end up + # with nested shells ``` Here is an examplefor *i3wm* on ubuntu