{"id":13897714,"url":"https://github.com/alexbarton/ax-zsh","last_synced_at":"2025-07-17T14:32:41.004Z","repository":{"id":44383430,"uuid":"46225115","full_name":"alexbarton/ax-zsh","owner":"alexbarton","description":"Modular configuration system for the Z shell (ZSH)","archived":false,"fork":false,"pushed_at":"2025-06-15T09:01:22.000Z","size":474,"stargazers_count":25,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-15T10:18:53.818Z","etag":null,"topics":["ax-zsh","configuration","manager","plugin","plugin-manager","shell","zsh"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/alexbarton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-11-15T16:13:37.000Z","updated_at":"2025-06-15T09:01:25.000Z","dependencies_parsed_at":"2023-12-15T21:14:34.450Z","dependency_job_id":"c1cee913-ef81-4c98-a263-9a5b3628796b","html_url":"https://github.com/alexbarton/ax-zsh","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alexbarton/ax-zsh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexbarton%2Fax-zsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexbarton%2Fax-zsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexbarton%2Fax-zsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexbarton%2Fax-zsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexbarton","download_url":"https://codeload.github.com/alexbarton/ax-zsh/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexbarton%2Fax-zsh/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265616854,"owners_count":23798909,"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":["ax-zsh","configuration","manager","plugin","plugin-manager","shell","zsh"],"created_at":"2024-08-06T18:03:49.481Z","updated_at":"2025-07-17T14:32:40.998Z","avatar_url":"https://github.com/alexbarton.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# AX-ZSH: Alex' Modular ZSH Configuration\n\n[AX-ZSH] is a modular configuration system for the Z shell ([ZSH]).\nIt provides sane defaults and is extendable by plugins.\n\nAX-ZSH integrates well with [Powerlevel10k] and other extensions, even plugins\nof [OhMyZsh], see [below](#integration-with-other-projects).\n\nThe homepage of [AX-ZSH] can be found at [GitHub]:\n\u003chttps://github.com/alexbarton/ax-zsh\u003e.\n\n## Installation\n\nPrerequisites:\n\n* [ZSH] – obviously ;-)\n* [Git] (optional but recommended!)\n\nInstalling AX-ZSH is a two-step process:\n\n1. Clone or copy the source files into the `~/.axzsh` directory,\n2. Run the `~/.axzsh/install.sh` script.\n\nThe `install.sh` script creates symbolic links for `~/.zprofile`, `~/.zshrc`,\n`~/.zlogin`, and `~/.zlogout` (don't worry, already existing files are backed\nup).\n\n*Note:* The installation is per-user and only changes/installs files into the\nhome directory of the current user (`~`). AX-ZSH is not meant to be installed\nglobally for all users on a system at once, and you don't need to become \"root\"\nor any other user with elevated privileges!\n\n### Installation using Git\n\nWhen using [Git], the preferred method, it is best to directly clone the AX-ZSH\nrepository into the `~/.axzsh` directory and call `install.sh` from this\nlocation:\n\n```sh\ngit clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh\n~/.axzsh/install.sh\n```\n\n### Installation without Git\n\n*Note:* If you do not install AX-ZSH with [Git], you will not be able to upgrade\nitself afterwards with the integrated `axzsh upgrade` command! Therefore this\nmethod is *not recommended* for normal use!\n\n```sh\ncurl -Lo ax-zsh-master.zip https://github.com/alexbarton/ax-zsh/archive/refs/heads/master.zip\nunzip ax-zsh-master.zip\nmv ax-zsh-master ~/.axzsh\n~/.axzsh/install.sh\n```\n\n### Post-Installation Tasks\n\nAfter installing AX-ZSH, using Git or via an archive file, you should close all\nrunning ZSH sessions and restart them to activate AX-ZSH. And maybe you want to\nchange your default shell to ZSH if you haven't already?\n\nFor example like this:\n\n```sh\n# Set new default shell\nchsh -s $(command -v zsh)\n\n# Replace running shell with a ZSH login shell\nexec $(command -v zsh) -l\n```\n\n## Upgrade\n\nWhen you used Git to install AX-ZSH (and/or plugins), you can use the `axzshctl`\ncommand to upgrade AX-ZSH itself and external plugins like this:\n\n```sh\naxzshctl upgrade\n```\n\n## Usage\n\nAX-ZSH comes with a hopefully sane default configuration and can be extended\nusing plugins. Different types of plugins are supported:\n\n* Plugins shipped with AX-ZSH.\n* Themes shipped with AX-ZSH.\n* 3rd-party plugins:\n  * installed manually into `$AXZSH/custom_plugins`\n  * stand-alone plugins stored on GitHub\n  * plugins of OhMyZsh from its GitHub repository\n* 3rd-party themes:\n  * installed manually into `$AXZSH/custom_themes`\n  * some stand-alone themes stored on GitHub\n\n### Configuration of other applications \u0026 tools\n\nSome tools, notably remote access tools like ssh(1) and screen-multiplexers\nlike screen(1) or tmux(1), can be configured to better support AX-ZSH. For\nexample, AX-ZSH tries to adjust itself for a sane terminal and locale setup,\nwhich in turn requires some information (mostly environment variables) being\navailable and passed to the ZSH running AX-ZSH on the (target) system.\n\n#### OpenSSH Client\n\nIf you are using the OpenSSH client, the following configuration in your\n`~/.ssh/config` file is very useful:\n\n```ini\n# Some defaults.\n# Note: Place this block LAST to not override some other settings, if any, as\n# OpenSSH uses the first(!) match it finds!\nHost *\n    # Pass some environment variables to the remote host to allow the remote\n    # system to get a better idea of your used and desired working environment:\n    SendEnv COLORTERM LANG LC_* TERM_* TZ\n\n    # Don't hash host names in the ~/.ssh/known_hosts file, so that ZSH\n    # compeltion functions can detect helpful host names to complete.\n    # Note: This has an \"security impact\". It is on YOU to check what your\n    # security requirements are!\n    HashKnownHosts no\n```\n\n#### OpenSSH Client\n\nOn an OpenSSH server, the following configuration in one of its configuration\nfiles (for example, a good place is in a drop-in configuration file like\n`/etc/ssh/sshd_config.d/local.conf`) allows SSH clients to pass some\nenvironment variables to the server:\n\n```init\n# Allow SSH client to pass some \"safe\" environment variables to the server:\nAcceptEnv COLORTERM LANG LC_* TERM_* TZ\n```\n\nThis is required for the SSH client configuration shown above to work.\n\nDon't forget to have `sshd` reload its configuration, for example using\n`systemctl reload ssh.service` or `pkill -o -HUP sshd`, or whatever is used on\nyour operating system.\n\n### Check whether all locally available \"useful\" plug-ins are activated\n\nMost plugins can be enabled even when the commands they work with aren't\navailable and won't do any harm. But to keep ZSH startup times low, you should\nonly enable plugins that are useable on your local system and which you actually\nplan to use.\n\nYou can use the following command to let AX-ZSH scan the status of all locally\navailable plugins:\n\n```sh\naxzshctl check-plugins\n```\n\nIt will summarize the status of all enabled plugins, and suggest to enable\nplugins which seem to make sense on the system and to disable enabled plugins\nthat seem not to be supported (for example because of missing dependencies).\n\n### List enabled plugins\n\nRun the following command to list all currently enabled plugins:\n\n```sh\naxzshctl list-enabled\n```\n\n### Enable plugins\n\nAX-ZSH comes with a sane \"core ZSH configuration\", but it can show its true\nstrengths when enabling additional plugins for additional tools and commands\nthat are available on your system and you want to use.\n\nDifferent types of plugins are supported (see the introduction to the section\n\"*usage*\" above) which are differentiated by their identifier:\n\n* `\u003cname\u003e`: locally available plugin, either bundled with AX-ZSH itself, or\n  installed manually (see below).\n* `\u003crepository\u003e/\u003cname\u003e`: stand-alone [GitHub] repository.\n* `@ohmyzsh/\u003cname\u003e`: [OhMyZsh] plugin from the OhMyZsh GitHub\n  repository (see \u003chttps://github.com/ohmyzsh/ohmyzsh/tree/master/plugins\u003e).\n\nYou can enable one or more plugins like this:\n\n```sh\naxzshctl enable-plugin \u003cidentifier\u003e [\u003cidentifier\u003e […]]\n```\n\n*Hint:* *Tab-completion* works for sub-commands and already locally available\nplugin names!\n\nSome examples:\n\n```sh\n# Enable some plugins bundled with AX-ZSH:\naxzshctl enable-plugin editor_select git ssh_autoadd\n\n# Enable the Powerlevel10k \"theme plugin\" from GitHub, see\n# \u003chttps://github.com/romkatv/powerlevel10k\u003e:\naxzshctl enable-plugin romkatv/powerlevel10k\n\n# Enable the \"fast-syntax-highlighting\" plugin from GitHub, see\n# \u003chttps://github.com/zdharma-continuum/fast-syntax-highlighting\u003e:\naxzshctl enable-plugin zdharma-continuum/fast-syntax-highlighting\n\n# Enable the Git and tmux plugins of OhMyZsh:\naxzshctl enable-plugin @ohmyzsh/git @ohmyzsh/tmux\n```\n\n#### Custom local plugins\n\nYou can link custom plugins stored in arbitrary directories using `axzshctl`\nby specifying the complete path name. Or you can place additional plugins into\nthe `$AXZSH/custom_plugins` folder which is searched by the `axzshctl` tool\nby default.\n\nIn addition you can set the `AXZSH_PLUGIN_D` variable (and `ZSH_CUSTOM` like\n[OhMyZsh]) to specify additional plugin search directories.\n\n### Disable plugins\n\nRun the following command to disable a currently enabled plugin:\n\n```sh\naxzshctl disable-plugin \u003cidentifier\u003e [\u003cidentifier\u003e […]]\n```\n\n*Hint:* *Tab-completion* works for sub-commands and plugin names!\n\n### Update plugin cache\n\nAX-ZSH uses a \"plugin cache\" to speedup ZSH start times. This cache is\nautomatically updated when using the `axzshctl` sub-commands, for example when\nenabling or disabling plugins, or when  upgrading the AX-ZSH installation and\nall plugins.\n\nBut you *have to* update the cache when manually installing plugins or during\ndevelopment of a own local plugin after updating its code!\n\nRun the following command to update the AX-ZSH cache:\n\n```sh\naxzshctl update-caches\n```\n\n### Other `axzshctl` sub-commands\n\nPlease run `axzshctl --help` to get a full list of a available sub-commands:\n\n```sh\naxzshctl --help\n```\n\n## Integration with other projects\n\n### Powerlevel10k\n\nAX-ZSH supports [Powerlevel10k] out of the box, you just have to install it as a\nplugin:\n\n```sh\naxzshctl enable-plugin romkatv/powerlevel10k\n```\n\n*Hint:* Once the Powerlevel10k plugin theme is installed, you can use the\nregular `axzshctl set-theme` command to enable it, like for any other installed\ntheme: `axzshctl set-theme powerlevel10k`.\n\n## AX-ZSH \u0026 local ZSH configuration\n\nDon't modify `~/.zprofile`, `~/.zshrc`, `~/.zlogin`, or `~/.zlogout`! These\nare links to \"AX-ZSH\"-private files that can become overwritten when updating.\n\nYou can use the following files for local ZSH configuration:\n\n1. AX-ZSH doesn't use `~/.zshenv` in any way. So you can use this file for your\n   own purposes (for example, to set up some environment variables that AX-ZSH\n   relies on).\n\n2. AX-ZSH reads the optional files `~/.zprofile.local`, `~/.zshrc.local`,\n   `~/.zlogin.local`, and `~/.zlogout.local` after its own core initialization\n   files when present.\n\n## Environment variables\n\nExpected to be already set:\n\n* `HOME`\n* `LOGNAME`\n\nValidated and/or set up by core plugins:\n\n* `AXZSH` – AX-ZSH installation directory\n* `HOST`\n* `HOSTNAME` (same as HOST, deprecated)\n* `LOCAL_HOME`\n* `PS1`\n* `SHORT_HOST`\n* `TMPDIR` (set and always ends with a \"/\")\n* `XDG_CACHE_HOME`\n* `XDG_RUNTIME_DIR`\n* `ZSH_CACHE_DIR`\n\n___\n[AX-ZSH]: \u003chttps://github.com/alexbarton/ax-zsh\u003e \"AX-ZSH Homepage\"\n[Git]: \u003chttps://git-scm.com/\u003e \"Git Homepage\"\n[GitHub]: \u003chttps://github.com/\u003e \"GitHub Homepage\"\n[OhMyZsh]: \u003chttps://ohmyz.sh/\u003e \"OhMyZsh Homepage\"\n[Powerlevel10k]: \u003chttps://github.com/romkatv/powerlevel10k\u003e \"Powerlevel10k Homepage\"\n[ZSH]: \u003chttps://www.zsh.org/\u003e \"ZSH Homepage\"\n\n[AX-ZSH] Copyright (c) 2015-2025 Alexander Barton \u003calex@barton.de\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexbarton%2Fax-zsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexbarton%2Fax-zsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexbarton%2Fax-zsh/lists"}