romkatv/zsh4humans

A turnkey configuration for Zsh

Zsh for Humans

• THE PROJECT HAS VERY LIMITED SUPPORT
• NO NEW FEATURES ARE IN THE WORKS
• MOST BUGS WILL GO UNFIXED

A turnkey configuration for Zsh that aims to work really well out of the box. It combines the best Zsh plugins into a coherent whole that feels like a finished product rather than a DIY starter kit.

If you want a great shell that just works, this project is for you.

Table of contents

• 1. Features
• 2. Installation
• 3. Try it in Docker
• 4. Caveats
• 5. Usage
  • 5.1. Accepting autosuggestions
  • 5.2. Completing commands
  • 5.3. Searching command history
  • 5.4. Interactive search with fzf
  • 5.5. SSH
• 6. Customization
  • 6.1. Customizing prompt
  • 6.2. Customizing appearance
  • 6.3. Additional Zsh startup files
• 7. Updating
• 8. Uninstalling
• 9. Advanced configuration tips

Features

• Powerful POSIX-based shell preconfigured to work great out of the box.
• Easy-to-use installation wizard. Does not require git, zsh or sudo.
• Syntax highlighting for the command line.
• Autosuggestions for commands based on command history.
• Command prompt configurable through a builtin configuration wizard.
• Command completions and history searchable with fzf.
• Super fast. No lag when you open a new tab in the terminal or run a command.
• The complete shell environment can be automatically teleported to the remote host when connecting over ssh. This does not require git, zsh or sudo on the remote host.
• Command history can be shared across different hosts. For example, history from ssh foo can be made available within ssh bar and/or on the local machine.

Installation

Run this command in bash, zsh, or sh:

if command -v curl >/dev/null 2>&1; then
  sh -c "$(curl -fsSL https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)"
else
  sh -c "$(wget -O- https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)"
fi

The installer backs up the existing Zsh startup files, creates new ones, installs everything necessary for Zsh for Humans, starts a new shell, and configures it as login shell. It asks for confirmation on every step so that you are always in control. Installation requires curl or wget. It does not require git, zsh, sudo or anything else.

Recording of the installation process

Try it in Docker

Try Zsh for Humans in a Docker container. You can safely install additional software and make any changes to the file system. Once you exit Zsh, the image is deleted.

• Alpine Linux: starts quickly; install additional software with apk add <package>

  docker run -e TERM -e COLORTERM -e LC_ALL=C.UTF-8 -w /root -it --rm alpine sh -uec '
    apk add zsh curl tmux
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)"'

• Ubuntu: install additional software with apt install <package>:

  docker run -e TERM -e COLORTERM -w /root -it --rm ubuntu sh -uec '
    apt-get update
    apt-get install -y zsh curl tmux
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)"'

Caveats

Zsh for Humans is not a good choice for users who prefer vi bindings in their shell.

Zsh for Humans has very little documentation. There is no list of configuration options it recognizes and no description of what those options do.

Usage

If you've used Zsh, Bash or Fish before, Zsh for Humans should feel familiar. For the most part everything works as you would expect.

Accepting autosuggestions

All key bindings that move the cursor can accept command autosuggestions. For example, moving the cursor one word to the right will accept that word from the autosuggestion. The whole autosuggestion can be accepted without moving the cursor with Alt+M/Option+M.

Autosuggestions in Zsh for Humans are provided by zsh-autosuggestions. See its homepage for more information.

Completing commands

When completing with Tab, suggestions come from completion functions. For most commands completion functions are provided by Zsh proper. Additional completion functions are contributed by zsh-completions. See its homepage for the list of commands it supports.

Ambiguous completions automatically start fzf. Accept the desired completion with Enter. You can also select more than one completion with Ctrl+Space or all of them with Ctrl+A.

Searching command history

Up and Down keys fetch commands from history that contain what you've already typed on the command line. For example, if you press Up after typing grep, you'll see the last executed command that contains grep.

Ctrl+R starts fzf to search over history.

Interactive search with fzf

Several UI elements in Zsh for Humans use fzf to quickly select an item from a potentially large list of candidates. You can type multiple search terms delimited by spaces. For example:

^music .mp3$ sbtrkt !fire

Token	Match type	Description
wild	substring	Items with the substring wild
^music	prefix	Items that start with music
.mp3$	suffix	Items that end with .mp3
!wild	inverse substring	Items without the substring wild
!^music	inverse prefix	Items that do not start with music
!.mp3$	inverse suffix	Items that do not end with .mp3

A single bar (|) acts as an OR operator. For example, the following query matches entries that start with core and end with either go, rb, or py.

^core go$ | rb$ | py$

See fzf homepage for more information.

SSH

When you connect to a remote host over SSH, your local Zsh for Humans environment can be teleported over to it. The first login to a remote host may take some time. After that it's as fast as normal ssh.

Search for "ssh" in your ~/.zshrc for information on how to enable and configure SSH teleportation.

Customization

You can (and should) edit ~/.zshrc to customize your shell. It's a very good idea to read through the whole file to see which customization options are in there and to flip some of them to your liking.

When adding your customizations, put them next to the existing lines that do similar things. The default ~/.zshrc contains the following types of customizations that should serve as examples:

• Export environment variables.
• Extend PATH.
• Define aliases.
• Add flags to existing aliases.
• Define functions.
• Source additional local files.
• Load Oh My Zsh plugins.
• Clone and load external Zsh plugins.
• Set shell options.
• Autoload functions.
• Change key bindings.

Customizing prompt

Prompt in Zsh for Humans is provided by Powerlevel10k. Run p10k configure to access its interactive configuration wizard. Further customization can be done by editing ~/.p10k*.zsh files. There can be more than one configuration file to account for terminals with limited capabilities. Most users will ever only see ~/.p10k.zsh. When in doubt, consult $POWERLEVEL9K_CONFIG_FILE. This parameter is set by Zsh for Humans and it always points to the Powerlevel10k config file currently in use.

See Powerlevel10k homepage for more information.

Customizing appearance

Different parts of Zsh for Humans UI are rendered by different projects.

Everything within the highlighted areas on the screenshot is prompt. It is produced by Powerlevel10k. See Customizing prompt.

