{"id":20162555,"url":"https://github.com/zdharma-continuum/zredis","last_synced_at":"2026-05-31T21:31:42.200Z","repository":{"id":103427470,"uuid":"425226076","full_name":"zdharma-continuum/zredis","owner":"zdharma-continuum","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-16T04:43:30.000Z","size":1044,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-08T00:09:23.221Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zdharma-continuum.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-11-06T11:25:45.000Z","updated_at":"2025-03-22T02:06:41.000Z","dependencies_parsed_at":"2024-01-03T04:29:57.846Z","dependency_job_id":null,"html_url":"https://github.com/zdharma-continuum/zredis","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/zdharma-continuum/zredis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzredis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzredis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzredis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzredis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zdharma-continuum","download_url":"https://codeload.github.com/zdharma-continuum/zredis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzredis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33750474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-14T00:25:41.207Z","updated_at":"2026-05-31T21:31:42.152Z","avatar_url":"https://github.com/zdharma-continuum.png","language":"C","funding_links":[],"categories":["Plugins"],"sub_categories":["ZSH on Windows"],"readme":"[![Built with Spacemacs](https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg)](http://spacemacs.org)\n![ZSH 5.0.0](https://img.shields.io/badge/zsh-v5.0.0-orange.svg?style=flat-square)\n[![Zredis](https://img.shields.io/badge/zredis-0.93-green.svg)](https://github.com/zdharma/zredis/releases)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [Zredis](#zredis)\n  - [Rationale](#rationale)\n  - [Deleting From Database](#deleting-from-database)\n  - [Compiling modules](#compiling-modules)\n  - [Cache](#cache)\n  - [News](#news)\n  - [Mapping Of Redis Types To Zsh Data Structures](#mapping-of-redis-types-to-zsh-data-structures)\n    - [Database string keys -\u003e Zsh hash](#database-string-keys---zsh-hash)\n    - [Redis hash -\u003e Zsh hash](#redis-hash---zsh-hash)\n    - [Redis set -\u003e Zsh array](#redis-set---zsh-array)\n    - [Redis sorted set -\u003e Zsh hash](#redis-sorted-set---zsh-hash)\n    - [Redis list -\u003e Zsh array](#redis-list---zsh-array)\n    - [Redis string key -\u003e Zsh string](#redis-string-key---zsh-string)\n- [Installation](#installation)\n  - [Zplugin](#zplugin)\n  - [Antigen](#antigen)\n  - [Oh-My-Zsh](#oh-my-zsh)\n  - [Zgen](#zgen)\n- [Zredis Zstyles](#zredis-zstyles)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# Zredis\n\nZsh binary module written in C interfacing with `redis` database via `Zshell` `variables` mapped to `keys` or the whole\n`database`.\n\n```SystemVerilog\n# Create a hash `HASHSET' using the standard cli tool, holding 2 keys\n% redis-cli -n 3 hmset HASHSET key1 value1 \\\n                                key2 value2\n\n# Bind the shell variable `hset' onto the hash `HASHSET' in the database 127.0.0.1/3\n% ztie -d db/redis -a \"127.0.0.1/3/HASHSET\" hset\n\n% echo ${(kv)hset}    # (kv) – keys and values of Zsh hash\nkey1 value1 key2 value2\n% echo ${(k)hset}\nkey1 key2\n% echo $hset          # in Zsh when accesing a hash the values are output by default\nvalue1 value2\n\n% ztie -d db/redis -a \"127.0.0.1/3/LIST\" -L list lst # Lazy binding, will create list-key on write\n                                                     # -L {type}, obtains Redis type name like `zset',\n                                                     # `hash', `string', etc.\n% echo ${(t)lst}      # (t) – display type of Zsh variable\narray-special\n% lst=( ${(k)hset} )  # Copying hash keys into list\n% echo $lst\nkey1 key2\n% redis-cli -n 3 lrange LIST 0 -1   # Test the value of `LIST' using the standard cli tool\n1) \"key1\"\n2) \"key2\"\n```\n\n## Rationale\n\nBuilding commands for `redis-cli` quickly becomes inadequate. For example, if copying of one hash to another one is\nneeded, what `redis-cli` invocations are needed? With `zredis`, this task is simple:\n\n```zsh\n% ztie -r -d db/redis -a \"127.0.0.1/3/HASHSET1\" hset1 # -r - read-only\n% ztie -d db/redis -a \"127.0.0.1/3/HASHSET2\" hset2\n% echo ${(kv)hset2}\nother data\n% echo ${(kv)hset1}\nkey1 value1 key2 value2\n% hset2=( \"${(kv)hset1[@]}\" )\n% echo ${(kv)hset2}\nkey1 value1 key2 value2\n```\n\nThe `\"${(kv)hset1[@]}\"` construct guarantees that empty elements (keys or values) will be preserved, thanks to quoting\nand `@` operator. `(kv)` means keys and values, alternating.\n\nOr, for example, if one needs a large sorted set (`zset`), how to accomplish this with `redis-cli`? With `zredis`, one\ncan do:\n\n```zsh\n% redis-cli -n 3 zadd NEWZSET 1.0 a\n% ztie -d db/redis -a \"127.0.0.1/3/NEWZSET\" zset\n% echo ${(kv)zset}\na 1\n% count=0\n% for i in {a..z} {A..Z}; do (( count ++ )); zset[$i]=$count; done\n% echo ${(kv)zset}\na 1 b 2 c 3 d 4 e 5 f 6 g 7 h 8 i 9 j 10 k 11 l 12 m 13 n 14 o 15 p 16 q 17 r 18 s 19 t 20 u 21 v 22 w 23 x 24 y 25 z 26 A 27 B 28 C 29 D 30 E 31 F 32 G 33 H 34 I 35 J 36 K 37 L 38 M 39 N 40 O 41 P 42 Q 43 R 44 S 45 T 46 U 47 V 48 W 49 X 50 Y 51 Z 52\n% zrzset -h\nUsage: zrzset {tied-param-name}\nOutput: $reply array, to hold elements of the sorted set\n% zrzset zset\n% echo $reply\na b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z\n```\n\n## Deleting From Database\n\nUnsetting the first type of mapped variable (Zsh hash -\u003e whole database) doesn't cause a deletion from database. If\noption `-D` is given to `ztie` when binding to concrete key in database, then unsets, also caused by automatic Zsh\nscoping actions, cause the corresponding key to be deleted. `zuntie` never deletes from database.\n\nMore: in Redis, removing all elements from a set, list, etc. means the same as deletion. So you can delete all datatypes\nexcept string, by doing `variable=()`. For string you can unset key in whole-database mapped hash:\n`unset 'wholedb[key]'`.\n\n## Compiling modules\n\nThe Zsh modules provided by the plugin will build automatically (`hiredis` library is needed). You can start more than 1\nshell, only the first one will be compiling. If a developer commits a new timestamp to `module/RECOMPILE_REQUEST`, the\nmodule will recompile (don't worry, at startup, `mtime` is checked first, so check for recompilation is fast). I do this\nwhen I add tested features or fixes. You can recompile the modules yourself by invoking Zsh function `zredis_compile`.\n\n## Cache\n\nBy default, reads are cached. If a tied variable is read for the first time, then database is accessed. For the second\nread there's no database access. Writes aren't cached in any way.\n\nTo clear the cache, invoke:\n\n```zsh\nztclear my_string_var       # Also for types: list, set\nztclear my_hashset_var key  # Also for types: whole-db mapping, zset\n```\n\nTo disable the cache, pass `-z` (\"zero-cache\") option to ztie.\n\n## News\n\n- 2018-12-19\n\n  - The builtin `zrpush` can have the param-name argument skipped – if it's called for the second time, meaning that a\n    new special (but writeable) parameter has been set – `$zredis_last`. It holds the param-name used in the 1st call\n    and will be used in place of the `{pm-name}` argument. The short call is then to look like the following:\n    `zrpush {l|r} [ {val1} {val2} ... ]`.\n\n- 2018-12-18\n\n  - New builtin `zrpush {l|r} {pm-name} [ {val1} {val2} ... ]` that in an optimized manner pushes the given elements\n    `{val1} {val2}`, etc. onto the front or back (i.e. `l|r`, left or right, head or tail) of the list tied to param\n    `{pm-name}`.\n  - Hash-**set** operation (i.e. `hsh=( a b ...)`) has been greately optimized for over-internet tied hash parameters.\n\n- 2018-01-09\n\n  - New option to `ztie`: `-S`, which used in conjunction with `-L` (lazy binding) causes database connection to be\n    defered until first use of variable. Standard lazy binding means: key isn't required to exist.\n\n- 2018-01-08\n\n  - New option to `ztie`: `-D`, which causes mapped database key to be deleted on `unset` of the tied variable. Up to\n    this moment this behavior was the default.\n\n## Mapping Of Redis Types To Zsh Data Structures\n\n### Database string keys -\u003e Zsh hash\n\nRedis can store strings at given keys, using `SET` command. `Zredis` maps those to hash array (like Zsh `gdbm` module):\n\n```\n% redis-cli -n 4 SET key1 value1\n% redis-cli -n 4 SET key2 value2\n% ztie -d db/redis -a \"127.0.0.1/4\" redis\n% echo $zredis_tied\nredis\n% echo ${(kv)redis}\nkey1 value1 key2 value2\n```\n\n### Redis hash -\u003e Zsh hash\n\nBy appending `/NAME` to the `host-spec` (`-f` option), one can select single key of type `HASH` and map it to `Zsh`\nhash:\n\n```\n% redis-cli -n 4 hmset HASH key1 value1 key2 value2\n% ztie -d db/redis -a \"127.0.0.1/4/HASH\" hset\n% echo $zredis_tied\nhset\n% echo ${(kv)hset}\nkey1 value1 key2 value2\n% echo $hset[key2]\nvalue2\n% unset 'hset[key2]'\n% echo ${(kv)hset}\nkey1 value1\n```\n\n### Redis set -\u003e Zsh array\n\nCan clear single elements by assigning `()` to array element. Can overwrite whole set by assigning via `=( ... )` to\nset, and delete set from database by use of `unset`. Use `zuntie` to only detach variable from database without deleting\nany data.\n\n```\n% redis-cli -n 4 sadd SET value1 value2 value3 ''\n% ztie -d db/redis -a \"127.0.0.1/4/SET\" myset\n% echo ${myset[@]}\nvalue2 value3 value1\n% echo -E ${(qq)myset[@]}  # (qq) – quote with '', use to see empty elements\n'value2' 'value3' '' 'value1'\n% myset=( 1 2 3 )\n% myset[2]=()\n% redis-cli -n 4 smembers SET\n1) \"1\"\n3) \"3\"\n% unset myset\n% redis-cli -n 4 smembers SET\n(empty list or set)\n```\n\n### Redis sorted set -\u003e Zsh hash\n\nThis variant maps `zset` as hash - keys are set elements, values are ranks. `zrzset` call outputs elements sorted\naccording to the rank:\n\n```\n% redis-cli -n 4 zadd NEWZSET 1.0 a\n% ztie -d db/redis -a \"127.0.0.1/4/NEWZSET\" zset\n% echo ${(kv)zset}\na 1\n% zset[a]=2.5\n% zset[b]=1.5\n% zrzset zset\n% echo $reply\nb a\n```\n\n### Redis list -\u003e Zsh array\n\nThere is no analogue of `zrzset` call because `Zsh` array already has correct order:\n\n```zsh\n% redis-cli -n 4 rpush LIST value1 value2 value3\n% ztie -d db/redis -a \"127.0.0.1/4/LIST\" mylist\n% echo $mylist\nvalue1 value2 value3\n% mylist=( 1 2 3 )\n% mylist[2]=()\n% redis-cli -n 4 lrange LIST 0 -1\n1) \"1\"\n3) \"3\"\n% zuntie mylist\n% redis-cli -n 4 lrange LIST 0 -1\n1) \"1\"\n3) \"3\"\n```\n\n### Redis string key -\u003e Zsh string\n\nSingle keys in main Redis storage are bound to `Zsh` string variables:\n\n```zsh\n% redis-cli -n 4 KEYS \"*\"\n1) \"key1\"\n2) \"SET\"\n3) \"LIST\"\n4) \"HASH\"\n5) \"NEWZSET\"\n6) \"key2\"\n% ztie -d db/redis -a \"127.0.0.1/4/key1\" key1\n% echo $key1\nvalue1\n% key1=value2\n% echo $key1\nvalue2\n% redis-cli -n 4 get key1\n\"value2\"\n```\n\n# Installation\n\n**The plugin is \"standalone\"**, which means that only sourcing it is needed. So to install, unpack `zredis` somewhere\nand add\n\n```SystemVerilog\nsource {where-zredis-is}/zredis.plugin.zsh\n```\n\nto `zshrc`.\n\nIf using a plugin manager, then `Zplugin` is recommended, but you can use any other too, and also install with\n`Oh My Zsh` (by copying directory to `~/.oh-my-zsh/custom/plugins`).\n\n### [Zplugin](https://github.com/zdharma-continuum/zinit)\n\nAdd `zplugin light zdharma/zredis` to your `.zshrc` file. Zplugin will handle cloning the plugin for you automatically\nthe next time you start zsh. To update issue `zplugin update zdharma/zredis`.\n\n### Antigen\n\nAdd `antigen bundle zdharma/zredis` to your `.zshrc` file. Antigen will handle cloning the plugin for you automatically\nthe next time you start zsh.\n\n### Oh-My-Zsh\n\n1. `cd ~/.oh-my-zsh/custom/plugins`\n1. `git clone git@github.com:zdharma/zredis.git`\n1. Add `zredis` to your plugin list\n\n### Zgen\n\nAdd `zgen load zdharma/zredis` to your .zshrc file in the same place you're doing your other `zgen load` calls in.\n\n# Zredis Zstyles\n\nThe values being set are the defaults. Change the values before loading `zredis` plugin.\n\n```zsh\nzstyle \":plugin:zredis\" cppflags \"-I/usr/local/include\"  # Additional include directory\nzstyle \":plugin:zredis\" cflags \"-Wall -O2 -g\"            # Additional CFLAGS\nzstyle \":plugin:zredis\" ldflags \"-L/usr/local/lib\"       # Additional library directory\nzstyle \":plugin:zredis\" configure_opts \"\"                # Additional ./configure options\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzdharma-continuum%2Fzredis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzdharma-continuum%2Fzredis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzdharma-continuum%2Fzredis/lists"}