{"id":15209500,"url":"https://github.com/xpmo/zsh-ls-colors","last_synced_at":"2025-08-24T09:19:52.352Z","repository":{"id":54393678,"uuid":"227099135","full_name":"xPMo/zsh-ls-colors","owner":"xPMo","description":"A zsh library to use LS_COLORS","archived":false,"fork":false,"pushed_at":"2021-02-25T04:38:32.000Z","size":356,"stargazers_count":35,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-02T02:03:51.320Z","etag":null,"topics":["colorization","ls-colors","zsh","zsh-library"],"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/xPMo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-10T11:10:40.000Z","updated_at":"2025-01-11T15:37:21.000Z","dependencies_parsed_at":"2022-08-13T14:20:30.038Z","dependency_job_id":null,"html_url":"https://github.com/xPMo/zsh-ls-colors","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xPMo%2Fzsh-ls-colors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xPMo%2Fzsh-ls-colors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xPMo%2Fzsh-ls-colors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xPMo%2Fzsh-ls-colors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xPMo","download_url":"https://codeload.github.com/xPMo/zsh-ls-colors/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238840731,"owners_count":19539602,"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":["colorization","ls-colors","zsh","zsh-library"],"created_at":"2024-09-28T07:40:27.859Z","updated_at":"2025-02-14T12:30:44.993Z","avatar_url":"https://github.com/xPMo.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zsh support for LS_COLORS\n\n![Demo screenshot](https://raw.githubusercontent.com/xPMo/zsh-ls-colors/image/demo-new.png)\n\nA zsh library to use `LS_COLORS` in scripts or other plugins.\n\nFor a simple demo, see the `zstyle-demo` script in this repo.\n\nIf a use case isn't adequately covered,\nplease [open an issue](https://github.com/xPMo/zsh-ls-colors/issues/)!\n\nFinally, if you are making use of this plugin, [add it to the wiki](https://github.com/xPMo/zsh-ls-colors/wiki/Uses-in-the-wild)!\n\n## Using zsh-ls-colors in a plugin\n\nYou can use this as a submodule or a subtree.\n\n### submodule:\n\n```sh\n# Add (only once)\ngit submodule add git://github.com/xPMo/zsh-ls-colors.git ls-colors\ngit commit -m 'Add ls-colors as submodule'\n\n# Update\ncd ls-colors\ngit fetch\ngit checkout origin/master\ncd ..\ngit commit ls-colors -m 'Update ls-colors to latest'\n```\n\n### Subtree:\n\n```sh\n# Initial add\ngit subtree add --prefix=ls-colors/ --squash -m 'Add ls-colors as a subtree' \\\n\tgit://github.com/xPMo/zsh-ls-colors.git master\n\n# Update\ngit subtree pull --prefix=ls-colors/ --squash -m 'Update ls-colors to latest' \\\n\tgit://github.com/xPMo/zsh-ls-colors.git master \n\n\n# Or, after adding a remote:\ngit remote add ls-colors git://github.com/xPMo/zsh-ls-colors.git\n\n# Initial add\ngit subtree add --prefix=ls-colors/ --squash -m 'Add ls-colors as a subtree' ls-colors master\n\n# Update\ngit subtree pull --prefix=ls-colors/ --squash -m 'Update ls-colors to latest' ls-colors master \n```\n\n## API v2:\n\nThis function takes a context and a list of files as input,\nand returns a list of colored strings, formatted according to `$format`.\n\n```zsh\n${prefix}::fmt [ -f $format | -F $format ] [ -o | -0 | -a | -A ] $context $files[@]\n```\n\n### Loading the library\n\nSince functions are a public namespace,\nThis library allows you to customize the preifix for your plugin:\n\n```zsh\n# load function as my-lscolors::fmt\n# The remaining arguments to source determines which lib/ files you want to load.\n# If no arguments are provided, then all lib/*.zsh are loaded.\nsource ${0:h}/ls-colors/ls-colors.zsh my-lscolors fmt\n```\n\n### Customizing Colors with styles\n\nThe `::fmt` function uses the usual `list-colors` style to determine how to color the results.\nSet the style as follows:\n\n```zsh\n# Uses LS_COLORS format\nzstyle $pattern list-colors ${(s[:])LS_COLORS} '*.ext=1'\n```\n\nIn addition, you can enable `extendedglob` for certain contexts:\n\n```zsh\nzstyle $pattern list-colors-extended true\nzstyle $pattern list-colors ${(s[:])LS_COLORS} '(#i).ext=1'\n```\n\n_Personally, I like this method for dynamically getting LS_COLORS for all contexts:_\n\n```zsh\nzstyle -e '*' list-colors 'reply=(${(s[:])LS_COLORS})'\n```\n\n### Customizing format with styles\n\nThe `::fmt` function uses the `list-format` style to determine how to format the results.\nSet the style as follows:\n\n```zsh\nzstyle $pattern list-format '%F%P%r%(h.%I%i. -\u003e %L%l%r)'\n```\n\n| Format specifier | Meaning | Example (`PWD=/usr`, `./bin/sh` symlinked to `dash`) |\n| --- | --- | --- |\n| `%F` | The color/console codes which match the file | `\\e[0m\\01;36m` |\n| `%f` | The file basename | `sh` |\n| `%P` | The file path provided | `./bin/sh` |\n| `%p` | The fully-qualified path | `/usr/bin/sh` |\n| `%L` | The color/console codes which match the target of the symlink | `\\e[0m\\e[01;32m` |\n| `%l` | The target of the symlink | `dash` |\n| `%h` | `1` if this file is a symlink, otherwise empty (useful to conditionally output the link target) | `1` |\n| `%r` | The color/console codes normally used to reset the terminal style | `\\e[0m` |\n| `%I` | The color for filetype indicators | `\\e[0m` |\n| `%i` | The single-character filetype indicator the given file | `@` |\n| `%j` | The single-character filetype indicator for the target of the symlink | `*` |\n\nFor more information on using these codes, see the section on `zformat` in `man zshmodules`.\n\nMore format specifiers may be added in the future, probably based on GNU find's `-printf` formats.\n\n### Customizing format at runtime\n\nThere are two flags to the `::fmt` function which change how `list-format` is used:\n\n```zsh\n${prefix}::fmt -f $format     # use $format if no list-format is specified for the current style\n${prefix}::fmt -F $format     # force $format, ignore the list-format specified for the current style\n```\n\n### Output method\n\nThere are four ways `::fmt` can return its results:\n\n```zsh\n${prefix}::fmt -a ...     # [default] assign results to $reply as an array\n${prefix}::fmt -A ...     # assign results to $reply as an associative array, with filenames as keys\n${prefix}::fmt -o ...     # print results to stdout separated by newlines\n${prefix}::fmt -0 ...     # print results to stdout separated by NUL characters\n```\n\n\n## Legacy API:\n\nFor more advanced usage,\ninstructions are located at top of the source files for `from-mode` and `from-name`.\n\n### Function namespacing\n\nSince functions are a public namespace,\nthis plugin allows you to customize the preifix for your plugin:\n\n```zsh\n# load functions as my-lscolors::{init,match-by,from-name,from-mode}\n# The remaining arguments to source determines which lib/ files you want to load.\n# If no arguments are provided, then all lib/*.zsh are loaded.\nsource ${0:h}/ls-colors/ls-colors.zsh my-lscolors legacy\n```\n\n### Parameter namespacing\n\nWhile indirect parameter expansion exists with `${(P)var}`,\nit doesn't play nicely with array parameters,\nand especially not with associative arrays.\n\nThere are multiple strategies to prevent unnecessary re-parsing:\n\n**Call `init` in global scope.**\nThis pollutes global namespace but prevents re-parsing `$LS_COLORS` on every function call.\n```zsh\nls-color::init\n```\n\n**Don't call init at all:**\nThis is only compatible with `::match-by`,\nand reparses LS_COLORS each time,\nbut it doesn't pollute global namespace.\n\n```zsh\nls-color::match-by $file lstat\n```\n\n**Initialize within a scope with local parameters.**\nBest for not polluting global namespace when multiple filenames need to be parsed.\n\n```zsh\n(){\n\tlocal -A namecolors modecolors\n\tls-color::init\n\n\tfor arg; do\n\t\t...\n\tdone\n}\n```\n\n**Custom parameter:** Save the array value as your own custom parameter to copy back.\n```zsh\n(){ # initially\n\tlocal -A namecolors modecolors\n\tls-color::init\n\ttypeset -ga _my_modecolors=(\"${(@kv)modecolors}\")    # you MUST use (@kv) to avoid losing empty entries\n\ttypeset -ga _my_namecolors=(\"${(kv)namecolors[@]}\")  # alternatively, use bash-style [@]\n}\n\nmy-function(){\n\tlocal -A modecolors=(\"${(@)_my_modecolors}\")         # you MUST use (@) to avoid losing empty entries\n\tlocal -A namecolors=(\"${_my_namecolors[@]}\")         # alternatively, use bash-style [@]\n\n\t...\n}\n```\n\n## About the plugin:\n\nYou can find the plugin at [xPMo/zsh-ls-colors](https://github.com/xPMo/zsh-ls-colors/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxpmo%2Fzsh-ls-colors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxpmo%2Fzsh-ls-colors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxpmo%2Fzsh-ls-colors/lists"}