The listing of files produced by ls command is colored by ls itself. Different commands have different ways of customizing their output, and even different version of ls have different flags and environment variables related to colors. Zsh for Humans enables colored output for common commands such as ls and grep. For further customization consult documentation of the respective command.

echo hello is the current command being typed. Syntax highlighting for it is provided by zsh-syntax-highlighting. See its homepage for documentation on how to customize it.

After echo hello you can see world in grey. This is not a part of the command, so pressing Enter will print only hello but not world. The latter is an autosuggestion provided by zsh-autosuggestions that you can accept in part or in full. It comes from command history and it's a great productivity booster. See zsh-autosuggestions homepage for more information.

Last but not least, your terminal has a say about the appearance of everything that runs within it. The base colors, numbered from 0 to 15, can look differently in different terminals and even in the same terminal with different settings. Most modern terminals support themes, color palettes or color schemes that allow you to quickly change base colors. If colors in your terminal look unpleasant, try a different theme. Note that colors with codes above 15, as well as colors specified as RGB triplets, don't get affected by terminal themes. They look the same everywhere.

Additional Zsh startup files

When you start Zsh, it automatically sources ~/.zshenv and ~/.zshrc. The former bootstraps Zsh for Humans, the latter is your personal config. It is strongly recommended to keep all shell customization and configuration (including exported environment variables such as PATH) in ~/.zshrc or in files sourced from ~/.zshrc. If you are certain that you must export some environment variables in ~/.zshenv, do it where indicated by comments.

Zsh supports several additional startup files with complex rules governing when each file is sourced. The additional startup files are ~/.zprofile, ~/.zlogin and ~/.zlogout. Do not create these files unless you are absolutely certain you need them.

Updating

Run z4h update to update Zsh for Humans. There is no update mechanism for ~/.zshrc itself.

Uninstalling

1. Delete or replace ~/.zshenv and ~/.zshrc. If you had these files prior to the installation of Zsh for Humans and have replied in the affirmative when asked by the installer whether you want them backed up, you can find them in ~/zsh-backup.
2. Restart your terminal. Restarting zsh is not enough.
3. Delete Zsh for Humans cache:

   rm -rf -- "${XDG_CACHE_HOME:-$HOME/.cache}/zsh4humans/v5"

Advanced configuration tips

See this document.

zsh4humans's Issues

rustup and cargo completions

The rustup and cargo completions are generated by a script (in the same manner of kubectl and helm).

❯ rustup completions --help
rustup-completions 
Generate tab-completion scripts for your shell

USAGE:
    rustup completions [ARGS]

FLAGS:
    -h, --help    Prints help information

ARGS:
    <shell>       [possible values: zsh, bash, fish, powershell, elvish]
    <command>     [possible values: rustup, cargo]

If the sourcing is done "naively" by the user, he can choose between 1/ executing the rustup completions zsh rustup inside .zshrc and delay zsh start or 2/ cache the command result in a file that could not be up to date when updating rust.

NB: There could be other tools working the same way, I'm wondering if it would be interesting that z4h offer to the user a "generic" way of caching/auto-updating for these use cases, instead of having you to update z4h each time there is a new tool.

edit: maybe this could also increase the modularity of your code (for z4h v4)

Feature Request : Warn on updates instead of prompting

Hi, small feature request:

I was trying to put a fire out, and it was distracting to get a blocking prompt when I start up my shell over and over. It seems like maybe a slightly nicer user experience, if, instead there was a warning "zsh4humans: warn: updates are available, type ... to update".

It also feels like the kind of thing where I want to sit down with the intent to update z4h, and be prepared to deal with consequences, versus something I might just do on a whim when I open a terminal to do something else?

Pretty minor, but it kept occurring to me until I finally let it upgrade.

ls alias doesn't work on mac

thanks for writing this (and for powerlevel10k!)

one small point - ls --color=auto doesn't work on Mac out of the box because it's a different ls than the Linux one - have to do ls -G instead (otherwise, a default install of z4h complains every time ls is run).

DUPE - How to sync choices to another machine?

I made about 10 arbitrary choices about how I wanted the terminal to look.

How can I sync those easily to a different machine?

prompt visual glitch inside Dolphin terminal view when clicking folders

note: maybe I should have opened this in https://github.com/romkatv/powerlevel10k

KDE Dophin file manager can open a terminal view which stays synchronized with the folder tree view: whenever you cd inside the terminal, the folder tree view switches to this directory, whenever you click a folder, the terminal cd to this directory.

It works great with z4h/p10k but when I click a folder in the tree view, I get a visual glitch:

It looks like Dolphin is pasting a '\n cd myfolder` or something close, as a result I get extra "dirty" lines inside the terminal view. In the previous example, I successively clicked on the '' folder, then on the '\etc' one.

I'm using p10k with pure theme and a transient prompt.

Note that it's really a very minor thing, I really rarely use that Dolphin terminal view. Feel free to close it.

Cannot retrieve function definitions, v3

Hello - I took @romkatv's advice and moved my functions to external files.

fpath+=(~/bin/zsh/functions)
autoload -Uz -- ~/bin/zsh/functions/[^_]*(.)
compdef _directories md

Actually they are in my cloned dotfiles at ~/.dotfiles/zsh/bin/zsh/functions and linked into
~ with gnu stow.

I wanted to prove the md function was loaded by viewing its definition. I did which md which normally would output the function definition to std-out, but it doesn't. Rather it just outputs the below:

❯ which md
md () {
	# undefined
	builtin autoload -XUz /path/to/bin/zsh/functions
}

Also tried whence -f md, type -f md, declare -f md, functions md, typeset -f md, but all gave the same result.

I could write a function to show function contents by just doing i.e. a cat on the external file, but I am wondering if viewing the contents of functions declared from external files, can be performed in the usual way?

Deploying zsh remotely without internet with z4h ssh

Hi Roman,

I continue to play with v3, its awesome.
Do you plan to handle the case where a remote server dont got internet and so in this case, two cases:

• i would like to pass a proxy_http to z4h ssh
• i would like to use my laptop as a gateway, laptop will download the zsh binary(and other stuff is need) needed, then push them to the remote server

Tell me you need more information ;)

Thanks you!

Keybindings with putty on windows

Hi, just discovered this little gem.

I have set cd-key to ctrl in .zshrc

I am using this on a box via putty on Windows 10 and there seems to be an issue with keybindings for me. For example the ctrl+up combination (and probably others) do not work.

