Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposed enhancements to runcoms repo documentation #1540

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Proposed enhancements to runcoms repo documentation #1540

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5d2b2a7
Proposed enhancements to runcoms repo documentation
hlecuanda Feb 1, 2018
f602176
Addressed Belak's feedback for more concise docs
hlecuanda Feb 7, 2018
5ec8ce5
Reformat to 80col wide text. Fixed table alignment
hlecuanda Feb 11, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 126 additions & 48 deletions runcoms/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,68 +3,142 @@ 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.
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

### zshenv

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

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.
```bash
if [[ -n $ZDOTDIR ]]; then
DOTFILES_PATH=$ZDOTDIR
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nit: can you remove a space from the beginning here to be consistent with the else branch?

else
DOTFILES_PATH=$HOME
fi
source $DOTFILES_PATH/.zshenv

zprofile and zlogin are not meant to be used concurrently but can be done so.
# 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`

### zshrc

This file is sourced by interactive shells. It should define aliases,
functions, shell options, and key bindings.

### zpreztorc

This file configures Prezto.

### zlogin
File Descriptions
-----------------

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.
| system/site config </br> (`/etc/zsh/**`) [2] | User configuration </br>(`${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* ) |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/completly/completely

| `/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. |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like a few typos here: "fylesystems", "directoriesm", "checout"

| `/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)

## 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. Automated Shell scripts
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/accomodate/accommodate

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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/appart/apart

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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/yor/your

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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either . or ! is needed; both is extra.

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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/its/it's, s/ofthe/of the

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.!
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment about .!


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:

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`

you can configure your graphical environment or `tmux` to lauch nteractive
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/lauch/launch, s/nteractive/interactive

login sessions by default: here are some examples:

```sh
#tmux.conf:
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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/examplefor/example for


```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

```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
-------
Expand All @@ -73,7 +147,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