{"id":13434434,"url":"https://github.com/romkatv/zsh4humans","last_synced_at":"2025-05-14T08:09:23.800Z","repository":{"id":37957724,"uuid":"240969480","full_name":"romkatv/zsh4humans","owner":"romkatv","description":"A turnkey configuration for Zsh","archived":false,"fork":false,"pushed_at":"2025-05-09T08:15:36.000Z","size":944,"stargazers_count":1945,"open_issues_count":32,"forks_count":128,"subscribers_count":38,"default_branch":"master","last_synced_at":"2025-05-09T09:26:07.396Z","etag":null,"topics":["zsh"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/romkatv.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-16T21:33:36.000Z","updated_at":"2025-05-09T08:15:40.000Z","dependencies_parsed_at":"2022-07-10T01:26:28.103Z","dependency_job_id":"4dbc0056-6686-44df-8b90-658a01352e60","html_url":"https://github.com/romkatv/zsh4humans","commit_stats":{"total_commits":1090,"total_committers":15,"mean_commits":72.66666666666667,"dds":"0.019266055045871533","last_synced_commit":"8b4b7444fd642274a367a88b1a4eb153947eeb4a"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romkatv%2Fzsh4humans","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romkatv%2Fzsh4humans/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romkatv%2Fzsh4humans/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romkatv%2Fzsh4humans/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/romkatv","download_url":"https://codeload.github.com/romkatv/zsh4humans/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101558,"owners_count":22014908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["zsh"],"created_at":"2024-07-31T02:01:56.892Z","updated_at":"2025-05-14T08:09:18.791Z","avatar_url":"https://github.com/romkatv.png","language":null,"funding_links":[],"categories":["Others","Tutorials","Terminal"],"sub_categories":["Generic ZSH","Shell"],"readme":"# Zsh for Humans\n\n- **THE PROJECT HAS VERY LIMITED SUPPORT**\n- **NO NEW FEATURES ARE IN THE WORKS**\n- **MOST BUGS WILL GO UNFIXED**\n\nA turnkey configuration for Zsh that aims to work really well out of the box. It combines the best\nZsh plugins into a coherent whole that feels like a finished product rather than a DIY starter kit.\n\nIf you want a great shell that just works, this project is for you.\n\n## Table of contents\n\n* 1. [Features](#features)\n* 2. [Installation](#installation)\n* 3. [Try it in Docker](#try-it-in-docker)\n* 4. [Caveats](#caveats)\n* 5. [Usage](#usage)\n  * 5.1. [Accepting autosuggestions](#accepting-autosuggestions)\n  * 5.2. [Completing commands](#completing-commands)\n  * 5.3. [Searching command history](#searching-command-history)\n  * 5.4. [Interactive search with `fzf`](#interactive-search-with-fzf)\n  * 5.5. [SSH](#ssh)\n* 6. [Customization](#customization)\n  * 6.1. [Customizing prompt](#customizing-prompt)\n  * 6.2. [Customizing appearance](#customizing-appearance)\n  * 6.3. [Additional Zsh startup files](#additional-zsh-startup-files)\n* 7. [Updating](#updating)\n* 8. [Uninstalling](#uninstalling)\n* 9. [Advanced configuration tips](#advanced-configuration-tips)\n\n## Features\n\n- Powerful POSIX-based shell preconfigured to work great out of the box.\n- Easy-to-use installation wizard. Does not require `git`, `zsh` or `sudo`.\n- [Syntax highlighting](https://github.com/zsh-users/zsh-syntax-highlighting) for the command line.\n- [Autosuggestions](https://github.com/zsh-users/zsh-autosuggestions) for commands based on command\n  history.\n- [Command prompt](https://github.com/romkatv/powerlevel10k) configurable through a builtin\n  configuration wizard.\n- Command completions and history searchable with [fzf](https://github.com/junegunn/fzf).\n- [Super fast](https://github.com/romkatv/zsh-bench). No lag when you open a new tab in the terminal\n  or run a command.\n- The complete shell environment can be automatically teleported to the remote host when connecting\n  over `ssh`. This does not require `git`, `zsh` or `sudo` on the remote host.\n- Command history can be shared across different hosts. For example, history from `ssh foo`\n  can be made available within `ssh bar` and/or on the local machine.\n\n## Installation\n\nRun this command in bash, zsh, or sh:\n\n```shell\nif command -v curl \u003e/dev/null 2\u003e\u00261; then\n  sh -c \"$(curl -fsSL https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)\"\nelse\n  sh -c \"$(wget -O- https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)\"\nfi\n```\n\nThe installer backs up the existing Zsh startup files, creates new ones, installs everything\nnecessary for Zsh for Humans, starts a new shell, and configures it as login shell. It asks for\nconfirmation on every step so that you are always in control. Installation requires `curl` or\n`wget`. It does not require `git`, `zsh`, `sudo` or anything else.\n\n\u003cdetails\u003e\n  \u003csummary\u003eRecording of the installation process\u003c/summary\u003e\n\n  ![Zsh for Humans installation](\n    https://github.com/romkatv/powerlevel10k-media/raw/32c7d40239c93507277f14522be90b5750f442c9/z4h-install.gif)\n\n\u003c/details\u003e\n\n## Try it in Docker\n\nTry Zsh for Humans in a Docker container. You can safely install additional software and make any\nchanges to the file system. Once you exit Zsh, the image is deleted.\n\n- **Alpine Linux**: starts quickly; install additional software with `apk add \u003cpackage\u003e`\n  ```zsh\n  docker run -e TERM -e COLORTERM -e LC_ALL=C.UTF-8 -w /root -it --rm alpine sh -uec '\n    apk add zsh curl tmux\n    sh -c \"$(curl -fsSL https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)\"'\n  ```\n- **Ubuntu**: install additional software with `apt install \u003cpackage\u003e`:\n  ```zsh\n  docker run -e TERM -e COLORTERM -w /root -it --rm ubuntu sh -uec '\n    apt-get update\n    apt-get install -y zsh curl tmux\n    sh -c \"$(curl -fsSL https://raw.githubusercontent.com/romkatv/zsh4humans/v5/install)\"'\n  ```\n\n## Caveats\n\nZsh for Humans is not a good choice for users who prefer vi bindings in their shell.\n\nZsh for Humans has very little documentation. There is no list of configuration options it\nrecognizes and no description of what those options do.\n\n## Usage\n\nIf you've used Zsh, Bash or Fish before, Zsh for Humans should feel familiar. For the most part\neverything works as you would expect.\n\n### Accepting autosuggestions\n\nAll key bindings that move the cursor can accept *command autosuggestions*. For example, moving the\ncursor one word to the right will accept that word from the autosuggestion. The whole autosuggestion\ncan be accepted without moving the cursor with \u003ckbd\u003eAlt+M\u003c/kbd\u003e/\u003ckbd\u003eOption+M\u003c/kbd\u003e.\n\nAutosuggestions in Zsh for Humans are provided by [zsh-autosuggestions](\n  https://github.com/zsh-users/zsh-autosuggestions). See its homepage for more information.\n\n### Completing commands\n\nWhen completing with \u003ckbd\u003eTab\u003c/kbd\u003e, suggestions come from *completion functions*. For most\ncommands completion functions are provided by Zsh proper. Additional completion functions are\ncontributed by [zsh-completions](https://github.com/zsh-users/zsh-completions). See its homepage\nfor the list of commands it supports.\n\nAmbiguous completions automatically start [fzf](#interactive-search-with-fzf). Accept the desired\ncompletion with \u003ckbd\u003eEnter\u003c/kbd\u003e. You can also select more than one completion with\n\u003ckbd\u003eCtrl+Space\u003c/kbd\u003e or all of them with \u003ckbd\u003eCtrl+A\u003c/kbd\u003e.\n\n### Searching command history\n\n\u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e keys fetch commands from history that contain what you've already\ntyped on the command line. For example, if you press \u003ckbd\u003eUp\u003c/kbd\u003e after typing `grep`, you'll see\nthe last executed command that contains `grep`.\n\n\u003ckbd\u003eCtrl+R\u003c/kbd\u003e starts [fzf](#interactive-search-with-fzf) to search over history.\n\n### Interactive search with `fzf`\n\nSeveral UI elements in Zsh for Humans use [fzf](https://github.com/junegunn/fzf) to quickly select\nan item from a potentially large list of candidates. You can type multiple search terms delimited by\nspaces. For example:\n\n```text\n^music .mp3$ sbtrkt !fire\n```\n\n| Token     | Match type        | Description                          |\n| --------- | ----------------- | ------------------------------------ |\n| `wild`    | substring         | Items with the substring `wild`      |\n| `^music`  | prefix            | Items that start with `music`        |\n| `.mp3$`   | suffix            | Items that end with `.mp3`           |\n| `!wild`   | inverse substring | Items without the substring `wild`   |\n| `!^music` | inverse prefix    | Items that do not start with `music` |\n| `!.mp3$`  | inverse suffix    | Items that do not end with `.mp3`    |\n\nA single bar (`|`) acts as an OR operator. For example, the following query matches entries that\nstart with `core` and end with either `go`, `rb`, or `py`.\n\n```text\n^core go$ | rb$ | py$\n```\n\nSee [fzf](https://github.com/junegunn/fzf) homepage for more information.\n\n### SSH\n\n[![SSH teleportation](https://asciinema.org/a/542763.svg)](https://asciinema.org/a/542763)\n\nWhen you connect to a remote host over SSH, your local Zsh for Humans environment can be teleported\nover to it. The first login to a remote host may take some time. After that it's as fast as normal\n`ssh`.\n\nSearch for \"ssh\" in your `~/.zshrc` for information on how to enable and configure SSH\nteleportation.\n\n## Customization\n\nYou can (and should) edit `~/.zshrc` to customize your shell. It's a very good idea to read through\nthe whole file to see which customization options are in there and to flip some of them to your\nliking.\n\nWhen adding your customizations, put them next to the existing lines that do similar things. The\ndefault `~/.zshrc` contains the following types of customizations that should serve as examples:\n\n- Export environment variables.\n- Extend `PATH`.\n- Define aliases.\n- Add flags to existing aliases.\n- Define functions.\n- Source additional local files.\n- Load Oh My Zsh plugins.\n- Clone and load external Zsh plugins.\n- Set shell options.\n- Autoload functions.\n- Change key bindings.\n\n### Customizing prompt\n\nPrompt in Zsh for Humans is provided by [Powerlevel10k](https://github.com/romkatv/powerlevel10k).\nRun `p10k configure` to access its interactive configuration wizard. Further customization can be\ndone by editing `~/.p10k*.zsh` files. There can be more than one configuration file to account for\nterminals with limited capabilities. Most users will ever only see `~/.p10k.zsh`. When in doubt,\nconsult `$POWERLEVEL9K_CONFIG_FILE`. This parameter is set by Zsh for Humans and it always points\nto the Powerlevel10k config file currently in use.\n\nSee [Powerlevel10k](https://github.com/romkatv/powerlevel10k) homepage for more information.\n\n### Customizing appearance\n\nDifferent parts of Zsh for Humans UI are rendered by different projects.\n\n![Zsh for Humans](https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/prompt-highlight.png)\n\nEverything within the highlighted areas on the screenshot is *prompt*. It is produced by\n[Powerlevel10k](https://github.com/romkatv/powerlevel10k). See\n[Customizing prompt](#customizing-prompt).\n\nThe listing of files produced by `ls` command is colored by `ls` itself. Different commands have\ndifferent ways of customizing their output, and even different version of `ls` have different flags\nand environment variables related to colors. Zsh for Humans enables colored output for common\ncommands such as `ls` and `grep`. For further customization consult documentation of the respective\ncommand.\n\n`echo hello` is the current command being typed. Syntax highlighting for it is provided by\n[zsh-syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting). See its homepage\nfor documentation on how to customize it.\n\nAfter `echo hello` you can see `world` in grey. This is not a part of the command, so pressing\n\u003ckbd\u003eEnter\u003c/kbd\u003e will print only `hello` but not `world`. The latter is an autosuggestion provided\nby [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions) that you can\n[accept](#accepting-autosuggestions) in part or in full. It comes from command history and it's a\ngreat productivity booster. See [zsh-autosuggestions](\n  https://github.com/zsh-users/zsh-autosuggestions) homepage for more information.\n\nLast but not least, your terminal has a say about the appearance of *everything* that runs within\nit. The base colors, numbered from 0 to 15, can look differently in different terminals and even\nin the same terminal with different settings. Most modern terminals support *themes*,\n*color palettes* or *color schemes* that allow you to quickly change base colors. If colors in your\nterminal look unpleasant, try a different theme. Note that colors with codes above 15, as well as\ncolors specified as RGB triplets, don't get affected by terminal themes. They look the same\neverywhere.\n\n### Additional Zsh startup files\n\nWhen you start Zsh, it automatically sources `~/.zshenv` and `~/.zshrc`. The former bootstraps Zsh\nfor Humans, the latter is your personal config. It is strongly recommended to keep all shell\ncustomization and configuration (including exported environment variables such as `PATH`) in\n`~/.zshrc` or in files sourced from `~/.zshrc`. If you are certain that you must export some\nenvironment variables in `~/.zshenv`, do it where indicated by comments.\n\nZsh supports several additional startup files with complex rules governing when each file is\nsourced. The additional startup files are `~/.zprofile`, `~/.zlogin` and `~/.zlogout`. **Do not\ncreate these files** unless you are absolutely certain you need them.\n\n## Updating\n\nRun `z4h update` to update Zsh for Humans. There is no update mechanism for `~/.zshrc` itself.\n\n## Uninstalling\n\n1. Delete or replace `~/.zshenv` and `~/.zshrc`. If you had these files prior to the installation of\n   Zsh for Humans and have replied in the affirmative when asked by the installer whether you want\n   them backed up, you can find them in `~/zsh-backup`.\n2. Restart your terminal. **Restarting zsh is not enough.**\n3. Delete Zsh for Humans cache:\n   ```zsh\n   rm -rf -- \"${XDG_CACHE_HOME:-$HOME/.cache}/zsh4humans/v5\"\n   ```\n\n## Advanced configuration tips\n\nSee [this document](tips.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromkatv%2Fzsh4humans","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fromkatv%2Fzsh4humans","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromkatv%2Fzsh4humans/lists"}