Via cat, i get the following bindings for ctrl+up: ^[OA

So what actually happens is z4h-up-local-history

from z4h.zsh:

  bindkey -s '^[OA' '^[[A'  # up
  bindkey '^[[A'    z4h-up-local-history           # up         prev command in local history

Is there an easy way to make this work?

Include bash completions support

I've been trying z4h and I quite loved it, maybe given the purpose of it it may also include support for bash completions as fallback, I've written a small plugin that handles it, which you may be interested in including by default, as it will only provide quite a lot more completions without much initialization time (just sourcing it takes something like ~10ms).

Zinit integration and plugin customization

Hello,
First thank you for a wonderful ZSH experience for beginners. I wish I'd found it earlier. Just a couple questions, and sorry in advance if this is really basic:

1. Where do I edit which plugins are being loaded? I want to use marlonrichert /
   zsh-autocomplete and I believe it interferes with the built-in autocomplete.
2. I've sourced zinit in the .zshrc file, but I'm not sure if this is proper and will cause issue. If it does, it is possible to isolate your SSH functionality (take your zsh settings with you) and use it in a new setup? TIA!!!

Basic autocompletion doesn't work?

systemctl --user restart gpg-agent<tab> doesn't work.

cd dir1<tab><down><tab> doesn't... actually let you tab complete more than one dir at a tab.

It was very jarring to try and switch to zsh with this with my most used tab completions not working at all. Am I doing something wrong?

Truncate dir in term title

Some of the directories I work in are quite long (up to 91 chars), and it's visually annoying to have them cut off (plus, I can't tell exactly where each tab is). I haven't totally migrated to zsh4humans yet, but I'm using the snippet with the term title setting and the expansions are beyond me. How would I truncate the dir?

[Discussion/Enhancements/Bugs?] - Feedback on zsh4humans

Hi I was looking into your project for last couple of days because I'm trying to create something similar for my own use and decided to give you some feedback.

Enhancements

FZF

Something that might be useful for default is override of FZF_DEFAULT_COMMAND when user have installed fd, ack, ripgrep or any other tool that can handle well large codebases. Tools could be also used for generating completion by defining _fzf_compgen_path and _fzf_compgen_dir functions.

fzf-tab

For well used commands like cd, ps it might be worth considering to add completion with preview windows.

# give a preview of commandline arguments when completing `kill`
zstyle ':completion:*:*:*:*:processes' command "ps -u $USER -o pid,user,comm,cmd -w -w"
zstyle ':fzf-tab:complete:kill:argument-rest' extra-opts --preview=$extract'ps --pid=$in[(w)1] -o cmd --no-headers -w -w' --preview-window=down:3:wrap

Colorls

Nice tool that provides synergy with Powerlevel10k and Nerd Fonts is colorls. It might be good addition to your shell.

Possible bugs

Kubernetes ?

I wan't able to successfully test Kubernetes integration with your shell in Docker image (see error below), however on my personal setup I wasn't able to figure out how to make this work. Completion with fzf-tab works only for kubectl, when typing kubectl get <tab> completion is not offered as it should and you get directories instead of Kubernetes API primitives. Can you verify if this is also issue in your project?

Error in Docker

$ source <(kubectl completion zsh)                                                                                                       
$ sed: bad regex '[[:<:]]_filedir[[:>:]]': Unknown character class name

Discussion

Plugin managers

Have you considered to give users option to use other Zsh plugin managers such as zplug? I was wondering if the decision behind your own custom lightweight manager is only to have zero dependencies / fast shell by zcompiling everything. Would that be possible with other plugin system?

Please do not rebind `alt-f` for fzf completion

As an avid command line junkie, I rely on alt-b and alt-f to quickly navigate back and forth on the command line. Can the same be done with ctrl-left and ctrl-right? Sure, but your hands have to move off the keyboard. Keyboard enthusiasts will be unhappy you have changed an immutable law of physics 😄

In meantime, I'll manually rebind it, but I think this binding violates the principle of least surprise when one is accustomed to emacs keybindings.

Thanks!
Pete

GPG git commit signing stopped working

for the record, i love this repo much faster than zprezto and much nicer to work in general.
BUT!

gpg completely fails on git commit signing. how to resolve this issue?

gitconfig didn't change nor I deleted any packages. it worked before migration

[Discussion/Help/Bugs?] Some Impressions from the first days of using z4h

Preamble

I switched from omz, so some things that I expect might be opinionated towards the way omz did it. This will probably lean between disagreement, searching for help to configure z4h correctly for myself and some bug reports.

Unexpected defaults

• ctrl-r: not cycling through history (and ctrl-s to reverse it)
  I expected export FZF_CTRL_R_COMMAND='--bind ctrl-r:up --bind ctrl-s:down' to introduce this behavior but it didn't.
• in completion menu: tab not for cycling through the results threw me off hard and combined with the prompt eating (see below) it was quite painful to use.

Possible Bugs in z4h, zsh or a used plugin

• z4h-up-global-history: If I understand this correctly this should work:

❯ echo foo
foo
❯ zsh
❯ echo bar
bar
❯ exit
❯ <alt-x>
execute: z4h-up-global-history<enter>

I would expect this to yield exit but it goes to zsh
I also wondered why INC_APPEND_HISTORY wasn't set which sounds like a good idea?

• tab completion was really buggy for me until I switched off the accept on tab. It regularly ate the prompt line leaving me guessing what the command even was. I thought switching it off solved that since I wasn't planing on sticking with that behavior anyway. But I still have eaten prompt syndome:

docker run -e TERM -e COLORTERM -w /root -it --rm alpine sh -uec 'sh -c "$(wget -O- https://raw.githubusercontent.com/romkatv/zsh4humans/v2/install)"'
[setup stuff, mostly 1, twi line prompt, no transient prompt]
~                                                                                      root@1313e4dc2cad
❯ sed -i "/fzf-tab/d" ~/.zshrc && exec zsh
~                                                                                      root@1313e4dc2cad
❯ ls /<tab>etc/

(Feature) Wishes

• The completion menu I used to use also had a horizontal axis, fzf only seems to have vertical entries. Any way to make more use of the available space to the right?
• I use this to make the undo (ctlr-_) also bring back interrupted prompts (ctrl-c). It feels natural (to me) and might be a nice addition.
  I dirtily patched it to the zle-line-init function so I wouldn't lose other functionality.

functions[zle-line-init]="
    $functions[zle-line-init]
    after_zle-line-init

PS: Jeez, there are some useless plugins...

Transfer of other dotfiles besides those for zsh

This is such an interesting project - impressive and well done.

I wonder, would it be overly difficult to have z4h ssh transfer not only zsh configs, but also other configs such as for vim or git?

Question: why not use the zsh/terminfo module for key escape sequences?

Hey!

I'm wondering why you're directly using escape codes instead of using the zsh/terminfo module.
For example, you're using this:

bindkey '^[[H' beginning-of-line

Instead of:

bindkey "${terminfo[khome]}" beginning-of-line

Thanks!

How to complete things that are not files?

Apology offered in advance, this is probably just me being dumb or something.

Coming from prezto, I am used to completing things like git branch. For example, I type
git checkout fix- and hit tab to complete with fix-bad-formatting(or some such.) But when I try that with z4h, it gives me fzf with completing files instead of branches, which I don't want. I understand checkout could be used for both, but I most often use it for branch switching, and it doesn't seem to be working at all (e.g. If I type enough where it doesn't fuzzy match to any files but precisely matches branches, fzf offers no branches nor files). I thought this was maybe my mistake for not learning the keybinds, but Ctrl-Space offers me nothing at all. Reading the docs it seems that completion functions are indeed supported, and this led me to believe completion worked similarly (albeit fuzzy) to my previous setup, but that isn't the case.

Pretty much, if I type git checkout and then the enough of a git branch to be unique, what key should I press to get the rest of that branch in there? Is this not a feature of z4h? It was one of my most-used features from my previous setup (although I will admit that z4h's alt-arrow dir navigation and the simplicity of the system are big pros for me).

Question: does using `zcompile` actually improve performance?

I once experimented with using zcompile to source scripts (mostly plugins), but my tests didn't show any improvement (at least not significant enough to be visible in benchmarking with tens of runs).
I tried to do the same with the zsh4humans .zshrc to see if I get similar results, and indeed I don't see a real improvement. To benchmark, I used two variations:

1. Simple for loop like:

for i in $(seq 1 10); do time zsh -i -c exit; done;

2. Using hyperfine:

hyperfine --warmup 1 'zsh -i -c exit'

I compared between the current .zshrc from master, and a slight variation to source the script directly by adding the following lines:

[[ -f "$2.zwc" ]] && rm "$2.zwc"
source "$2"

To this piece of code just above the if:

zsh4humans/.zshrc

Lines 18 to 20 in ed3ac2b

	2-source)
	[[ -r $2 ]] || return
	if [[ ! $2.zwc -nt $2 && -w ${2:h} ]]; then

Cursor position when pressing up arrow

Probably this is intentional but I wanna know if it's possible to force cursor position to go to the end of the line when searching in the history.

macos brew & linux brew integration

Hi, I'm a regular fish user and a zsh noob (discovering it with Z4H).

I'm trying to enable some of the Oh-my-Zsh plugins, let's say kubectl: how am I supposed to do so ?

• plugins=(kubectl) does nothing by itself, should I source OMZ ? how ?
• as in the examples section : z4h source $Z4H/ohmyzsh/ohmyzsh/plugins/kubectl/kubectl.plugin.zsh. It works but I have to define the ZSH_CACHE variable (that seems to be used in many OMZ plugins). I added export ZSH_CACHE_DIR=$Z4H/cache. If it the right way to do so, should it be in the Z4H default .zshrc ?

The examples in "Use additional Git repositories pulled in with z4h install" show different strategies (sourcing or adding a directory in the fpath). Do I have to choose one / both depending on the OMZ plugin I'm using ? Is it safe to do both and if so, is there a shorter way to include a OMZ plugin ?

Cannot install when current directory is not $HOME

You always create impressive projects. 👍

Full log:

[root@261341dba2ed /]# cd /usr/
[root@261341dba2ed usr]# if command -v curl >/dev/null 2>&1; then
>   sh -c "$(curl -fsSL https://raw.githubusercontent.com/romkatv/zsh4humans/v4/install)"
> else
>   sh -c "$(wget -O- https://raw.githubusercontent.com/romkatv/zsh4humans/v4/install)"
> fi
Greetings, Human!

What kind of keyboard are you using?

  (1)  Mac. It has Option key(s) and does not have Backspace.
  (2)  PC.  It has Backspace key(s) and does not have Option.
  (q)  Quit and do nothing.

Choice [12q]: 1
What keybindings do you prefer?

  (1)  Standard. I delete characters with Delete key.
  (2)  Like in vi. I delete characters with X key in command mode.
  (q)  Quit and do nothing.

Choice [12q]: 1
You have the following Zsh startup files:

    ~/.zshenv
    ~/.zshrc

What should I do with them?

  (1)  Move them to ~/zsh-backup/20201023-135540. Recommended.
  (2)  Delete them.
  (q)  Quit and do nothing.

Choice [12q]: 1
Settings up Zsh For Humans...

z4h: fetching z4h.zsh from github.com/romkatv/zsh4humans
z4h: generating ~/.zshenv
z4h: generating ~/.zshrc
cp: cannot stat '.zshenv': No such file or directory

slow autocomplete for files and directories

in my repo i have scripts folder with 1 file inside. it takes seconds to autocomplete. any idea how can i make it faster? or how to diagnose what is going on

thanks

Add completions for hashicorp vault

I noticed you have a few built-in completions for apps that generate them directly (kitty, helm, cargo, rustup, etc). I'd like to propose adding completions for hashicorp vault, which I think is a very common tool these days to manage secrets.

Currently their docs says to run vault -autocomplete-install, which in turn places the following lines to the end of .zshrc:

autoload -U +X bashcompinit && bashcompinit
complete -o nospace -C /usr/bin/vault vault

Proposal: fix deleting in multiline contexts

This issue is not about a bug in z4h, but a bug (or at least surprising behavior) in zsh by default.
By default, when you edit a multiline command and you're not in the first line, it seems you can't go to a previous line by deleting characters (or any other way I'm aware of).
For example, try typing echo 1 \ and then pressing enter. ZLE will move the cursor to a new line, but then how do you go back to the first one?
I would expect that pressing backspace or Ctrl-W would do it, but that's not the case. The cursor is stuck on the second line.

In my config, I try to fix it with the following:

backward-delete-char-or-up-line() {
  emulate -L zsh
  if [[ -n "${LBUFFER}" ]]; then
    zle backward-delete-char
  elif [[ -n "${PREBUFFER}" ]]; then
    local len=$(( ${#PREBUFFER} -1 ))
    # Based on /usr/share/zsh/functions/Zle/edit-command-line
    print -Rz - "${PREBUFFER:0:${len}}"
    zle send-break
  fi
}
zle -N backward-delete-char-or-up-line
bindkey '^?' backward-delete-char-or-up-line

backward-delete-word-multiline() {
  emulate -L zsh
  if [[ -n "${LBUFFER}" ]]; then
    local len=${#LBUFFER}
    if [[ "${LBUFFER:$((len-1)):${len}}" == $'\n' ]]; then
      zle backward-delete-char
    fi
    zle backward-delete-word
  elif [[ -n "${PREBUFFER}" ]]; then
    local len=${#PREBUFFER}
    # Based on /usr/share/zsh/functions/Zle/edit-command-line
    print -Rz - "${PREBUFFER:0:${$((len-1))}}"
    # send-break is required to break from a multiline editing mode.
    zle send-break
  fi
}
zle -N backward-delete-word-multiline
bindkey '^W' backward-delete-word-multiline

Does it make sense to have this behavior by default?

I don't know if the improvement justifies the added complexity for z4h, but thought I'd share it for you to decide.

error in debian

Hi again! I got everything working beautifully on my mac, so I started moving it to my servers. Doing so, though, is giving me an error:

$ zsh
z4h:29: unknown file attribute: \n

It then spits out what looks like my bash PS1 but all with the encoded characters:

$ zsh
z4h:29: unknown file attribute: \n
\[\033[00m\][\[\033[0;32m\]\H\[\033[00m\]:\[\033[01;36m\]\w\[\033[00m\]] [\[\033[0;94m\]\D{ 17:56 }\[\033[00m\]]\[\033[0;33m\]$(__git_ps1)\n$\[\033[00m\]

I can't seem to figure out why this is happening...is it something to do with the z4h file (seems to be pointing to line 29, but that line didn't seem wrong to me)

Any ideas? Let me know if you need any other info to help debug or point me in a direction...

Some background info:

$ cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 8 (jessie)"
NAME="Debian GNU/Linux"
VERSION_ID="8"
VERSION="8 (jessie)"
ID=debian
HOME_URL="http://www.debian.org/"
SUPPORT_URL="http://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"

$ zsh --version
zsh 5.0.7 (x86_64-pc-linux-gnu)

disable tab completion?

Is there a way to disable tab completion, but rely on FZF_COMPLETION_TRIGGER=** instead? I'd rather have cd completion the old way, and only use fzf if I give **.

Automatically changing zdotdir?

Hello, first and foremost thank you for all of your incredible efforts!
I am using z4h for a couple of weeks now and it is really nice, however when I open up a terminal inside IDEA I get the following message:

I would like to understand how z4h knows that it is being called from IDEA and why it chose to change the ZDOTDIR and create a new configuration branch on my disk. Will this happen for every terminal emulator?

enable-fzf-tab:functions:39: no such function: _main_complete

I installed zsh4humans in one of my machines and it worked perfectly out of the box. However when I tried to install it in another machine, I receive the following error whenever I start zsh:

enable-fzf-tab:functions:39: no such function: _main_complete
enable-fzf-tab:functions:46: no such function: _approximate

So the completions doesn't work.

I'm using zsh 5.8 on Endeavour OS (Arch based) on both machines.

Upgrading v3 to v4

Hi - I am using v3, and run z4h update regularly. If I want to upgrade to the just-released v4, what's the best way to do it?

Thanks
Rick

History being removed/cleared

Hi, I carefully open this bug report since it might be my own fault.

I tried z4h in a docker container, played with it. I decided to copy the .zshrc to my maschine then but before I did that I moved ~/.zshrc and ~/.zlogin away. I didn't move ~/.zsh_history aka my HISTFILE.
I think I did a exec zsh then.

I would have liked to reproduce it but I am not sure how to wipe z4h.

PS: I still have terminal open so I can probably easily restore my history (maybe even with timestamps).

Beep on selecting the previous item in history

The title says it. Since that's a common action, it distracts a lot.
I've done a quick search and found this article. If I run unsetopt beep, it fixes the issue, but I don't mind beeping in other situations. unsetopt histbeep and unsetopt listbeep didn't fix the issue. I assume that there might be something else going on when selecting the previous item since the problem does not occur with the clean zsh setup.
To represent the issue, simply running the example docker would be enough.

.zprofile not being used

Since your .zshrc file will get overwritten upon update, I want to use .zprofile to store some of my personal aliases/functions that I will use. However, the file doesn't seem to be loading properly, as my aliased commands show as undefined.

My setup is:

~/.zshenv

export ZDOTDIR=$HOME/zdotdir

~/zdotdir/.zshrc

contents of your file

~/zdotdir/.zprofile

alias ll='ls -lAhG'
...

when I open a new zsh session, if i type in ll i get zsh: command not found: ll

Any idea why this setup isn't working?

How to bind the Space key using z4h bindkey?

In v2, I used to have the following to bind Ctrl Space and Alt Space (so hands don't have to leave keyboard to use the default Shift Left and Shift Right)

bindkey -M emacs '^ ' z4h-cd-back
bindkey -M emacs '^[ ' z4h-cd-forward

I upgraded to v4 today and noticed it seems the preferred way to bind keys is with z4h bindkey, but I can't seem to figure out how to bind the Space key. Any tips?

Provide z4h ssh as external plugin

The idea of z4h ssh is quite nice and I imagine it could be used also externally.

Of course the plugin should be configured with an array of files that needs to be copied over in order to be adaptable to other scenarios, but I assume it could be generalized enough to have it working even in different scenarios.

Disable fzf-tab and iTerm2 alt/option key issue

Hi,

I would like to give z4h a try, but currently what's holding me back is the fzf-tab behavior.
What is the recommended way to disable fzf-tab and restore the default tab-completion?

---

In iTerm2 the alt-arrow key-mapping doesn't work. It only outputs [C& [D.
Here is the output from cat. First is alt-right, second is alt-left.

❯ cat
^[^[[C
^[^[[D

If I install and source belak/zsh-utils/editor/editor.plugin.zsh the alt-arrows works as expected.
Thank you for another interesting looking project!

My initial feedback

This is great! Just some minor feedback/questions...

Can't wait to use z4h ssh!

Add a comment to export XDG_CACHE_HOME stating that it is optional or why it is needed. I don't currently use these variables (I'm a mac user).

I would like to see Enable vi key bindings? [y/n] on install.

Add more content to z4h help install: Where does it install to? What happens if it is already installed? Is it intended to be used inside/outside .zshrc or both? How do I use the installed repo (using z4h source)? How does it affect z4h update and z4h init?

Should there be z4h uninstall? Or a way to clean the cache?

The start of the p10k wizard feels a little abrupt/unexpected when installing z4h. Maybe the z4h installer should display "Press Enter to run the powerlevel10k configuration wizard". This would bypass the p10k functionality of running config on startup (if I understand correctly).

Can the z4h installer prompts accept input instantly without enter? (like p10k wizard)

Add an install finished message like:

Zsh for Humans successfully installed.

You may edit ~/.zshrc to make further customizations to zsh. After making changes, run exec zsh to restart zsh.

Zsh for Humans will automatically check for updates once a month. You can change this in ~/.zshrc.

Can you explain this comment in .zshrc for my curiousity? "Code prior to this line should not assume the current shell is Zsh." Why would .zshrc run in a different shell?

If z4h chsh is ran outside of .zshrc, this outcome is surprising:

Won't ask again unless $Z4H/stickycache/no-chsh is deleted.
Consider removing z4h chsh call from ~/.zshrc.

It should either skip the caching or just fail altogether. Should be documented in z4h help chsh if intended for .zshrc only.

A man z4h entry might be nice.

"(eval):zle:1: bad option: -z" when sourcing history-substring-search

Huge fan of the idea of making a sane default for zsh, btw

When opening a new terminal I get:
(eval):zle:1: bad option: -z

I believe the high-level cause of this is adding
z4h source $Z4H/ohmyzsh/ohmyzsh/plugins/history-substring-search/history-substring-search.zsh
to my .zshrc

Regular source has the same problem.

Removing the source line and starting a new shell results in a clean start. Does this happen on your machine?

How to sync choices to another machine?

I made about 10 arbitrary choices about how I wanted the terminal to look.

How can I sync those easily to a different machine?

Feedback

Hey @romkatv! I'm giving z4h/v3 a spin, and would like to share some ideas and ask some questions at the same time 🙂

1. Tab completion: traversing hidden folders

You mentioned it is possible to add an option to traverse hidden folders as well when glob_dots is set, could you please add it or give me a hint how to do this locally?

Turns out I edit files in hidden folders too often, it would be helpful if fzf included everything.

2. Tab completion: ignoring some patterns

The standard completion system respects ignored-patterns.

This was a great hint, just as one idea it allows to ignore .zwc files, for example with zstyle ':completion:*:*:kak:*:*' ignored-patterns '*.zwc' opening .p10k.zsh in editor is simpler, as kak .p<Tab> now has only one match instead of two, so fzf doesn't show up at all and I go straight to .p10k.zsh.

Currently recursive directory listing doesn't respect it but it's on my TODO list to fix this.

Would be awesome! Could you please suggest what would be a proper zstyle syntax that you want to support for ignoring folders for cd? Say for example I wanted to ignore ~/.cache/ and ~/.docker/ and everything underneath them.

3. Tab completion: do not require space to search different dirs

Suppose I just cloned zsh4humans, I press <Alt-Down> and I want to navigate to zsh4humans/fn. Typing z fn will find it, but typing zfn will not. I am used to just typing in fzf without having to think where I should put spaces... Could we at least have an option, if the current behavior is something you prefer?

By the way, while <Alt-Down> shows

zsh4humans
zsh4humans/fn

But cd <Tab> shows

zsh4humans
./zsh4humans/fn

Both work, but the latter is less aesthetic :)

4. Tab completion: fzf-tab continuous-trigger

Am I right that it will become unnecessary when everything will be traversed? If so, this could be cleaned up I presume:

zsh4humans/.zshrc

Lines 56 to 58 in 6af0bfc

	# When presented with the list of choices upon hitting Tab, accept selection and
	# trigger another completion with this key binding. Great for completing file paths.
	zstyle ':fzf-tab:*' continuous-trigger tab

5. Tab completion: multiple selection doesn't seem to work

Or I'm doing something wrong :) What I expected to work is to type $ cp .zsh<Tab> and press Ctrl+Space to select more than one entry

6. Tab completion: add grouping and multiple coloring

Have you considered adding groups and using different colors to fzf completion? I have some half-broken leftovers from prezto, but they will suffice to show a difference:

zstyle ':completion:*:*:*:*:*' menu select
zstyle ':completion:*:matches' group 'yes'
zstyle ':completion:*:options' description 'yes'
zstyle ':completion:*:options' auto-description '%d'
zstyle ':completion:*:corrections' format ' %F{green}-- %d (errors: %e) --%f'
zstyle ':completion:*:descriptions' format ' %F{yellow}-- %d --%f'
zstyle ':completion:*:messages' format ' %F{purple} -- %d --%f'
zstyle ':completion:*:warnings' format ' %F{red}-- no matches found --%f'
zstyle ':completion:*:default' list-prompt '%S%M matches%s'
zstyle ':completion:*' format ' %F{yellow}-- %d --%f'
zstyle ':completion:*' group-name ''
zstyle ':completion:*' verbose yes

Current style:

With grouping and coloring:

I don't care about group names too much, we could just hide them, but I do think coloring different types of autocomplete is useful and nice.

7. "Additional Zsh startup files" in README

I would suggest to rephrase this a little, let me give you an example when editing those files makes sense: it is a nice and easy way to start GUI. Here's how I do it:

• In .zprofile I have [[ -z $DISPLAY && "$(tty)" == "/dev/tty1" ]] && exec sway
• In .zshenv I have a list of environment variables that I want to be exported both in terminal and also for GUI
  • .zshenv is loaded before .zprofile, so whatever I export in .zshenv is visible by sway and all GUI apps
• In .zshrc I have only setup that is relevant for terminal, but not GUI

Let me know if this makes sense. Right now I simply put all my variables on top of .zshenv generated by z4h, but I'm wondering if the README needs to be adjusted to relax the bold phrase a bit, maybe just say that everything that z4h generates must be preserved without modifications?

8. Avoid exporting XDG_CACHE_HOME

I would suggest to drop this line:

zsh4humans/.zshenv

Line 11 in 6af0bfc

export XDG_CACHE_HOME="$HOME/.cache"

I believe every software knows how to fallback to $HOME/.cache in the absence of that variable, and it should be a very conscious user decision to export all those XDG_* variables, let's not do it for them.

9. Add TIMEFMT='user=%U system=%S cpu=%P total=%*E' to z4h

First saw it in your dotfiles, and instantly fell in love. I believe it's exactly one of those things that makes zsh for humans and should be done for everyone 🙂

10. Terminal title to contain timestamp

Because transient prompt (often) removes the timestamp of when a command was started, you once recommended me to add the time to the terminal title instead, to be able to see how long the command is already running. I still think it was a great idea, might be worth adding directly to z4h? Time is only needed for when a command is running (not when title shows current dir), and maybe only when transient prompt is enabled (but I'd probably just show the time always when command is running). What do you think?

11. Support moooooore LS_COLORS

Have you seen this project? https://github.com/trapd00r/LS_COLORS

I think it would be very cool to tap into their work and have an integration with it, just like you do with zsh-syntax-highlight and others. Currently I can source their file and it will affect my ls, but I don't think tab completion respects this variable, maybe because colors are set immediately after a built-in LS_COLORS is defined?

zsh4humans/fn/-z4h-init

Line 392 in 6af0bfc

zstyle ':completion:*' list-colors "${(@s.:.)LS_COLORS}"

12. Various small ideas

I have had a few small snippets taken from here and there that I use quite frequently, want to show them and see if you would want to take anything directly in z4h:

• I still use your trick to have a new line added in transient prompt, just curious if noone else requested this to become a simple config variable? :)

typeset -g POWERLEVEL9K_TRANSIENT_PROMPT=off
p10k-on-pre-prompt()  { p10k display '1'=show }
p10k-on-post-prompt() { p10k display '1'=hide }

• Bind this to Ctrl+/ and it will toggle comment for the currently typed command, just like in VS Code and other editors :)

my-pound-toggle() {
    if [[ "$BUFFER" = '#'* ]]; then
        if [[ $CURSOR != $#BUFFER ]]; then
            (( CURSOR -= 1 ))
        fi
        BUFFER="${BUFFER:1}"
    else
        BUFFER="#$BUFFER"
        (( CURSOR += 1 ))
    fi
}
zle -N my-pound-toggle

• Bind this to Ctrl+V,V to edit the current command in EDITOR, very useful for multi-line commands

autoload -Uz edit-command-line
zle -N edit-command-line

• Make Ctrl+Z toggle pressing Ctrl+Z and fg, very useful for quickly checking terminal behind an editor and going back to the editor

my-ctrl-z() {
    if [[ $#BUFFER -eq 0 ]]; then
        BUFFER="fg"
        zle accept-line -w
    else
        zle push-input -w
        zle clear-screen -w
    fi
}
zle -N my-ctrl-z

That's enough for now 😄

UPDATE: OK, one more 😁 Have you considered to add these options to the list of default options in z4h?

• HIST_IGNORE_ALL_DUPS and HIST_SAVE_NO_DUPS to keep the history file smaller?
• RC_QUOTES to allow 'Henry''s Garage' instead of 'Henry'\''s Garage'?

fzf breaks if window size changes and it is interrupted

Hi Roman, got a funny bug with fzf and p10k involved. I only tested this on z4h v3. I don't know if it triggers on v2 as well.

If you resize the terminal while in fzf and interrupt it by pressing Ctrl-C or ESC the prompt breaks.

Steps to reproduce:

1. Open a terminal
2. Type vim tab OR Ctrl-R
3. Resize the terminal emulator
4. Press ESC or Ctrl-C or tab

Terminalemulator: Tilix, Xterm
Z4H version: v3
zsh version: zsh 5.8 (x86_64-pc-linux-gnu)
OS: Manjaro up-to-date
WM: i3wm

Edit: tab triggers the bug as well

MacOS Automator Cannot Find Z4H, v3

Hello - I need to run a function from a MacOS automator "run shell script" action. This problem started after I installed z4h, so I hope you don't mind if I ask here.

The Automator "run shell script" action lets you specify a shell so I select /bin/zsh, but, the environment is apparently not the same as the interactive one. When I first built this automator action, someone on a forum had recommended sourcing the zsh rc files at the top of the "run shell script" action to make sure to get paths and so on, so I did:

source ~/.zshenv
source ~/.zshrc
my-function #located in .zshrc

This worked fine with my previous setup. Now however, after installing z4h, when running this automator action, I started to get errors that automator "cannot find z4h" when parsing .zshrc. Another forum post recommended exporting PATH so I added that, and also thought I might need FPATH, so I export that too.

export PATH=/usr/bin:/usr/local/bin:~/.cache/zsh4humans/fzf/bin:~/bin:$PATH
export FPATH=~/.cache/zsh4humans/zsh4humans/fn:~/.cache/zsh4humans/zsh-completions/src:~/bin/zsh/functions:/usr/local/share/zsh/site-functions:$FPATH

source ~/.zshenv
source ~/.zshrc
my-function

This does not work either, and I get:

The action "Run Shell Script" encountered an error: "/Users/me/.zshrc:27: command not found z4h

... for two lines in the .zshrc.

z4h install romkatv/archive romkatv/zsh-prompt-benchmark
z4h init || return

It's getting to the "source" part because the errors reference lines in .zshrc, and apparently it loaded .zshenv ok.

Is there anything I can try, to make sure this execution environment within Automator will find z4h?
Any advice appreciated, thanks.

No keys bound on fresh install

HI,
I'm really excited about your project.

I'm currently running a prezto zsh, and am trying out zsh4humans by cloning the repo and running

cd zsh4humans && ZDOTDIR=$(pwd) exec zsh

My terminal is kitty 0.15.0, I've tried xterm as well.

The p10k wizard runs, and the shell seems to work, with the exception that there are no z4h keys bound. bindkey | grep z4h gives no results.

I've tried setting ~/.zshenv to

ZDOTDIR=~/zsh4humans
[[ -e $ZDOTDIR/.zshenv ]] && . $ZDOTDIR/.zshenv

and logging out/in

Any idea what's happening?

Additional startup files, referencing functions, updating v3

Hi - a couple of questions if you don't mind; sorry for my newbness. In the readme, I see the recommendation not to create the additional startup files:

When you start Zsh, it automatically sources ~/.zshrc -- your personal config that builds on Zsh For Humans. Zsh supports several additional startup files with complex rules governing when each file is sourced. The additional startup files are ~/.zshenv, ~/.zprofile, ~/.zlogin and ~/.zlogout. It is not recommended to create these files.

I have been using zsh for a few years now, and have accumulated settings in those based on recommendations on sites for some specific situation or in the notes from a brew install, in addition to having some settings / lines added by prezto.

Does the above warning mean, I can/should just re-create everything in ~/.zshrc like setting the EDITOR env var? I assume considering the timing or sequence that these are loaded with, makes the answer "it depends" but, I am thinking to just comb through, find anything I know is essential, and just start fresh. Would you say it's ok to just chuck all my EXPORT PATH=$PATH:/path/to/foo type statements into ~/.zshrc?

2. Lots of functions

I've got a number of functions littering up my ~/.zshrc. I want to move them to an external file and source them, to keep things compact. Is this the best practice assuming I'm using this project? :

z4h source $HOME/path/to/my/functions.zsh

3. Updating

If I install v3, then will the updater update from v3? This bit from ~/.zshrc appears to govern the updating, but, does channel stable mean v2?

# 'ask': ask to update; 'no': disable auto-update.
zstyle ':z4h:'                auto-update      ask
# Auto-update this often; has no effect if auto-update is 'no'.
zstyle ':z4h:'                auto-update-days 28
# Stability vs freshness of plugins: stable, testing or dev.
zstyle ':z4h:*'               channel          stable

The readme says there is no update mechanism for .zshrc so does that mean updating won't clobber my ~/.zshrc if I put customizations in there then do an update?

linux brew breaks man pages

Hi @romkatv, since the linux brew integration, the man command only list brew manpages.

❯ echo $MANPATH
/home/linuxbrew/.linuxbrew/share/man

When I type MANPATH=$MANPATH: (note the trailling :), I get all the manpages back.

Binding of ^J causing issues in libvterm in emacs

I just spent all morning reinstalling emacs, libvterm, p10k, and z4h to try and isolate a problem in my embedded terminal (libvterm) within emacs. The problem is that after typing a command to execute, the moment I press RET on my Mac, the line of text I typed would disappear as if I had typed a ^U.

Because I've changed so much of my personal setup this past week, I had no idea where to start so I just started ruling one component at a time. Fast forward several hours later, after having ruled everything else out, I turned my attention to z4h. I basically commented blocks of z4h.zsh to narrow down the issue, which turned out to be this line:

bindkey '^J'      backward-kill-line             # ctrl+j     delete line before cursor

The funny thing is that I actually went looking for any rebinding of ^M, which is the carriage return, but I did not think about looking at ^J, which is line feed. Apparently, my embedded vterm in emacs sends ^J characters. Here are the relevant parts of the emacs vterm module source code:

(defun vterm-send-return ()
  "Send `C-m' to the libvterm."
  (interactive)
  (when vterm--term
    (if (vterm--get-icrnl vterm--term)
        (process-send-string vterm--process "\C-j")
      (process-send-string vterm--process "\C-m"))))

emacs_value Fvterm_get_icrnl(emacs_env *env, ptrdiff_t nargs,
                             emacs_value args[], void *data) {
  Term *term = env->get_user_ptr(env, args[0]);

  if (term->pty_fd > 0) {
    struct termios keys;
    tcgetattr(term->pty_fd, &keys);

    if (keys.c_iflag & ICRNL)
      return Qt;
    else
      return Qnil;
  }
  return Qnil;
}

I guess the point is that we probably shouldn't bind ^J as there are terminals out there that send it when a user enters a command.

Thoughts?

use ${ZDOTDIR} for custom installation folder

First of all..this is amazing and exactly what I've been looking for!

Can I recommend that instead of using ~/.zshrc and ~/.cache, that you instead use ${ZDOTDIR}/*? I want to keep my files out of the home directory and right now I have to manually change your script, which means if/when you update, it will break.

Configure ssh_config to use z4h ssh

I am wondering if it is possible to use z4h ssh for some host when connecting via the ssh command.
I tried to use ProxyCommand but with little success. I tried stuff like using zsh -ic 'z4h ssh %h' or sourcing: source ${Z4H:=${XDG_CACHE_HOME:-$HOME/.cache}/zsh4humans}/romkatv/zsh4humans/fn/-z4h-ssh %h. The most far I could get was getting spammed by "Pseudo-terminal will not be allocated because stdin is not a terminal."

Any way to make this work or is it a bad idea to begin with? Would scp break for example.

ssh and TERM

Hi,

When on a linux desktop, my current terminal emulator usually is Termite which has it's own terminfo and TERM set to xterm-termite.
This can cause some issues when ssh'ing to hosts that doesn't have this terminfo installed, and installing this terminfo on all remote hosts doesn't seem like a good option.
A reasonable solution might be to have this ssh-function locally.
If your remote host has z4h already installed, the LC__ORIGINALTERM environment variable sent from your source host would need to be evaluated early in z4h.zsh, setting the TERM to the most suitable value, with reasonable fallbacks.

I tried to implement the above in my own .zshrc after z4h init-block, but that seem be to late in the execution. And I'm not sure what issues I may cause myself if I apply the TERM-evaluation code before z4h.zsh is loaded.

BTW, have a look at vincentbernat's zshrc-repo. Lots of interesting features in there. I've adopted both the bookmark-function and the locale settings from there.

---

Sidenote;
Just wanted to highlight an error occurring for me on a host using latest update of z4h v3;

❯ 
-z4h-zle-line-init:zle:4: bad option: -z
thomasd@thomasd-lab  ~
❯ zsh --version
zsh 5.7.1 (x86_64-debian-linux-gnu)

(and yes, I should stick to the stable releases 🙃)