Merging upstream version 1.13.0.

Signed-off-by: Daniel Baumann <daniel@debian.org>

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.12.1
+current_version = 1.13.0
 commit = True
 tag = True
 

.github/workflows/release.yaml

@@ -89,7 +89,7 @@ jobs:
         run: |
           python3 -m venv venv
           . venv/bin/activate
-          pip install pip==21.1
+          pip install pip
           pip install poetry
           poetry install
           python -c "import sys; print(sys.version)"

.github/workflows/test-binary-build.yaml

@@ -36,7 +36,7 @@ jobs:
         run: |
           python3 -m venv venv
           . venv/bin/activate
-          pip install pip==21.1
+          pip install pip
           pip install poetry
           poetry install
           python -c "import sys; print(sys.version)"

.github/workflows/test.yaml

@@ -11,8 +11,8 @@ jobs:
     name: Pytest
     strategy:
       matrix:
-        os: [ubuntu-latest]
+        os: ["ubuntu-20.04"]
-        python: ['3.6', '3.7', '3.8', '3.9', '3.10']
+        python: ["3.7", "3.8", "3.9", "3.10", "3.11.1"]
         redis: [5, 6, 7]
     runs-on: ${{ matrix.os }}
 
@@ -25,21 +25,23 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python }}
-          architecture: 'x64'
+          architecture: "x64"
       - name: Cache venv
         uses: actions/cache@v2
         with:
           path: venv
           # Look to see if there is a cache hit for the corresponding requirements file
-          key: poetryenv-${{ matrix.os }}-${{ matrix.python }}-${{ hashFiles('poetry.lock') }}
+          key:
+            poetryenv-${{ matrix.os }}-${{ matrix.python }}-${{
+            hashFiles('poetry.lock') }}
       - name: Install Dependencies
         run: |
           python3 -m venv venv
           . venv/bin/activate
-          pip install -U pip==21.1 setuptools
+          pip install -U pip setuptools
           pip install poetry
           poetry install
           python -c "import sys; print(sys.version)"
@@ -58,12 +60,12 @@ jobs:
       - uses: actions/checkout@v2
       - uses: codespell-project/actions-codespell@master
         with:
-          ignore_words_list: fo,ists,oll,optin,ot,smove,tre,whe
+          ignore_words_list: fo,ists,oll,optin,ot,smove,tre,whe,EXAT,exat
-          exclude_file: docs/assets/demo.svg
+          skip: ./docs/assets/demo.svg,./iredis/data/commands.json,./iredis/data/commands/*,./tests/unittests/*
-      - uses: actions/setup-python@v1
+      - uses: actions/setup-python@v4
         with:
           python-version: 3.7
-          architecture: 'x64'
+          architecture: "x64"
       - name: Cache venv
         uses: actions/cache@v2
         with:

CHANGELOG.md

@@ -1,5 +1,18 @@
 ## UPCOMING
 
+## 1.3
+
+- Dependency: Drop Python 3.6 support.
+- Bugfix: fix some typos.
+
+### 1.12.2
+
+- Feature: IRedis now honors the `ssl_cert_reqs` strategy, either specifying it via
+  command line (`--verify-ssl=<none|optional|required>`) or as an url parameter (`ssl_cert_reqs`)
+  when the connection is secured via tls (`rediss://`). (authored by [torrefatto])
+
+### 1.12.1
+
 - Feature: support new command: `HRANDFIELD`.
 - Bugfix: all tests pass on redis:7 now.
 - Feature: IRedis now accept `username` for auth, redis server version under 6
@@ -294,3 +307,4 @@
 [sid-maddy]: https://github.com/sid-maddy
 [tssujt]: https://github.com/tssujt
 [aymericbeaumet]: https://github.com/aymericbeaumet
+[torrefatto]: https://github.com/torrefatto

README.md

@@ -126,7 +126,7 @@ supports similar options like redis-cli, like `-h` for redis-server's host and
 ```
 $ iredis --help
 
-Usage:  [OPTIONS] [CMD]...
+Usage: iredis [OPTIONS] [CMD]...
 
   IRedis: Interactive Redis
 
@@ -143,39 +143,60 @@ Usage:  [OPTIONS] [CMD]...
   settings.
 
 Options:
-  -h TEXT                   Server hostname (default: 127.0.0.1).
+  -h TEXT                         Server hostname (default: 127.0.0.1).
-  -p TEXT                   Server port (default: 6379).
+  -p TEXT                         Server port (default: 6379).
-  -s, --socket TEXT         Server socket (overrides hostname and port).
+  -s, --socket TEXT               Server socket (overrides hostname and port).
-  -n TEXT                   Database number.(overwrites dsn/url's db number)
+  -n INTEGER                      Database number.(overwrites dsn/url's db
-  -a, --password TEXT       Password to use when connecting to the server.
+                                  number)
-  --url TEXT                Use Redis URL to indicate connection(Can set with
-                            env `IREDIS_URL`), Example:
-                            redis://[[username]:[password]]@localhost:6379/0
-                            rediss://[[username]:[password]]@localhost:6379/0
-                            unix://[[username]:[password]]@/path/to/socket.soc
-                            k?db=0
 
-  -d, --dsn TEXT            Use DSN configured into the [alias_dsn] section of
+  -u, --username TEXT             User name used to auth, will be ignore for
-                            iredisrc file. (Can set with env `IREDIS_DSN`)
+                                  redis version < 6.
 
-  --newbie / --no-newbie    Show command hints and useful helps.
+  -a, --password TEXT             Password to use when connecting to the
-  --iredisrc TEXT           Config file for iredis, default is ~/.iredisrc.
+                                  server.
-  --decode TEXT             decode response, default is No decode, which will
-                            output all bytes literals.
 
-  --client_name TEXT        Assign a name to the current connection.
+  --url TEXT                      Use Redis URL to indicate connection(Can set
-  --raw / --no-raw          Use raw formatting for replies (default when
+                                  with env `IREDIS_URL`), Example:     redis:/
-                            STDOUT is not a tty). However, you can use --no-
+                                  /[[username]:[password]]@localhost:6379/0
-                            raw to force formatted output even when STDOUT is
+                                  rediss://[[username]:[password]]@localhost:6
-                            not a tty.
+                                  379/0     unix://[[username]:[password]]@/pa
+                                  th/to/socket.sock?db=0
 
-  --rainbow / --no-rainbow  Display colorful prompt.
+  -d, --dsn TEXT                  Use DSN configured into the [alias_dsn]
-  --shell / --no-shell      Allow to run shell commands, default to True.
+                                  section of iredisrc file. (Can set with env
-  --pager / --no-pager      Using pager when output is too tall for your
+                                  `IREDIS_DSN`)
-                            window, default to True.
+
+  --newbie / --no-newbie          Show command hints and useful helps.
+  --iredisrc TEXT                 Config file for iredis, default is
+                                  ~/.iredisrc.
+
+  --decode TEXT                   decode response, default is No decode, which
+                                  will output all bytes literals.
+
+  --client_name TEXT              Assign a name to the current connection.
+  --raw / --no-raw                Use raw formatting for replies (default when
+                                  STDOUT is not a tty). However, you can use
+                                  --no-raw to force formatted output even when
+                                  STDOUT is not a tty.
+
+  --rainbow / --no-rainbow        Display colorful prompt.
+  --shell / --no-shell            Allow to run shell commands, default to
+                                  True.
+
+  --pager / --no-pager            Using pager when output is too tall for your
+                                  window, default to True.
+
+  --verify-ssl [none|optional|required]
+                                  Set the TLS certificate verification
+                                  strategy
+
+  --prompt TEXT                   Prompt format (supported interpolations:
+                                  {client_name}, {db}, {host}, {path}, {port},
+                                  {username}, {client_addr}, {client_id}).
+
+  --version                       Show the version and exit.
+  --help                          Show this message and exit.
 
-  --version                 Show the version and exit.
-  --help                    Show this message and exit.
 ```
 
 ### Using DSN
@@ -215,6 +236,13 @@ interpolations:
 - `{client_addr}`
 - `{client_id}`
 
+The `--prompt` utilize
+[Python String format engine](https://docs.python.org/3/library/string.html#formatstrings),
+so as long as it is a valid string formatter, it will work( anything that
+`"<your prompt>".format(...)` accepts). For example, you can limit your Redis
+server host name's length to 5 by setting `--prompt` to
+`iredis --prompt '{host:.5s}'`.
+
 ### Configuration
 
 IRedis supports config files. Command-line options will always take precedence

iredis/__init__.py

@@ -1 +1 @@
-__version__ = "1.12.1"
+__version__ = "1.13.0"

iredis/client.py

@@ -20,7 +20,6 @@ from redis.exceptions import (
     ResponseError,
 )
 
-
 from . import markdown, renders
 from .data import commands as commands_data
 from .commands import (
@@ -64,6 +63,7 @@ class Client:
         username=None,
         client_name=None,
         prompt=None,
+        verify_ssl=None,
     ):
         self.host = host
         self.port = port
@@ -81,6 +81,8 @@ class Client:
         if prompt:
             self.prompt = prompt
 
+        self.verify_ssl = verify_ssl or "required"
+
         self.client_id = None
         self.client_addr = None
 
@@ -125,6 +127,7 @@ class Client:
             self.path,
             self.scheme,
             self.username,
+            self.verify_ssl,
             client_name=self.client_name,
         )
 
@@ -137,6 +140,7 @@ class Client:
         path=None,
         scheme="redis",
         username=None,
+        verify_ssl=None,
         client_name=None,
     ):
         if scheme in ("redis", "rediss"):
@@ -154,6 +158,7 @@ class Client:
                 connection_kwargs["username"] = username
 
             if scheme == "rediss":
+                connection_kwargs["ssl_cert_reqs"] = verify_ssl
                 connection_class = SSLConnection
             else:
                 connection_class = Connection
@@ -286,6 +291,9 @@ class Client:
                 last_error = e
                 retry_times -= 1
                 need_refresh_connection = True
+            except redis.exceptions.ExecAbortError:
+                config.transaction = False
+                raise
             except ResponseError as e:
                 response_message = str(e)
                 if response_message.startswith("MOVED"):
@@ -294,9 +302,6 @@ class Client:
                     )
                 raise e
 
-            except redis.exceptions.ExecAbortError:
-                config.transaction = False
-                raise
             except KeyboardInterrupt:
                 logger.warning("received KeyboardInterrupt... rebuild connection...")
                 connection.disconnect()
@@ -308,7 +313,8 @@ class Client:
                 return None
             else:
                 return response
-        raise last_error
+        if last_error:
+            raise last_error
 
     def reissue_with_redirect(self, response, *args, **kwargs):
         """
@@ -318,13 +324,21 @@ class Client:
         This feature is not supported for unix socket connection.
         """
         # Redis Cluster only supports database zero.
-        _, slot, ip_port = response.split(" ")
+        _, _, ip_port = response.split(" ")
         ip, port = ip_port.split(":")
         port = int(port)
 
         print(response, file=sys.stderr)
 
-        connection = self.create_connection(ip, port)
+        connection = self.create_connection(
+            ip,
+            port,
+            username=self.username,
+            password=self.password,
+            path=self.path,
+            scheme=self.scheme,
+            client_name=self.client_name,
+        )
         # if user sets dsn for dest node
         # use username and password from dsn settings
         if config.alias_dsn:

iredis/config.py

@@ -8,7 +8,6 @@ from . import data as project_data
 # TODO verbose logger to print to stdout
 logger = logging.getLogger(__name__)
 
-
 system_config_file = "/etc/iredisrc"
 pwd_config_file = os.path.join(os.getcwd(), ".iredisrc")
 
@@ -40,6 +39,7 @@ class Config:
         self.shell = None
         self.enable_pager = None
         self.pager = None
+        self.verify_ssl = None
 
         self.warning = True
 

iredis/data/commands/_index.md

@@ -0,0 +1,4 @@
+---
+title: "Redis Commands"
+linkTitle: "Commands"
+---

iredis/data/commands/acl-cat.md

@@ -1,6 +1,6 @@
-The command shows the available ACL categories if called without arguments. If a
+The command shows the available ACL categories if called without arguments.
-category name is given, the command shows all the Redis commands in the
+If a category name is given, the command shows all the Redis commands in
-specified category.
+the specified category.
 
 ACL categories are very useful in order to create ACL rules that include or
 exclude a large set of commands at once, without specifying every single
@@ -10,8 +10,8 @@ stability:
 
     ACL SETUSER karin on +@all -@dangerous
 
-We first add all the commands to the set of commands that `karin` is able to
+We first add all the commands to the set of commands that `karin` is able
-execute, but then we remove all the dangerous commands.
+to execute, but then we remove all the dangerous commands.
 
 Checking for all the available categories is as simple as:
 
@@ -79,6 +79,4 @@ Then we may want to know what commands are part of a given category:
 
 @return
 
-@array-reply: a list of ACL categories or a list of commands inside a given
+@array-reply: a list of ACL categories or a list of commands inside a given category. The command may return an error if an invalid category name is given as argument.
-category. The command may return an error if an invalid category name is given
-as argument.

iredis/data/commands/acl-deluser.md

@@ -1,13 +1,12 @@
 Delete all the specified ACL users and terminate all the connections that are
 authenticated with such users. Note: the special `default` user cannot be
-removed from the system, this is the default user that every new connection is
+removed from the system, this is the default user that every new connection
-authenticated with. The list of users may include usernames that do not exist,
+is authenticated with. The list of users may include usernames that do not
-in such case no operation is performed for the non existing users.
+exist, in such case no operation is performed for the non existing users.
 
 @return
 
-@integer-reply: The number of users that were deleted. This number will not
+@integer-reply: The number of users that were deleted. This number will not always match the number of arguments since certain users may not exist.
-always match the number of arguments since certain users may not exist.
 
 @examples
 

iredis/data/commands/acl-dryrun.md

@@ -0,0 +1,18 @@
+Simulate the execution of a given command by a given user.
+This command can be used to test the permissions of a given user without having to enable the user or cause the side effects of running the command.
+
+@return
+
+@simple-string-reply: `OK` on success.
+@bulk-string-reply: An error describing why the user can't execute the command.
+
+@examples
+
+```
+> ACL SETUSER VIRGINIA +SET ~*
+"OK"
+> ACL DRYRUN VIRGINIA SET foo bar
+"OK"
+> ACL DRYRUN VIRGINIA GET foo bar
+"This user has no permissions to run the 'GET' command"
+```

iredis/data/commands/acl-genpass.md

@@ -1,33 +1,33 @@
 ACL users need a solid password in order to authenticate to the server without
-security risks. Such password does not need to be remembered by humans, but only
+security risks. Such password does not need to be remembered by humans, but
-by computers, so it can be very long and strong (unguessable by an external
+only by computers, so it can be very long and strong (unguessable by an
-attacker). The `ACL GENPASS` command generates a password starting from
+external attacker). The `ACL GENPASS` command generates a password starting
-/dev/urandom if available, otherwise (in systems without /dev/urandom) it uses a
+from /dev/urandom if available, otherwise (in systems without /dev/urandom) it
-weaker system that is likely still better than picking a weak password by hand.
+uses a weaker system that is likely still better than picking a weak password
+by hand.
 
-By default (if /dev/urandom is available) the password is strong and can be used
+By default (if /dev/urandom is available) the password is strong and
-for other uses in the context of a Redis application, for instance in order to
+can be used for other uses in the context of a Redis application, for
-create unique session identifiers or other kind of unguessable and not colliding
+instance in order to create unique session identifiers or other kind of
-IDs. The password generation is also very cheap because we don't really ask
+unguessable and not colliding IDs. The password generation is also very cheap
-/dev/urandom for bits at every execution. At startup Redis creates a seed using
+because we don't really ask /dev/urandom for bits at every execution. At
-/dev/urandom, then it will use SHA256 in counter mode, with
+startup Redis creates a seed using /dev/urandom, then it will use SHA256
-HMAC-SHA256(seed,counter) as primitive, in order to create more random bytes as
+in counter mode, with HMAC-SHA256(seed,counter) as primitive, in order to
-needed. This means that the application developer should be feel free to abuse
+create more random bytes as needed. This means that the application developer
-`ACL GENPASS` to create as many secure pseudorandom strings as needed.
+should be feel free to abuse `ACL GENPASS` to create as many secure
+pseudorandom strings as needed.
 
-The command output is an hexadecimal representation of a binary string. By
+The command output is a hexadecimal representation of a binary string.
-default it emits 256 bits (so 64 hex characters). The user can provide an
+By default it emits 256 bits (so 64 hex characters). The user can provide
-argument in form of number of bits to emit from 1 to 1024 to change the output
+an argument in form of number of bits to emit from 1 to 1024 to change
-length. Note that the number of bits provided is always rounded to the next
+the output length. Note that the number of bits provided is always
-multiple of 4. So for instance asking for just 1 bit password will result in 4
+rounded to the next multiple of 4. So for instance asking for just 1
-bits to be emitted, in the form of a single hex character.
+bit password will result in 4 bits to be emitted, in the form of a single
+hex character.
 
 @return
 
-@bulk-string-reply: by default 64 bytes string representing 256 bits of
+@bulk-string-reply: by default 64 bytes string representing 256 bits of pseudorandom data. Otherwise if an argument if needed, the output string length is the number of specified bits (rounded to the next multiple of 4) divided by 4.
-pseudorandom data. Otherwise if an argument if needed, the output string length
-is the number of specified bits (rounded to the next multiple of 4) divided
-by 4.
 
 @examples
 

iredis/data/commands/acl-getuser.md

@@ -1,34 +1,43 @@
 The command returns all the rules defined for an existing ACL user.
 
-Specifically, it lists the user's ACL flags, password hashes and key name
+Specifically, it lists the user's ACL flags, password hashes, commands, key patterns, channel patterns (Added in version 6.2) and selectors (Added in version 7.0).
-patterns. Note that command rules are returned as a string in the same format
+Additional information may be returned in the future if more metadata is added to the user.
-used with the `ACL SETUSER` command. This description of command rules reflects
+
-the user's effective permissions, so while it may not be identical to the set of
+Command rules are always returned in the same format as the one used in the `ACL SETUSER` command.
-rules used to configure the user, it is still functionally identical.
+Before version 7.0, keys and channels were returned as an array of patterns, however in version 7.0 later they are now also returned in same format as the one used in the `ACL SETUSER` command.
+Note: This description of command rules reflects the user's effective permissions, so while it may not be identical to the set of rules used to configure the user, it is still functionally identical.
+
+Selectors are listed in the order they were applied to the user, and include information about commands, key patterns, and channel patterns.
 
 @array-reply: a list of ACL rule definitions for the user.
 
-@history
+If `user` does not exist a @nil-reply is returned.
-
-- `>= 6.2`: Added Pub/Sub channel patterns.
 
 @examples
 
-Here's the default configuration for the default user:
+Here's an example configuration for a user
 
 ```
-> ACL GETUSER default
+> ACL SETUSER sample on nopass +GET allkeys &* (+SET ~key2)
+"OK"
+> ACL GETUSER sample
 1) "flags"
 2) 1) "on"
    2) "allkeys"
-   3) "allcommands"
+   3) "nopass"
-   4) "nopass"
 3) "passwords"
 4) (empty array)
 5) "commands"
 6) "+@all"
 7) "keys"
-8) 1) "*"
+8) "~*"
 9) "channels"
-10) 1) "*"
+10) "&*"
+11) "selectors"
+12) 1) 1) "commands"
+       6) "+SET"
+       7) "keys"
+       8) "~key2"
+       9) "channels"
+       10) "&*"
 ```

iredis/data/commands/acl-help.md

@@ -1,5 +1,4 @@
-The `ACL HELP` command returns a helpful text describing the different
+The `ACL HELP` command returns a helpful text describing the different subcommands.
-subcommands.
 
 @return
 

iredis/data/commands/acl-list.md

@@ -1,8 +1,8 @@
-The command shows the currently active ACL rules in the Redis server. Each line
+The command shows the currently active ACL rules in the Redis server. Each
-in the returned array defines a different user, and the format is the same used
+line in the returned array defines a different user, and the format is the
-in the redis.conf file or the external ACL file, so you can cut and paste what
+same used in the redis.conf file or the external ACL file, so you can
-is returned by the ACL LIST command directly inside a configuration file if you
+cut and paste what is returned by the ACL LIST command directly inside a
-wish (but make sure to check `ACL SAVE`).
+configuration file if you wish (but make sure to check `ACL SAVE`).
 
 @return
 

iredis/data/commands/acl-load.md

@@ -1,20 +1,16 @@
 When Redis is configured to use an ACL file (with the `aclfile` configuration
-option), this command will reload the ACLs from the file, replacing all the
+option), this command will reload the ACLs from the file, replacing all
-current ACL rules with the ones defined in the file. The command makes sure to
+the current ACL rules with the ones defined in the file. The command makes
-have an _all or nothing_ behavior, that is:
+sure to have an *all or nothing* behavior, that is:
 
-- If every line in the file is valid, all the ACLs are loaded.
+* If every line in the file is valid, all the ACLs are loaded.
-- If one or more line in the file is not valid, nothing is loaded, and the old
+* If one or more line in the file is not valid, nothing is loaded, and the old ACL rules defined in the server memory continue to be used.
-  ACL rules defined in the server memory continue to be used.
 
 @return
 
 @simple-string-reply: `OK` on success.
 
-The command may fail with an error for several reasons: if the file is not
+The command may fail with an error for several reasons: if the file is not readable, if there is an error inside the file, and in such case the error will be reported to the user in the error. Finally the command will fail if the server is not configured to use an external ACL file.
-readable, if there is an error inside the file, and in such case the error will
-be reported to the user in the error. Finally the command will fail if the
-server is not configured to use an external ACL file.
 
 @examples
 

iredis/data/commands/acl-log.md

@@ -4,9 +4,9 @@ The command shows a list of recent ACL security events:
 2. Commands denied because against the current ACL rules.
 3. Commands denied because accessing keys not allowed in the current ACL rules.
 
-The optional argument specifies how many entries to show. By default up to ten
+The optional argument specifies how many entries to show. By default
-failures are returned. The special `RESET` argument clears the log. Entries are
+up to ten failures are returned. The special `RESET` argument clears the log.
-displayed starting from the most recent.
+Entries are displayed starting from the most recent.
 
 @return
 

iredis/data/commands/acl-save.md

@@ -1,13 +1,11 @@
 When Redis is configured to use an ACL file (with the `aclfile` configuration
-option), this command will save the currently defined ACLs from the server
+option), this command will save the currently defined ACLs from the server memory to the ACL file.
-memory to the ACL file.
 
 @return
 
 @simple-string-reply: `OK` on success.
 
-The command may fail with an error for several reasons: if the file cannot be
+The command may fail with an error for several reasons: if the file cannot be written or if the server is not configured to use an external ACL file.
-written or if the server is not configured to use an external ACL file.
 
 @examples
 

iredis/data/commands/acl-setuser.md

@@ -1,109 +1,91 @@
-Create an ACL user with the specified rules or modify the rules of an existing
+Create an ACL user with the specified rules or modify the rules of an
-user. This is the main interface in order to manipulate Redis ACL users
+existing user. This is the main interface in order to manipulate Redis ACL
-interactively: if the username does not exist, the command creates the username
+users interactively: if the username does not exist, the command creates
-without any privilege, then reads from left to right all the rules provided as
+the username without any privilege, then reads from left to right all the
-successive arguments, setting the user ACL rules as specified.
+rules provided as successive arguments, setting the user ACL rules as specified.
 
-If the user already exists, the provided ACL rules are simply applied _in
+If the user already exists, the provided ACL rules are simply applied
-addition_ to the rules already set. For example:
+*in addition* to the rules already set. For example:
 
     ACL SETUSER virginia on allkeys +set
 
-The above command will create a user called `virginia` that is active (the on
+The above command will create a user called `virginia` that is active
-rule), can access any key (allkeys rule), and can call the set command (+set
+(the on rule), can access any key (allkeys rule), and can call the
-rule). Then another SETUSER call can modify the user rules:
+set command (+set rule). Then another SETUSER call can modify the user rules:
 
     ACL SETUSER virginia +get
 
-The above rule will not apply the new rule to the user virginia, so other than
+The above rule will not apply the new rule to the user virginia, so other than `SET`, the user virginia will now be able to also use the `GET` command.
-`SET`, the user virginia will now be able to also use the `GET` command.
 
-When we want to be sure to define an user from scratch, without caring if it had
+Starting from Redis 7.0, ACL rules can also be grouped into multiple distinct sets of rules, called selectors.
-previously defined rules associated, we can use the special rule `reset` as
+Selectors are added by wrapping the rules in parentheses and providing them just like any other rule.
-first rule, in order to flush all the other existing rules:
+In order to execute a command, either the root permissions (rules defined outside of parenthesis) or any of the selectors (rules defined inside parenthesis) must match the given command.
+For example:
+
+    ACL SETUSER virginia on +GET allkeys (+SET ~app1*)
+
+This sets a user with two sets of permission, one defined on the user and one defined with a selector.
+The root user permissions only allows executing the get command, but can be executed on any keys.
+The selector then grants a secondary set of permissions: access to the `SET` command to be executed on any key that starts with "app1".
+Using multiple selectors allows you to grant permissions that are different depending on what keys are being accessed.
+
+When we want to be sure to define a user from scratch, without caring if
+it had previously defined rules associated, we can use the special rule
+`reset` as first rule, in order to flush all the other existing rules:
 
     ACL SETUSER antirez reset [... other rules ...]
 
-After resetting an user, it returns back to the status it has when it was just
+After resetting a user, it returns back to the status it has when it
-created: non active (off rule), can't execute any command, can't access any key:
+was just created: non active (off rule), can't execute any command, can't
+access any key:
 
     > ACL SETUSER antirez reset
     +OK
     > ACL LIST
     1) "user antirez off -@all"
 
-ACL rules are either words like "on", "off", "reset", "allkeys", or are special
+ACL rules are either words like "on", "off", "reset", "allkeys", or are
-rules that start with a special character, and are followed by another string
+special rules that start with a special character, and are followed by
-(without any space in between), like "+SET".
+another string (without any space in between), like "+SET".
 
-The following documentation is a reference manual about the capabilities of this
+The following documentation is a reference manual about the capabilities of this command, however our [ACL tutorial](/topics/acl) may be a more gentle introduction to how the ACL system works in general.
-command, however our [ACL tutorial](/topics/acl) may be a more gentle
-introduction to how the ACL system works in general.
 
 ## List of rules
 
+Redis ACL rules are split into two categories: rules that define command permissions, "Command rules", and rules that define user state, "User management rules".
 This is a list of all the supported Redis ACL rules:
 
-- `on`: set the user as active, it will be possible to authenticate as this user
+### Command rules
-  using `AUTH <username> <password>`.
+
-- `off`: set user as not active, it will be impossible to log as this user.
+* `~<pattern>`: add the specified key pattern (glob style pattern, like in the `KEYS` command), to the list of key patterns accessible by the user. This grants both read and write permissions to keys that match the pattern. You can add multiple key patterns to the same user. Example: `~objects:*`
-  Please note that if a user gets disabled (set to off) after there are
+* `%R~<pattern>`: (Available in Redis 7.0 and later) Add the specified read key pattern. This behaves similar to the regular key pattern but only grants permission to read from keys that match the given pattern. See [key permissions](/topics/acl#key-permissions) for more information.
-  connections already authenticated with such a user, the connections will
+* `%W~<pattern>`: (Available in Redis 7.0 and later) Add the specified write key pattern. This behaves similar to the regular key pattern but only grants permission to write to keys that match the given pattern. See [key permissions](/topics/acl#key-permissions) for more information.
-  continue to work as expected. To also kill the old connections you can use
+* `%RW~<pattern>`: (Available in Redis 7.0 and later) Alias for `~<pattern>`.
-  `CLIENT KILL` with the user option. An alternative is to delete the user with
+* `allkeys`: alias for `~*`, it allows the user to access all the keys.
-  `ACL DELUSER`, that will result in all the connections authenticated as the
+* `resetkeys`: removes all the key patterns from the list of key patterns the user can access.
-  deleted user to be disconnected.
+* `&<pattern>`: (Available in Redis 6.2 and later) add the specified glob style pattern to the list of Pub/Sub channel patterns accessible by the user. You can add multiple channel patterns to the same user. Example: `&chatroom:*`
-- `~<pattern>`: add the specified key pattern (glob style pattern, like in the
+* `allchannels`: alias for `&*`, it allows the user to access all Pub/Sub channels.
-  `KEYS` command), to the list of key patterns accessible by the user. You can
+* `resetchannels`: removes all channel patterns from the list of Pub/Sub channel patterns the user can access.
-  add multiple key patterns to the same user. Example: `~objects:*`
+* `+<command>`: Add the command to the list of commands the user can call. Can be used with `|` for allowing subcommands (e.g "+config|get").
-- `allkeys`: alias for `~*`, it allows the user to access all the keys.
+* `+@<category>`: add all the commands in the specified category to the list of commands the user is able to execute. Example: `+@string` (adds all the string commands). For a list of categories check the `ACL CAT` command.
-- `resetkeys`: removes all the key patterns from the list of key patterns the
+* `+<command>|first-arg`: Allow a specific first argument of an otherwise disabled command. It is only supported on commands with no sub-commands, and is not allowed as negative form like -SELECT|1, only additive starting with "+". This feature is deprecated and may be removed in the future.
-  user can access.
+* `allcommands`: alias of `+@all`. Adds all the commands there are in the server, including *future commands* loaded via module, to be executed by this user.
-- `&<pattern>`: add the specified glob style pattern to the list of Pub/Sub
+* `-<command>`: Remove the command to the list of commands the user can call. Starting Redis 7.0, it can be used with `|` for blocking subcommands (e.g "-config|set").
-  channel patterns accessible by the user. You can add multiple channel patterns
+* `-@<category>`: Like `+@<category>` but removes all the commands in the category instead of adding them.
-  to the same user. Example: `&chatroom:*`
+* `nocommands`: alias for `-@all`. Removes all the commands, the user will no longer be able to execute anything.
-- `allchannels`: alias for `&*`, it allows the user to access all Pub/Sub
+
-  channels.
+### User management rules
-- `resetchannels`: removes all channel patterns from the list of Pub/Sub channel
+
-  patterns the user can access.
+* `on`: set the user as active, it will be possible to authenticate as this user using `AUTH <username> <password>`.
-- `+<command>`: add this command to the list of the commands the user can call.
+* `off`: set user as not active, it will be impossible to log as this user. Please note that if a user gets disabled (set to off) after there are connections already authenticated with such a user, the connections will continue to work as expected. To also kill the old connections you can use `CLIENT KILL` with the user option. An alternative is to delete the user with `ACL DELUSER`, that will result in all the connections authenticated as the deleted user to be disconnected.
-  Example: `+zadd`.
+* `nopass`: the user is set as a "no password" user. It means that it will be possible to authenticate as such user with any password. By default, the `default` special user is set as "nopass". The `nopass` rule will also reset all the configured passwords for the user.
-- `+@<category>`: add all the commands in the specified category to the list of
+* `>password`: Add the specified clear text password as a hashed password in the list of the users passwords. Every user can have many active passwords, so that password rotation will be simpler. The specified password is not stored as clear text inside the server. Example: `>mypassword`.
-  commands the user is able to execute. Example: `+@string` (adds all the string
+* `#<hashedpassword>`: Add the specified hashed password to the list of user passwords. A Redis hashed password is hashed with SHA256 and translated into a hexadecimal string. Example: `#c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2`.
-  commands). For a list of categories check the `ACL CAT` command.
+* `<password`: Like `>password` but removes the password instead of adding it.
-- `+<command>|<subcommand>`: add the specified command to the list of the
+* `!<hashedpassword>`: Like `#<hashedpassword>` but removes the password instead of adding it.
-  commands the user can execute, but only for the specified subcommand. Example:
+* `(<rule list>)`: (Available in Redis 7.0 and later) Create a new selector to match rules against. Selectors are evaluated after the user permissions, and are evaluated according to the order they are defined. If a command matches either the user permissions or any selector, it is allowed. See [selectors](/topics/acl#selectors) for more information.
-  `+config|get`. Generates an error if the specified command is already allowed
+* `clearselectors`: (Available in Redis 7.0 and later) Delete all of the selectors attached to the user.
-  in its full version for the specified user. Note: there is no symmetrical
+* `reset`: Remove any capability from the user. It is set to off, without passwords, unable to execute any command, unable to access any key.
-  command to remove subcommands, you need to remove the whole command and re-add
-  the subcommands you want to allow. This is much safer than removing
-  subcommands, in the future Redis may add new dangerous subcommands, so
-  configuring by subtraction is not good.
-- `allcommands`: alias of `+@all`. Adds all the commands there are in the
-  server, including _future commands_ loaded via module, to be executed by this
-  user.
-- `-<command>`. Like `+<command>` but removes the command instead of adding it.
-- `-@<category>`: Like `+@<category>` but removes all the commands in the
-  category instead of adding them.
-- `nocommands`: alias for `-@all`. Removes all the commands, the user will no
-  longer be able to execute anything.
-- `nopass`: the user is set as a "no password" user. It means that it will be
-  possible to authenticate as such user with any password. By default, the
-  `default` special user is set as "nopass". The `nopass` rule will also reset
-  all the configured passwords for the user.
-- `>password`: Add the specified clear text password as an hashed password in
-  the list of the users passwords. Every user can have many active passwords, so
-  that password rotation will be simpler. The specified password is not stored
-  as clear text inside the server. Example: `>mypassword`.
-- `#<hashedpassword>`: Add the specified hashed password to the list of user
-  passwords. A Redis hashed password is hashed with SHA256 and translated into a
-  hexadecimal string. Example:
-  `#c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2`.
-- `<password`: Like `>password` but removes the password instead of adding it.
-- `!<hashedpassword>`: Like `#<hashedpassword>` but removes the password instead
-  of adding it.
-- reset: Remove any capability from the user. It is set to off, without
-  passwords, unable to execute any command, unable to access any key.
 
 @return
 
@@ -111,10 +93,6 @@ This is a list of all the supported Redis ACL rules:
 
 If the rules contain errors, the error is returned.
 
-@history
-
-- `>= 6.2`: Added Pub/Sub channel patterns.
-
 @examples
 
 ```

iredis/data/commands/acl-users.md

@@ -1,5 +1,5 @@
-The command shows a list of all the usernames of the currently configured users
+The command shows a list of all the usernames of the currently configured
-in the Redis ACL system.
+users in the Redis ACL system.
 
 @return
 

iredis/data/commands/acl-whoami.md

@@ -1,6 +1,6 @@
-Return the username the current connection is authenticated with. New
+Return the username the current connection is authenticated with.
-connections are authenticated with the "default" user. They can change user
+New connections are authenticated with the "default" user. They
-using `AUTH`.
+can change user using `AUTH`.
 
 @return
 

iredis/data/commands/acl.md

@@ -0,0 +1,3 @@
+This is a container command for [Access Control List](/docs/manual/security/acl/) commands.
+
+To see the list of available commands you can call `ACL HELP`.

iredis/data/commands/append.md

@@ -1,6 +1,7 @@
 If `key` already exists and is a string, this command appends the `value` at the
-end of the string. If `key` does not exist it is created and set as an empty
+end of the string.
-string, so `APPEND` will be similar to `SET` in this special case.
+If `key` does not exist it is created and set as an empty string, so `APPEND`
+will be similar to `SET` in this special case.
 
 @return
 
@@ -18,8 +19,8 @@ GET mykey
 ## Pattern: Time series
 
 The `APPEND` command can be used to create a very compact representation of a
-list of fixed-size samples, usually referred as _time series_. Every time a new
+list of fixed-size samples, usually referred as _time series_.
-sample arrives we can store it using the command
+Every time a new sample arrives we can store it using the command
 
 ```
 APPEND timeseries "fixed-size sample"
@@ -27,17 +28,17 @@ APPEND timeseries "fixed-size sample"
 
 Accessing individual elements in the time series is not hard:
 
-- `STRLEN` can be used in order to obtain the number of samples.
+* `STRLEN` can be used in order to obtain the number of samples.
-- `GETRANGE` allows for random access of elements. If our time series have
+* `GETRANGE` allows for random access of elements.
-  associated time information we can easily implement a binary search to get
+  If our time series have associated time information we can easily implement
-  range combining `GETRANGE` with the Lua scripting engine available in Redis
+  a binary search to get range combining `GETRANGE` with the Lua scripting
-  2.6.
+  engine available in Redis 2.6.
-- `SETRANGE` can be used to overwrite an existing time series.
+* `SETRANGE` can be used to overwrite an existing time series.
 
-The limitation of this pattern is that we are forced into an append-only mode of
+The limitation of this pattern is that we are forced into an append-only mode
-operation, there is no way to cut the time series to a given size easily because
+of operation, there is no way to cut the time series to a given size easily
-Redis currently lacks a command able to trim string objects. However the space
+because Redis currently lacks a command able to trim string objects.
-efficiency of time series stored in this way is remarkable.
+However the space efficiency of time series stored in this way is remarkable.
 
 Hint: it is possible to switch to a different key based on the current Unix
 time, in this way it is possible to have just a relatively small amount of

iredis/data/commands/asking.md

@@ -0,0 +1,10 @@
+When a cluster client receives an `-ASK` redirect, the `ASKING` command is sent to the target node followed by the command which was redirected.
+This is normally done automatically by cluster clients.
+
+If an `-ASK` redirect is received during a transaction, only one ASKING command needs to be sent to the target node before sending the complete transaction to the target node.
+
+See [ASK redirection in the Redis Cluster Specification](/topics/cluster-spec#ask-redirection) for details.
+
+@return
+
+@simple-string-reply: `OK`.

iredis/data/commands/auth.md

@@ -1,46 +1,36 @@
 The AUTH command authenticates the current connection in two cases:
 
 1. If the Redis server is password protected via the `requirepass` option.
-2. If a Redis 6.0 instance, or greater, is using the
+2. If a Redis 6.0 instance, or greater, is using the [Redis ACL system](/topics/acl).
-   [Redis ACL system](/topics/acl).
 
 Redis versions prior of Redis 6 were only able to understand the one argument
 version of the command:
 
     AUTH <password>
 
-This form just authenticates against the password set with `requirepass`. In
+This form just authenticates against the password set with `requirepass`.
-this configuration Redis will deny any command executed by the just connected
+In this configuration Redis will deny any command executed by the just
-clients, unless the connection gets authenticated via `AUTH`.
+connected clients, unless the connection gets authenticated via `AUTH`.
 
-If the password provided via AUTH matches the password in the configuration
+If the password provided via AUTH matches the password in the configuration file, the server replies with the `OK` status code and starts accepting commands.
-file, the server replies with the `OK` status code and starts accepting
+Otherwise, an error is returned and the clients needs to try a new password.
-commands. Otherwise, an error is returned and the clients needs to try a new
-password.
 
 When Redis ACLs are used, the command should be given in an extended way:
 
     AUTH <username> <password>
 
 In order to authenticate the current connection with one of the connections
-defined in the ACL list (see `ACL SETUSER`) and the official
+defined in the ACL list (see `ACL SETUSER`) and the official [ACL guide](/topics/acl) for more information.
-[ACL guide](/topics/acl) for more information.
 
-When ACLs are used, the single argument form of the command, where only the
+When ACLs are used, the single argument form of the command, where only the password is specified, assumes that the implicit username is "default".
-password is specified, assumes that the implicit username is "default".
-
-@history
-
-- `>= 6.0.0`: Added ACL style (username and password).
 
 ## Security notice
 
-Because of the high performance nature of Redis, it is possible to try a lot of
+Because of the high performance nature of Redis, it is possible to try
-passwords in parallel in very short time, so make sure to generate a strong and
+a lot of passwords in parallel in very short time, so make sure to generate a
-very long password so that this attack is infeasible. A good way to generate
+strong and very long password so that this attack is infeasible.
-strong passwords is via the `ACL GENPASS` command.
+A good way to generate strong passwords is via the `ACL GENPASS` command.
 
 @return
 
-@simple-string-reply or an error if the password, or username/password pair, is
+@simple-string-reply or an error if the password, or username/password pair, is invalid.
-invalid.

iredis/data/commands/bgrewriteaof.md

@@ -1,5 +1,6 @@
-Instruct Redis to start an [Append Only File][tpaof] rewrite process. The
+Instruct Redis to start an [Append Only File][tpaof] rewrite process.
-rewrite will create a small optimized version of the current Append Only File.
+The rewrite will create a small optimized version of the current Append Only
+File.
 
 [tpaof]: /topics/persistence#append-only-file
 
@@ -10,17 +11,10 @@ process doing persistence.
 
 Specifically:
 
-- If a Redis child is creating a snapshot on disk, the AOF rewrite is
+* If a Redis child is creating a snapshot on disk, the AOF rewrite is _scheduled_ but not started until the saving child producing the RDB file terminates. In this case the `BGREWRITEAOF` will still return a positive status reply, but with an appropriate message.  You can check if an AOF rewrite is scheduled looking at the `INFO` command as of Redis 2.6 or successive versions.
-  _scheduled_ but not started until the saving child producing the RDB file
+* If an AOF rewrite is already in progress the command returns an error and no
-  terminates. In this case the `BGREWRITEAOF` will still return an positive
-  status reply, but with an appropriate message. You can check if an AOF rewrite
-  is scheduled looking at the `INFO` command as of Redis 2.6 or successive
-  versions.
-- If an AOF rewrite is already in progress the command returns an error and no
   AOF rewrite will be scheduled for a later time.
-- If the AOF rewrite could start, but the attempt at starting it fails (for
+* If the AOF rewrite could start, but the attempt at starting it fails (for instance because of an error in creating the child process), an error is returned to the caller.
-  instance because of an error in creating the child process), an error is
-  returned to the caller.
 
 Since Redis 2.4 the AOF rewrite is automatically triggered by Redis, however the
 `BGREWRITEAOF` command can be used to trigger a rewrite at any time.
@@ -31,7 +25,6 @@ Please refer to the [persistence documentation][tp] for detailed information.
 
 @return
 
-@simple-string-reply: A simple string reply indicating that the rewriting
+@simple-string-reply: A simple string reply indicating that the rewriting started or is about to start ASAP, when the call is executed with success.
-started or is about to start ASAP, when the call is executed with success.
 
 The command may reply with an error in certain cases, as documented above.

iredis/data/commands/bgsave.md

@@ -1,7 +1,8 @@
 Save the DB in background.
 
-Normally the OK code is immediately returned. Redis forks, the parent continues
+Normally the OK code is immediately returned.
-to serve the clients, the child saves the DB on disk then exits.
+Redis forks, the parent continues to serve the clients, the child saves the DB
+on disk then exits.
 
 An error is returned if there is already a background save running or if there
 is another non-background-save process running, specifically an in-progress AOF
@@ -20,9 +21,4 @@ Please refer to the [persistence documentation][tp] for detailed information.
 
 @return
 
-@simple-string-reply: `Background saving started` if `BGSAVE` started correctly
+@simple-string-reply: `Background saving started` if `BGSAVE` started correctly or `Background saving scheduled` when used with the `SCHEDULE` subcommand. 
-or `Background saving scheduled` when used with the `SCHEDULE` subcommand.
-
-@history
-
-- `>= 3.2.2`: Added the `SCHEDULE` option.

iredis/data/commands/bitcount.md

@@ -1,8 +1,8 @@
 Count the number of set bits (population counting) in a string.
 
-By default all the bytes contained in the string are examined. It is possible to
+By default all the bytes contained in the string are examined.
-specify the counting operation only in an interval passing the additional
+It is possible to specify the counting operation only in an interval passing the
-arguments _start_ and _end_.
+additional arguments _start_ and _end_.
 
 Like for the `GETRANGE` command start and end can contain negative values in
 order to index bytes starting from the end of the string, where -1 is the last
@@ -10,6 +10,11 @@ byte, -2 is the penultimate, and so forth.
 
 Non-existent keys are treated as empty strings, so the command will return zero.
 
+By default, the additional arguments _start_ and _end_ specify a byte index.
+We can use an additional argument `BIT` to specify a bit index.
+So 0 is the first bit, 1 is the second bit, and so forth.
+For negative values, -1 is the last bit, -2 is the penultimate, and so forth.
+
 @return
 
 @integer-reply
@@ -23,44 +28,48 @@ SET mykey "foobar"
 BITCOUNT mykey
 BITCOUNT mykey 0 0
 BITCOUNT mykey 1 1
+BITCOUNT mykey 1 1 BYTE
+BITCOUNT mykey 5 30 BIT
 ```
 
 ## Pattern: real-time metrics using bitmaps
 
 Bitmaps are a very space-efficient representation of certain kinds of
-information. One example is a Web application that needs the history of user
+information.
-visits, so that for instance it is possible to determine what users are good
+One example is a Web application that needs the history of user visits, so that
-targets of beta features.
+for instance it is possible to determine what users are good targets of beta
+features.
 
 Using the `SETBIT` command this is trivial to accomplish, identifying every day
-with a small progressive integer. For instance day 0 is the first day the
+with a small progressive integer.
-application was put online, day 1 the next day, and so forth.
+For instance day 0 is the first day the application was put online, day 1 the
+next day, and so forth.
 
-Every time a user performs a page view, the application can register that in the
+Every time a user performs a page view, the application can register that in
-current day the user visited the web site using the `SETBIT` command setting the
+the current day the user visited the web site using the `SETBIT` command setting
-bit corresponding to the current day.
+the bit corresponding to the current day.
 
 Later it will be trivial to know the number of single days the user visited the
 web site simply calling the `BITCOUNT` command against the bitmap.
 
-A similar pattern where user IDs are used instead of days is described in the
+A similar pattern where user IDs are used instead of days is described
-article called "[Fast easy realtime metrics using Redis
+in the article called "[Fast easy realtime metrics using Redis
 bitmaps][hbgc212fermurb]".
 
-[hbgc212fermurb]:
+[hbgc212fermurb]: http://blog.getspool.com/2011/11/29/fast-easy-realtime-metrics-using-redis-bitmaps
-  http://blog.getspool.com/2011/11/29/fast-easy-realtime-metrics-using-redis-bitmaps
 
 ## Performance considerations
 
 In the above example of counting days, even after 10 years the application is
 online we still have just `365*10` bits of data per user, that is just 456 bytes
-per user. With this amount of data `BITCOUNT` is still as fast as any other O(1)
+per user.
-Redis command like `GET` or `INCR`.
+With this amount of data `BITCOUNT` is still as fast as any other O(1) Redis
+command like `GET` or `INCR`.
 
 When the bitmap is big, there are two alternatives:
 
-- Taking a separated key that is incremented every time the bitmap is modified.
+* Taking a separated key that is incremented every time the bitmap is modified.
   This can be very efficient and atomic using a small Redis Lua script.
-- Running the bitmap incrementally using the `BITCOUNT` _start_ and _end_
+* Running the bitmap incrementally using the `BITCOUNT` _start_ and _end_
   optional parameters, accumulating the results client-side, and optionally
   caching the result into a key.

iredis/data/commands/bitfield.md

@@ -1,18 +1,8 @@
-The command treats a Redis string as a array of bits, and is capable of
+The command treats a Redis string as an array of bits, and is capable of addressing specific integer fields of varying bit widths and arbitrary non (necessary) aligned offset. In practical terms using this command you can set, for example, a signed 5 bits integer at bit offset 1234 to a specific value, retrieve a 31 bit unsigned integer from offset 4567. Similarly the command handles increments and decrements of the specified integers, providing guaranteed and well specified overflow and underflow behavior that the user can configure.
-addressing specific integer fields of varying bit widths and arbitrary non
-(necessary) aligned offset. In practical terms using this command you can set,
-for example, a signed 5 bits integer at bit offset 1234 to a specific value,
-retrieve a 31 bit unsigned integer from offset 4567. Similarly the command
-handles increments and decrements of the specified integers, providing
-guaranteed and well specified overflow and underflow behavior that the user can
-configure.
 
-`BITFIELD` is able to operate with multiple bit fields in the same command call.
+`BITFIELD` is able to operate with multiple bit fields in the same command call. It takes a list of operations to perform, and returns an array of replies, where each array matches the corresponding operation in the list of arguments.
-It takes a list of operations to perform, and returns an array of replies, where
-each array matches the corresponding operation in the list of arguments.
 
-For example the following command increments an 5 bit signed integer at bit
+For example the following command increments a 5 bit signed integer at bit offset 100, and gets the value of the 4 bit unsigned integer at bit offset 0:
-offset 100, and gets the value of the 4 bit unsigned integer at bit offset 0:
 
     > BITFIELD mykey INCRBY i5 100 1 GET u4 0
     1) (integer) 1
@@ -20,76 +10,54 @@ offset 100, and gets the value of the 4 bit unsigned integer at bit offset 0:
 
 Note that:
 
-1. Addressing with `!GET` bits outside the current string length (including the
+1. Addressing with `!GET` bits outside the current string length (including the case the key does not exist at all), results in the operation to be performed like the missing part all consists of bits set to 0.
-   case the key does not exist at all), results in the operation to be performed
+2. Addressing with `!SET` or `!INCRBY` bits outside the current string length will enlarge the string, zero-padding it, as needed, for the minimal length needed, according to the most far bit touched.
-   like the missing part all consists of bits set to 0.
-2. Addressing with `!SET` or `!INCRBY` bits outside the current string length
-   will enlarge the string, zero-padding it, as needed, for the minimal length
-   needed, according to the most far bit touched.
 
-## Supported subcommands and integer types
+## Supported subcommands and integer encoding
 
 The following is the list of supported commands.
 
-- **GET** `<type>` `<offset>` -- Returns the specified bit field.
+* **GET** `<encoding>` `<offset>` -- Returns the specified bit field.
-- **SET** `<type>` `<offset>` `<value>` -- Set the specified bit field and
+* **SET** `<encoding>` `<offset>` `<value>` -- Set the specified bit field and returns its old value.
-  returns its old value.
+* **INCRBY** `<encoding>` `<offset>` `<increment>` -- Increments or decrements (if a negative increment is given) the specified bit field and returns the new value.
-- **INCRBY** `<type>` `<offset>` `<increment>` -- Increments or decrements (if a
-  negative increment is given) the specified bit field and returns the new
-  value.
 
 There is another subcommand that only changes the behavior of successive
 `!INCRBY` and `!SET` subcommands calls by setting the overflow behavior:
 
-- **OVERFLOW** `[WRAP|SAT|FAIL]`
+* **OVERFLOW** `[WRAP|SAT|FAIL]`
 
-Where an integer type is expected, it can be composed by prefixing with `i` for
+Where an integer encoding is expected, it can be composed by prefixing with `i` for signed integers and `u` for unsigned integers with the number of bits of our integer encoding. So for example `u8` is an unsigned integer of 8 bits and `i16` is a
-signed integers and `u` for unsigned integers with the number of bits of our
+signed integer of 16 bits.
-integer type. So for example `u8` is an unsigned integer of 8 bits and `i16` is
-a signed integer of 16 bits.
 
-The supported types are up to 64 bits for signed integers, and up to 63 bits for
+The supported encodings are up to 64 bits for signed integers, and up to 63 bits for
 unsigned integers. This limitation with unsigned integers is due to the fact
 that currently the Redis protocol is unable to return 64 bit unsigned integers
 as replies.
 
 ## Bits and positional offsets
 
-There are two ways in order to specify offsets in the bitfield command. If a
+There are two ways in order to specify offsets in the bitfield command.
-number without any prefix is specified, it is used just as a zero based bit
+If a number without any prefix is specified, it is used just as a zero based
-offset inside the string.
+bit offset inside the string.
 
-However if the offset is prefixed with a `#` character, the specified offset is
+However if the offset is prefixed with a `#` character, the specified offset
-multiplied by the integer type width, so for example:
+is multiplied by the integer encoding's width, so for example:
 
     BITFIELD mystring SET i8 #0 100 SET i8 #1 200
 
-Will set the first i8 integer at offset 0 and the second at offset 8. This way
+Will set the first i8 integer at offset 0 and the second at offset 8.
-you don't have to do the math yourself inside your client if what you want is a
+This way you don't have to do the math yourself inside your client if what
-plain array of integers of a given size.
+you want is a plain array of integers of a given size.
 
 ## Overflow control
 
-Using the `OVERFLOW` command the user is able to fine-tune the behavior of the
+Using the `OVERFLOW` command the user is able to fine-tune the behavior of
-increment or decrement overflow (or underflow) by specifying one of the
+the increment or decrement overflow (or underflow) by specifying one of
-following behaviors:
+the following behaviors:
 
-- **WRAP**: wrap around, both with signed and unsigned integers. In the case of
+* **WRAP**: wrap around, both with signed and unsigned integers. In the case of unsigned integers, wrapping is like performing the operation modulo the maximum value the integer can contain (the C standard behavior). With signed integers instead wrapping means that overflows restart towards the most negative value and underflows towards the most positive ones, so for example if an `i8` integer is set to the value 127, incrementing it by 1 will yield `-128`.
-  unsigned integers, wrapping is like performing the operation modulo the
+* **SAT**: uses saturation arithmetic, that is, on underflows the value is set to the minimum integer value, and on overflows to the maximum integer value. For example incrementing an `i8` integer starting from value 120 with an increment of 10, will result into the value 127, and further increments will always keep the value at 127. The same happens on underflows, but towards the value is blocked at the most negative value.
-  maximum value the integer can contain (the C standard behavior). With signed
+* **FAIL**: in this mode no operation is performed on overflows or underflows detected. The corresponding return value is set to NULL to signal the condition to the caller.
-  integers instead wrapping means that overflows restart towards the most
-  negative value and underflows towards the most positive ones, so for example
-  if an `i8` integer is set to the value 127, incrementing it by 1 will yield
-  `-128`.
-- **SAT**: uses saturation arithmetic, that is, on underflows the value is set
-  to the minimum integer value, and on overflows to the maximum integer value.
-  For example incrementing an `i8` integer starting from value 120 with an
-  increment of 10, will result into the value 127, and further increments will
-  always keep the value at 127. The same happens on underflows, but towards the
-  value is blocked at the most negative value.
-- **FAIL**: in this mode no operation is performed on overflows or underflows
-  detected. The corresponding return value is set to NULL to signal the
-  condition to the caller.
 
 Note that each `OVERFLOW` statement only affects the `!INCRBY` and `!SET`
 commands that follow it in the list of subcommands, up to the next `OVERFLOW`
@@ -124,33 +92,25 @@ The following is an example of `OVERFLOW FAIL` returning NULL.
 ## Motivations
 
 The motivation for this command is that the ability to store many small integers
-as a single large bitmap (or segmented over a few keys to avoid having huge
+as a single large bitmap (or segmented over a few keys to avoid having huge keys) is extremely memory efficient, and opens new use cases for Redis to be applied, especially in the field of real time analytics. This use cases are supported by the ability to specify the overflow in a controlled way.
-keys) is extremely memory efficient, and opens new use cases for Redis to be
-applied, especially in the field of real time analytics. This use cases are
-supported by the ability to specify the overflow in a controlled way.
 
-Fun fact: Reddit's 2017 April fools' project
+Fun fact: Reddit's 2017 April fools' project [r/place](https://reddit.com/r/place) was [built using the Redis BITFIELD command](https://redditblog.com/2017/04/13/how-we-built-rplace/) in order to take an in-memory representation of the collaborative canvas.
-[r/place](https://reddit.com/r/place) was
-[built using the Redis BITFIELD command](https://redditblog.com/2017/04/13/how-we-built-rplace/)
-in order to take an in-memory representation of the collaborative canvas.
 
 ## Performance considerations
 
-Usually `BITFIELD` is a fast command, however note that addressing far bits of
+Usually `BITFIELD` is a fast command, however note that addressing far bits of currently short strings will trigger an allocation that may be more costly than executing the command on bits already existing.
-currently short strings will trigger an allocation that may be more costly than
-executing the command on bits already existing.
 
 ## Orders of bits
 
-The representation used by `BITFIELD` considers the bitmap as having the bit
+The representation used by `BITFIELD` considers the bitmap as having the
-number 0 to be the most significant bit of the first byte, and so forth, so for
+bit number 0 to be the most significant bit of the first byte, and so forth, so
-example setting a 5 bits unsigned integer to value 23 at offset 7 into a bitmap
+for example setting a 5 bits unsigned integer to value 23 at offset 7 into a
-previously set to all zeroes, will produce the following representation:
+bitmap previously set to all zeroes, will produce the following representation:
 
     +--------+--------+
     |00000001|01110000|
     +--------+--------+
 
-When offsets and integer sizes are aligned to bytes boundaries, this is the same
+When offsets and integer sizes are aligned to bytes boundaries, this is the
-as big endian, however when such alignment does not exist, its important to also
+same as big endian, however when such alignment does not exist, its important
-understand how the bits inside a byte are ordered.
+to also understand how the bits inside a byte are ordered.

iredis/data/commands/bitfield_ro.md

@@ -0,0 +1,19 @@
+Read-only variant of the `BITFIELD` command.
+It is like the original `BITFIELD` but only accepts `!GET` subcommand and can safely be used in read-only replicas.
+
+Since the original `BITFIELD` has `!SET` and `!INCRBY` options it is technically flagged as a writing command in the Redis command table.
+For this reason read-only replicas in a Redis Cluster will redirect it to the master instance even if the connection is in read-only mode (see the `READONLY` command of Redis Cluster).
+
+Since Redis 6.2, the `BITFIELD_RO` variant was introduced in order to allow `BITFIELD` behavior in read-only replicas without breaking compatibility on command flags.
+
+See original `BITFIELD` for more details.
+
+@examples
+
+```
+BITFIELD_RO hello GET i8 16
+```
+
+@return
+
+@array-reply: An array with each entry being the corresponding result of the subcommand given at the same position.

iredis/data/commands/bitop.md

@@ -4,13 +4,14 @@ store the result in the destination key.
 The `BITOP` command supports four bitwise operations: **AND**, **OR**, **XOR**
 and **NOT**, thus the valid forms to call the command are:
 
-- `BITOP AND destkey srckey1 srckey2 srckey3 ... srckeyN`
+
-- `BITOP OR destkey srckey1 srckey2 srckey3 ... srckeyN`
+* `BITOP AND destkey srckey1 srckey2 srckey3 ... srckeyN`
-- `BITOP XOR destkey srckey1 srckey2 srckey3 ... srckeyN`
+* `BITOP OR  destkey srckey1 srckey2 srckey3 ... srckeyN`
-- `BITOP NOT destkey srckey`
+* `BITOP XOR destkey srckey1 srckey2 srckey3 ... srckeyN`
+* `BITOP NOT destkey srckey`
 
 As you can see **NOT** is special as it only takes an input key, because it
-performs inversion of bits so it only makes sense as an unary operator.
+performs inversion of bits so it only makes sense as a unary operator.
 
 The result of the operation is always stored at `destkey`.
 
@@ -27,8 +28,8 @@ zero bytes up to the length of the longest string.
 
 @integer-reply
 
-The size of the string stored in the destination key, that is equal to the size
+The size of the string stored in the destination key, that is equal to the
-of the longest input string.
+size of the longest input string.
 
 @examples
 
@@ -42,20 +43,20 @@ GET dest
 ## Pattern: real time metrics using bitmaps
 
 `BITOP` is a good complement to the pattern documented in the `BITCOUNT` command
-documentation. Different bitmaps can be combined in order to obtain a target
+documentation.
-bitmap where the population counting operation is performed.
+Different bitmaps can be combined in order to obtain a target bitmap where
+the population counting operation is performed.
 
 See the article called "[Fast easy realtime metrics using Redis
-bitmaps][hbgc212fermurb]" for a interesting use cases.
+bitmaps][hbgc212fermurb]" for an interesting use cases.
 
-[hbgc212fermurb]:
+[hbgc212fermurb]: http://blog.getspool.com/2011/11/29/fast-easy-realtime-metrics-using-redis-bitmaps
-  http://blog.getspool.com/2011/11/29/fast-easy-realtime-metrics-using-redis-bitmaps
 
 ## Performance considerations
 
-`BITOP` is a potentially slow command as it runs in O(N) time. Care should be
+`BITOP` is a potentially slow command as it runs in O(N) time.
-taken when running it against long input strings.
+Care should be taken when running it against long input strings.
 
 For real-time metrics and statistics involving large inputs a good approach is
-to use a replica (with read-only option disabled) where the bit-wise operations
+to use a replica (with read-only option disabled) where the bit-wise
-are performed to avoid blocking the master instance.
+operations are performed to avoid blocking the master instance.

iredis/data/commands/bitpos.md

@@ -1,25 +1,24 @@
 Return the position of the first bit set to 1 or 0 in a string.
 
-The position is returned, thinking of the string as an array of bits from left
+The position is returned, thinking of the string as an array of bits from left to
-to right, where the first byte's most significant bit is at position 0, the
+right, where the first byte's most significant bit is at position 0, the second
-second byte's most significant bit is at position 8, and so forth.
+byte's most significant bit is at position 8, and so forth.
 
 The same bit position convention is followed by `GETBIT` and `SETBIT`.
 
-By default, all the bytes contained in the string are examined. It is possible
+By default, all the bytes contained in the string are examined.
-to look for bits only in a specified interval passing the additional arguments
+It is possible to look for bits only in a specified interval passing the additional arguments _start_ and _end_ (it is possible to just pass _start_, the operation will assume that the end is the last byte of the string. However there are semantic differences as explained later).
-_start_ and _end_ (it is possible to just pass _start_, the operation will
+By default, the range is interpreted as a range of bytes and not a range of bits, so `start=0` and `end=2` means to look at the first three bytes.
-assume that the end is the last byte of the string. However there are semantic
-differences as explained later). The range is interpreted as a range of bytes
-and not a range of bits, so `start=0` and `end=2` means to look at the first
-three bytes.
 
-Note that bit positions are returned always as absolute values starting from bit
+You can use the optional `BIT` modifier to specify that the range should be interpreted as a range of bits.
-zero even when _start_ and _end_ are used to specify a range.
+So `start=0` and `end=2` means to look at the first three bits.
+
+Note that bit positions are returned always as absolute values starting from bit zero even when _start_ and _end_ are used to specify a range.
 
 Like for the `GETRANGE` command start and end can contain negative values in
 order to index bytes starting from the end of the string, where -1 is the last
-byte, -2 is the penultimate, and so forth.
+byte, -2 is the penultimate, and so forth. When `BIT` is specified, -1 is the last
+bit, -2 is the penultimate, and so forth.
 
 Non-existent keys are treated as empty strings.
 
@@ -27,25 +26,15 @@ Non-existent keys are treated as empty strings.
 
 @integer-reply
 
-The command returns the position of the first bit set to 1 or 0 according to the
+The command returns the position of the first bit set to 1 or 0 according to the request.
-request.
 
-If we look for set bits (the bit argument is 1) and the string is empty or
+If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.
-composed of just zero bytes, -1 is returned.
 
-If we look for clear bits (the bit argument is 0) and the string only contains
+If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value `0xff` the command `BITPOS key 0` will return 24, since up to bit 23 all the bits are 1.
-bit set to 1, the function returns the first bit not part of the string on the
-right. So if the string is three bytes set to the value `0xff` the command
-`BITPOS key 0` will return 24, since up to bit 23 all the bits are 1.
 
-Basically, the function considers the right of the string as padded with zeros
+Basically, the function considers the right of the string as padded with zeros if you look for clear bits and specify no range or the _start_ argument **only**.
-if you look for clear bits and specify no range or the _start_ argument
-**only**.
 
-However, this behavior changes if you are looking for clear bits and specify a
+However, this behavior changes if you are looking for clear bits and specify a range with both __start__ and __end__. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.
-range with both **start** and **end**. If no clear bit is found in the specified
-range, the function returns -1 as the user specified a clear range and there are
-no 0 bits in that range.
 
 @examples
 
@@ -55,6 +44,9 @@ BITPOS mykey 0
 SET mykey "\x00\xff\xf0"
 BITPOS mykey 1 0
 BITPOS mykey 1 2
+BITPOS mykey 1 2 -1 BYTE
+BITPOS mykey 1 7 15 BIT
 set mykey "\x00\x00\x00"
 BITPOS mykey 1
+BITPOS mykey 1 7 -3 BIT
 ```

iredis/data/commands/blmove.md

@@ -1,8 +1,9 @@
-`BLMOVE` is the blocking variant of `LMOVE`. When `source` contains elements,
+`BLMOVE` is the blocking variant of `LMOVE`.
-this command behaves exactly like `LMOVE`. When used inside a `MULTI`/`EXEC`
+When `source` contains elements, this command behaves exactly like `LMOVE`.
-block, this command behaves exactly like `LMOVE`. When `source` is empty, Redis
+When used inside a `MULTI`/`EXEC` block, this command behaves exactly like `LMOVE`.
-will block the connection until another client pushes to it or until `timeout`
+When `source` is empty, Redis will block the connection until another client
-is reached. A `timeout` of zero can be used to block indefinitely.
+pushes to it or until `timeout` (a double value specifying the maximum number of seconds to block) is reached.
+A `timeout` of zero can be used to block indefinitely.
 
 This command comes in place of the now deprecated `BRPOPLPUSH`. Doing
 `BLMOVE RIGHT LEFT` is equivalent.
@@ -11,8 +12,8 @@ See `LMOVE` for more information.
 
 @return
 
-@bulk-string-reply: the element being popped from `source` and pushed to
+@bulk-string-reply: the element being popped from `source` and pushed to `destination`.
-`destination`. If `timeout` is reached, a @nil-reply is returned.
+If `timeout` is reached, a @nil-reply is returned.
 
 ## Pattern: Reliable queue
 

iredis/data/commands/blmpop.md

@@ -0,0 +1,15 @@
+`BLMPOP` is the blocking variant of `LMPOP`.
+
+When any of the lists contains elements, this command behaves exactly like `LMPOP`.
+When used inside a `MULTI`/`EXEC` block, this command behaves exactly like `LMPOP`.
+When all lists are empty, Redis will block the connection until another client pushes to it or until the `timeout` (a double value specifying the maximum number of seconds to block) elapses.
+A `timeout` of zero can be used to block indefinitely.
+
+See `LMPOP` for more information.
+
+@return
+
+@array-reply: specifically:
+
+* A `nil` when no element could be popped, and timeout is reached.
+* A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of elements.

iredis/data/commands/blpop.md

@@ -1,7 +1,8 @@
-`BLPOP` is a blocking list pop primitive. It is the blocking version of `LPOP`
+`BLPOP` is a blocking list pop primitive.
-because it blocks the connection when there are no elements to pop from any of
+It is the blocking version of `LPOP` because it blocks the connection when there
-the given lists. An element is popped from the head of the first list that is
+are no elements to pop from any of the given lists.
-non-empty, with the given keys being checked in the order that they are given.
+An element is popped from the head of the first list that is non-empty, with the
+given keys being checked in the order that they are given.
 
 ## Non-blocking behavior
 
@@ -9,9 +10,10 @@ When `BLPOP` is called, if at least one of the specified keys contains a
 non-empty list, an element is popped from the head of the list and returned to
 the caller together with the `key` it was popped from.
 
-Keys are checked in the order that they are given. Let's say that the key
+Keys are checked in the order that they are given.
-`list1` doesn't exist and `list2` and `list3` hold non-empty lists. Consider the
+Let's say that the key `list1` doesn't exist and `list2` and `list3` hold
-following command:
+non-empty lists.
+Consider the following command:
 
 ```
 BLPOP list1 list2 list3 0
@@ -29,93 +31,53 @@ client performs an `LPUSH` or `RPUSH` operation against one of the keys.
 Once new data is present on one of the lists, the client returns with the name
 of the key unblocking it and the popped value.
 
-When `BLPOP` causes a client to block and a non-zero timeout is specified, the
+When `BLPOP` causes a client to block and a non-zero timeout is specified,
-client will unblock returning a `nil` multi-bulk value when the specified
+the client will unblock returning a `nil` multi-bulk value when the specified
 timeout has expired without a push operation against at least one of the
 specified keys.
 
-**The timeout argument is interpreted as a double value specifying the maximum
+**The timeout argument is interpreted as a double value specifying the maximum number of seconds to block**. A timeout of zero can be used to block indefinitely.
-number of seconds to block**. A timeout of zero can be used to block
-indefinitely.
 
 ## What key is served first? What client? What element? Priority ordering details.
 
-- If the client tries to blocks for multiple keys, but at least one key contains
+* If the client tries to blocks for multiple keys, but at least one key contains elements, the returned key / element pair is the first key from left to right that has one or more elements. In this case the client is not blocked. So for instance `BLPOP key1 key2 key3 key4 0`, assuming that both `key2` and `key4` are non-empty, will always return an element from `key2`.
-  elements, the returned key / element pair is the first key from left to right
+* If multiple clients are blocked for the same key, the first client to be served is the one that was waiting for more time (the first that blocked for the key). Once a client is unblocked it does not retain any priority, when it blocks again with the next call to `BLPOP` it will be served accordingly to the number of clients already blocked for the same key, that will all be served before it (from the first to the last that blocked).
-  that has one or more elements. In this case the client is not blocked. So for
+* When a client is blocking for multiple keys at the same time, and elements are available at the same time in multiple keys (because of a transaction or a Lua script added elements to multiple lists), the client will be unblocked using the first key that received a push operation (assuming it has enough elements to serve our client, as there may be other clients as well waiting for this key). Basically after the execution of every command Redis will run a list of all the keys that received data AND that have at least a client blocked. The list is ordered by new element arrival time, from the first key that received data to the last. For every key processed, Redis will serve all the clients waiting for that key in a FIFO fashion, as long as there are elements in this key. When the key is empty or there are no longer clients waiting for this key, the next key that received new data in the previous command / transaction / script is processed, and so forth.
-  instance `BLPOP key1 key2 key3 key4 0`, assuming that both `key2` and `key4`
-  are non-empty, will always return an element from `key2`.
-- If multiple clients are blocked for the same key, the first client to be
-  served is the one that was waiting for more time (the first that blocked for
-  the key). Once a client is unblocked it does not retain any priority, when it
-  blocks again with the next call to `BLPOP` it will be served accordingly to
-  the number of clients already blocked for the same key, that will all be
-  served before it (from the first to the last that blocked).
-- When a client is blocking for multiple keys at the same time, and elements are
-  available at the same time in multiple keys (because of a transaction or a Lua
-  script added elements to multiple lists), the client will be unblocked using
-  the first key that received a push operation (assuming it has enough elements
-  to serve our client, as there may be other clients as well waiting for this
-  key). Basically after the execution of every command Redis will run a list of
-  all the keys that received data AND that have at least a client blocked. The
-  list is ordered by new element arrival time, from the first key that received
-  data to the last. For every key processed, Redis will serve all the clients
-  waiting for that key in a FIFO fashion, as long as there are elements in this
-  key. When the key is empty or there are no longer clients waiting for this
-  key, the next key that received new data in the previous command / transaction
-  / script is processed, and so forth.
 
 ## Behavior of `!BLPOP` when multiple elements are pushed inside a list.
 
-There are times when a list can receive multiple elements in the context of the
+There are times when a list can receive multiple elements in the context of the same conceptual command:
-same conceptual command:
 
-- Variadic push operations such as `LPUSH mylist a b c`.
+* Variadic push operations such as `LPUSH mylist a b c`.
-- After an `EXEC` of a `MULTI` block with multiple push operations against the
+* After an `EXEC` of a `MULTI` block with multiple push operations against the same list.
-  same list.
+* Executing a Lua Script with Redis 2.6 or newer.
-- Executing a Lua Script with Redis 2.6 or newer.
 
-When multiple elements are pushed inside a list where there are clients
+When multiple elements are pushed inside a list where there are clients blocking, the behavior is different for Redis 2.4 and Redis 2.6 or newer.
-blocking, the behavior is different for Redis 2.4 and Redis 2.6 or newer.
 
-For Redis 2.6 what happens is that the command performing multiple pushes is
+For Redis 2.6 what happens is that the command performing multiple pushes is executed, and *only after* the execution of the command the blocked clients are served. Consider this sequence of commands.
-executed, and _only after_ the execution of the command the blocked clients are
-served. Consider this sequence of commands.
 
     Client A:   BLPOP foo 0
     Client B:   LPUSH foo a b c
 
-If the above condition happens using a Redis 2.6 server or greater, Client **A**
+If the above condition happens using a Redis 2.6 server or greater, Client **A** will be served with the `c` element, because after the `LPUSH` command the list contains `c,b,a`, so taking an element from the left means to return `c`.
-will be served with the `c` element, because after the `LPUSH` command the list
-contains `c,b,a`, so taking an element from the left means to return `c`.
 
-Instead Redis 2.4 works in a different way: clients are served _in the context_
+Instead Redis 2.4 works in a different way: clients are served *in the context* of the push operation, so as long as `LPUSH foo a b c` starts pushing the first element to the list, it will be delivered to the Client **A**, that will receive `a` (the first element pushed).
-of the push operation, so as long as `LPUSH foo a b c` starts pushing the first
-element to the list, it will be delivered to the Client **A**, that will receive
-`a` (the first element pushed).
 
-The behavior of Redis 2.4 creates a lot of problems when replicating or
+The behavior of Redis 2.4 creates a lot of problems when replicating or persisting data into the AOF file, so the much more generic and semantically simpler behavior was introduced into Redis 2.6 to prevent problems.
-persisting data into the AOF file, so the much more generic and semantically
-simpler behavior was introduced into Redis 2.6 to prevent problems.
 
-Note that for the same reason a Lua script or a `MULTI/EXEC` block may push
+Note that for the same reason a Lua script or a `MULTI/EXEC` block may push elements into a list and afterward **delete the list**. In this case the blocked clients will not be served at all and will continue to be blocked as long as no data is present on the list after the execution of a single command, transaction, or script.
-elements into a list and afterward **delete the list**. In this case the blocked
-clients will not be served at all and will continue to be blocked as long as no
-data is present on the list after the execution of a single command,
-transaction, or script.
 
 ## `!BLPOP` inside a `!MULTI` / `!EXEC` transaction
 
-`BLPOP` can be used with pipelining (sending multiple commands and reading the
+`BLPOP` can be used with pipelining (sending multiple commands and
-replies in batch), however this setup makes sense almost solely when it is the
+reading the replies in batch), however this setup makes sense almost solely
-last command of the pipeline.
+when it is the last command of the pipeline.
 
-Using `BLPOP` inside a `MULTI` / `EXEC` block does not make a lot of sense as it
+Using `BLPOP` inside a `MULTI` / `EXEC` block does not make a lot of sense
-would require blocking the entire server in order to execute the block
+as it would require blocking the entire server in order to execute the block
 atomically, which in turn does not allow other clients to perform a push
-operation. For this reason the behavior of `BLPOP` inside `MULTI` / `EXEC` when
+operation. For this reason the behavior of `BLPOP` inside `MULTI` / `EXEC` when the list is empty is to return a `nil` multi-bulk reply, which is the same
-the list is empty is to return a `nil` multi-bulk reply, which is the same thing
+thing that happens when the timeout is reached.
-that happens when the timeout is reached.
 
 If you like science fiction, think of time flowing at infinite speed inside a
 `MULTI` / `EXEC` block...
@@ -124,15 +86,11 @@ If you like science fiction, think of time flowing at infinite speed inside a
 
 @array-reply: specifically:
 
-- A `nil` multi-bulk when no element could be popped and the timeout expired.
+* A `nil` multi-bulk when no element could be popped and the timeout expired.
-- A two-element multi-bulk with the first element being the name of the key
+* A two-element multi-bulk with the first element being the name of the key
   where an element was popped and the second element being the value of the
   popped element.
 
-@history
-
-- `>= 6.0`: `timeout` is interpreted as a double instead of an integer.
-
 @examples
 
 ```
@@ -147,23 +105,19 @@ redis> BLPOP list1 list2 0
 
 ## Reliable queues
 
-When `BLPOP` returns an element to the client, it also removes the element from
+When `BLPOP` returns an element to the client, it also removes the element from the list. This means that the element only exists in the context of the client: if the client crashes while processing the returned element, it is lost forever.
-the list. This means that the element only exists in the context of the client:
-if the client crashes while processing the returned element, it is lost forever.
 
-This can be a problem with some application where we want a more reliable
+This can be a problem with some application where we want a more reliable messaging system. When this is the case, please check the `BRPOPLPUSH` command, that is a variant of `BLPOP` that adds the returned element to a target list before returning it to the client.
-messaging system. When this is the case, please check the `BRPOPLPUSH` command,
-that is a variant of `BLPOP` that adds the returned element to a target list
-before returning it to the client.
 
 ## Pattern: Event notification
 
 Using blocking list operations it is possible to mount different blocking
-primitives. For instance for some application you may need to block waiting for
+primitives.
-elements into a Redis Set, so that as far as a new element is added to the Set,
+For instance for some application you may need to block waiting for elements
-it is possible to retrieve it without resort to polling. This would require a
+into a Redis Set, so that as far as a new element is added to the Set, it is
-blocking version of `SPOP` that is not available, but using blocking list
+possible to retrieve it without resort to polling.
-operations we can easily accomplish this task.
+This would require a blocking version of `SPOP` that is not available, but using
+blocking list operations we can easily accomplish this task.
 
 The consumer will do:
 

iredis/data/commands/brpop.md

@@ -1,7 +1,8 @@
-`BRPOP` is a blocking list pop primitive. It is the blocking version of `RPOP`
+`BRPOP` is a blocking list pop primitive.
-because it blocks the connection when there are no elements to pop from any of
+It is the blocking version of `RPOP` because it blocks the connection when there
-the given lists. An element is popped from the tail of the first list that is
+are no elements to pop from any of the given lists.
-non-empty, with the given keys being checked in the order that they are given.
+An element is popped from the tail of the first list that is non-empty, with the
+given keys being checked in the order that they are given.
 
 See the [BLPOP documentation][cb] for the exact semantics, since `BRPOP` is
 identical to `BLPOP` with the only difference being that it pops elements from
@@ -13,15 +14,11 @@ the tail of a list instead of popping from the head.
 
 @array-reply: specifically:
 
-- A `nil` multi-bulk when no element could be popped and the timeout expired.
+* A `nil` multi-bulk when no element could be popped and the timeout expired.
-- A two-element multi-bulk with the first element being the name of the key
+* A two-element multi-bulk with the first element being the name of the key
   where an element was popped and the second element being the value of the
   popped element.
 
-@history
-
-- `>= 6.0`: `timeout` is interpreted as a double instead of an integer.
-
 @examples
 
 ```

iredis/data/commands/brpoplpush.md

@@ -1,23 +1,16 @@
-`BRPOPLPUSH` is the blocking variant of `RPOPLPUSH`. When `source` contains
+`BRPOPLPUSH` is the blocking variant of `RPOPLPUSH`.
-elements, this command behaves exactly like `RPOPLPUSH`. When used inside a
+When `source` contains elements, this command behaves exactly like `RPOPLPUSH`.
-`MULTI`/`EXEC` block, this command behaves exactly like `RPOPLPUSH`. When
+When used inside a `MULTI`/`EXEC` block, this command behaves exactly like `RPOPLPUSH`.
-`source` is empty, Redis will block the connection until another client pushes
+When `source` is empty, Redis will block the connection until another client
-to it or until `timeout` is reached. A `timeout` of zero can be used to block
+pushes to it or until `timeout` is reached.
-indefinitely.
+A `timeout` of zero can be used to block indefinitely.
-
-As per Redis 6.2.0, BRPOPLPUSH is considered deprecated. Please prefer `BLMOVE`
-in new code.
 
 See `RPOPLPUSH` for more information.
 
 @return
 
-@bulk-string-reply: the element being popped from `source` and pushed to
+@bulk-string-reply: the element being popped from `source` and pushed to `destination`.
-`destination`. If `timeout` is reached, a @nil-reply is returned.
+If `timeout` is reached, a @nil-reply is returned.
-
-@history
-
-- `>= 6.0`: `timeout` is interpreted as a double instead of an integer.
 
 ## Pattern: Reliable queue
 

iredis/data/commands/bzmpop.md

@@ -0,0 +1,16 @@
+`BZMPOP` is the blocking variant of `ZMPOP`.
+
+When any of the sorted sets contains elements, this command behaves exactly like `ZMPOP`.
+When used inside a `MULTI`/`EXEC` block, this command behaves exactly like `ZMPOP`.
+When all sorted sets are empty, Redis will block the connection until another client adds members to one of the keys or until the `timeout` (a double value specifying the maximum number of seconds to block) elapses.
+A `timeout` of zero can be used to block indefinitely.
+
+See `ZMPOP` for more information.
+
+@return
+
+@array-reply: specifically:
+
+* A `nil` when no element could be popped.
+* A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of the popped elements. Every entry in the elements array is also an array that contains the member and its score.
+

iredis/data/commands/bzpopmax.md

@@ -1,9 +1,9 @@
 `BZPOPMAX` is the blocking variant of the sorted set `ZPOPMAX` primitive.
 
 It is the blocking version because it blocks the connection when there are no
-members to pop from any of the given sorted sets. A member with the highest
+members to pop from any of the given sorted sets.
-score is popped from first sorted set that is non-empty, with the given keys
+A member with the highest score is popped from first sorted set that is
-being checked in the order that they are given.
+non-empty, with the given keys being checked in the order that they are given.
 
 The `timeout` argument is interpreted as a double value specifying the maximum
 number of seconds to block. A timeout of zero can be used to block indefinitely.
@@ -18,14 +18,10 @@ with the highest scores instead of popping the ones with the lowest scores.
 
 @array-reply: specifically:
 
-- A `nil` multi-bulk when no element could be popped and the timeout expired.
+* A `nil` multi-bulk when no element could be popped and the timeout expired.
-- A three-element multi-bulk with the first element being the name of the key
+* A three-element multi-bulk with the first element being the name of the key
-  where a member was popped, the second element is the popped member itself, and
+  where a member was popped, the second element is the popped member itself,
-  the third element is the score of the popped element.
+  and the third element is the score of the popped element.
-
-@history
-
-- `>= 6.0`: `timeout` is interpreted as a double instead of an integer.
 
 @examples
 

iredis/data/commands/bzpopmin.md

@@ -1,11 +1,11 @@
 `BZPOPMIN` is the blocking variant of the sorted set `ZPOPMIN` primitive.
 
 It is the blocking version because it blocks the connection when there are no
-members to pop from any of the given sorted sets. A member with the lowest score
+members to pop from any of the given sorted sets.
-is popped from first sorted set that is non-empty, with the given keys being
+A member with the lowest score is popped from first sorted set that is
-checked in the order that they are given.
+non-empty, with the given keys being checked in the order that they are given.
 
-The `timeout` argument is interpreted as an double value specifying the maximum
+The `timeout` argument is interpreted as a double value specifying the maximum
 number of seconds to block. A timeout of zero can be used to block indefinitely.
 
 See the [BLPOP documentation][cl] for the exact semantics, since `BZPOPMIN` is
@@ -18,14 +18,10 @@ popped from.
 
 @array-reply: specifically:
 
-- A `nil` multi-bulk when no element could be popped and the timeout expired.
+* A `nil` multi-bulk when no element could be popped and the timeout expired.
-- A three-element multi-bulk with the first element being the name of the key
+* A three-element multi-bulk with the first element being the name of the key
-  where a member was popped, the second element is the popped member itself, and
+  where a member was popped, the second element is the popped member itself,
-  the third element is the score of the popped element.
+  and the third element is the score of the popped element.
-
-@history
-
-- `>= 6.0`: `timeout` is interpreted as a double instead of an integer.
 
 @examples
 

iredis/data/commands/client-caching.md

@@ -1,18 +1,21 @@
-This command controls the tracking of the keys in the next command executed by
+This command controls the tracking of the keys in the next command executed
-the connection, when tracking is enabled in `OPTIN` or `OPTOUT` mode. Please
+by the connection, when tracking is enabled in `OPTIN` or `OPTOUT` mode.
-check the [client side caching documentation](/topics/client-side-caching) for
+Please check the
+[client side caching documentation](/topics/client-side-caching) for
 background information.
 
 When tracking is enabled Redis, using the `CLIENT TRACKING` command, it is
-possible to specify the `OPTIN` or `OPTOUT` options, so that keys in read only
+possible to specify the `OPTIN` or `OPTOUT` options, so that keys
-commands are not automatically remembered by the server to be invalidated later.
+in read only commands are not automatically remembered by the server to
-When we are in `OPTIN` mode, we can enable the tracking of the keys in the next
+be invalidated later. When we are in `OPTIN` mode, we can enable the
-command by calling `CLIENT CACHING yes` immediately before it. Similarly when we
+tracking of the keys in the next command by calling `CLIENT CACHING yes`
-are in `OPTOUT` mode, and keys are normally tracked, we can avoid the keys in
+immediately before it. Similarly when we are in `OPTOUT` mode, and keys
-the next command to be tracked using `CLIENT CACHING no`.
+are normally tracked, we can avoid the keys in the next command to be
+tracked using `CLIENT CACHING no`.
 
-Basically the command sets a state in the connection, that is valid only for the
+Basically the command sets a state in the connection, that is valid only
-next command execution, that will modify the behavior of client tracking.
+for the next command execution, that will modify the behavior of client
+tracking.
 
 @return
 

iredis/data/commands/client-getname.md

@@ -1,6 +1,4 @@
-The `CLIENT GETNAME` returns the name of the current connection as set by
+The `CLIENT GETNAME` returns the name of the current connection as set by `CLIENT SETNAME`. Since every new connection starts without an associated name, if no name was assigned a null bulk reply is returned.
-`CLIENT SETNAME`. Since every new connection starts without an associated name,
-if no name was assigned a null bulk reply is returned.
 
 @return
 

iredis/data/commands/client-getredir.md

@@ -1,13 +1,11 @@
 This command returns the client ID we are redirecting our
-[tracking](/topics/client-side-caching) notifications to. We set a client to
+[tracking](/topics/client-side-caching) notifications to. We set a client
-redirect to when using `CLIENT TRACKING` to enable tracking. However in order to
+to redirect to when using `CLIENT TRACKING` to enable tracking. However in
-avoid forcing client libraries implementations to remember the ID notifications
+order to avoid forcing client libraries implementations to remember the
-are redirected to, this command exists in order to improve introspection and
+ID notifications are redirected to, this command exists in order to improve
-allow clients to check later if redirection is active and towards which client
+introspection and allow clients to check later if redirection is active
-ID.
+and towards which client ID.
 
 @return
 
-@integer-reply: the ID of the client we are redirecting the notifications to.
+@integer-reply: the ID of the client we are redirecting the notifications to. The command returns `-1` if client tracking is not enabled, or `0` if client tracking is enabled but we are not redirecting the notifications to any client.
-The command returns `-1` if client tracking is not enabled, or `0` if client
-tracking is enabled but we are not redirecting the notifications to any client.

iredis/data/commands/client-help.md

@@ -0,0 +1,5 @@
+The `CLIENT HELP` command returns a helpful text describing the different subcommands.
+
+@return
+
+@array-reply: a list of subcommands and their descriptions

iredis/data/commands/client-id.md

@@ -1,16 +1,11 @@
-The command just returns the ID of the current connection. Every connection ID
+The command just returns the ID of the current connection. Every connection
-has certain guarantees:
+ID has certain guarantees:
 
-1. It is never repeated, so if `CLIENT ID` returns the same number, the caller
+1. It is never repeated, so if `CLIENT ID` returns the same number, the caller can be sure that the underlying client did not disconnect and reconnect the connection, but it is still the same connection.
-   can be sure that the underlying client did not disconnect and reconnect the
+2. The ID is monotonically incremental. If the ID of a connection is greater than the ID of another connection, it is guaranteed that the second connection was established with the server at a later time.
-   connection, but it is still the same connection.
-2. The ID is monotonically incremental. If the ID of a connection is greater
-   than the ID of another connection, it is guaranteed that the second
-   connection was established with the server at a later time.
 
 This command is especially useful together with `CLIENT UNBLOCK` which was
-introduced also in Redis 5 together with `CLIENT ID`. Check the `CLIENT UNBLOCK`
+introduced also in Redis 5 together with `CLIENT ID`. Check the `CLIENT UNBLOCK` command page for a pattern involving the two commands.
-command page for a pattern involving the two commands.
 
 @examples
 

iredis/data/commands/client-info.md

@@ -1,8 +1,6 @@
-The command returns information and statistics about the current client
+The command returns information and statistics about the current client connection in a mostly human readable format.
-connection in a mostly human readable format.
 
-The reply format is identical to that of `CLIENT LIST`, and the content consists
+The reply format is identical to that of `CLIENT LIST`, and the content consists only of information about the current client.
-only of information about the current client.
 
 @examples
 
@@ -12,5 +10,4 @@ CLIENT INFO
 
 @return
 
-@bulk-string-reply: a unique string, as described at the `CLIENT LIST` page, for
+@bulk-string-reply: a unique string, as described at the `CLIENT LIST` page, for the current client.
-the current client.

iredis/data/commands/client-kill.md

@@ -1,60 +1,45 @@
-The `CLIENT KILL` command closes a given client connection. This command support
+The `CLIENT KILL` command closes a given client connection. This command support two formats, the old format:
-two formats, the old format:
 
     CLIENT KILL addr:port
 
-The `ip:port` should match a line returned by the `CLIENT LIST` command (`addr`
+The `ip:port` should match a line returned by the `CLIENT LIST` command (`addr` field).
-field).
 
 The new format:
 
     CLIENT KILL <filter> <value> ... ... <filter> <value>
 
-With the new form it is possible to kill clients by different attributes instead
+With the new form it is possible to kill clients by different attributes
-of killing just by address. The following filters are available:
+instead of killing just by address. The following filters are available:
 
-- `CLIENT KILL ADDR ip:port`. This is exactly the same as the old
+* `CLIENT KILL ADDR ip:port`. This is exactly the same as the old three-arguments behavior.
-  three-arguments behavior.
+* `CLIENT KILL LADDR ip:port`. Kill all clients connected to specified local (bind) address.
-- `CLIENT KILL LADDR ip:port`. Kill all clients connected to specified local
+* `CLIENT KILL ID client-id`. Allows to kill a client by its unique `ID` field. Client `ID`'s are retrieved using the `CLIENT LIST` command.
-  (bind) address.
+* `CLIENT KILL TYPE type`, where *type* is one of `normal`, `master`, `replica` and `pubsub`. This closes the connections of **all the clients** in the specified class. Note that clients blocked into the `MONITOR` command are considered to belong to the `normal` class.
-- `CLIENT KILL ID client-id`. Allows to kill a client by its unique `ID` field.
+* `CLIENT KILL USER username`. Closes all the connections that are authenticated with the specified [ACL](/topics/acl) username, however it returns an error if the username does not map to an existing ACL user.
-  Client `ID`'s are retrieved using the `CLIENT LIST` command.
+* `CLIENT KILL SKIPME yes/no`. By default this option is set to `yes`, that is, the client calling the command will not get killed, however setting this option to `no` will have the effect of also killing the client calling the command.
-- `CLIENT KILL TYPE type`, where _type_ is one of `normal`, `master`, `replica`
-  and `pubsub`. This closes the connections of **all the clients** in the
-  specified class. Note that clients blocked into the `MONITOR` command are
-  considered to belong to the `normal` class.
-- `CLIENT KILL USER username`. Closes all the connections that are authenticated
-  with the specified [ACL](/topics/acl) username, however it returns an error if
-  the username does not map to an existing ACL user.
-- `CLIENT KILL SKIPME yes/no`. By default this option is set to `yes`, that is,
-  the client calling the command will not get killed, however setting this
-  option to `no` will have the effect of also killing the client calling the
-  command.
 
-It is possible to provide multiple filters at the same time. The command will
+It is possible to provide multiple filters at the same time. The command will handle multiple filters via logical AND. For example:
-handle multiple filters via logical AND. For example:
 
     CLIENT KILL addr 127.0.0.1:12345 type pubsub
 
-is valid and will kill only a pubsub client with the specified address. This
+is valid and will kill only a pubsub client with the specified address. This format containing multiple filters is rarely useful currently.
-format containing multiple filters is rarely useful currently.
 
-When the new form is used the command no longer returns `OK` or an error, but
+When the new form is used the command no longer returns `OK` or an error, but instead the number of killed clients, that may be zero.
-instead the number of killed clients, that may be zero.
 
 ## CLIENT KILL and Redis Sentinel
 
-Recent versions of Redis Sentinel (Redis 2.8.12 or greater) use CLIENT KILL in
+Recent versions of Redis Sentinel (Redis 2.8.12 or greater) use CLIENT KILL
-order to kill clients when an instance is reconfigured, in order to force
+in order to kill clients when an instance is reconfigured, in order to
-clients to perform the handshake with one Sentinel again and update its
+force clients to perform the handshake with one Sentinel again and update
-configuration.
+its configuration.
 
 ## Notes
 
-Due to the single-threaded nature of Redis, it is not possible to kill a client
+Due to the single-threaded nature of Redis, it is not possible to
-connection while it is executing a command. From the client point of view, the
+kill a client connection while it is executing a command. From
-connection can never be closed in the middle of the execution of a command.
+the client point of view, the connection can never be closed
-However, the client will notice the connection has been closed only when the
+in the middle of the execution of a command. However, the client
+will notice the connection has been closed only when the
 next command is sent (and results in network error).
 
 @return
@@ -66,12 +51,3 @@ When called with the three arguments format:
 When called with the filter / value format:
 
 @integer-reply: the number of clients killed.
-
-@history
-
-- `>= 2.8.12`: Added new filter format.
-- `>= 2.8.12`: `ID` option.
-- `>= 3.2`: Added `master` type in for `TYPE` option.
-- `>= 5`: Replaced `slave` `TYPE` with `replica`. `slave` still supported for
-  backward compatibility.
-- `>= 6.2`: `LADDR` option.

iredis/data/commands/client-list.md

@@ -1,49 +1,46 @@
 The `CLIENT LIST` command returns information and statistics about the client
 connections server in a mostly human readable format.
 
-You can use one of the optional subcommands to filter the list. The `TYPE type`
+You can use one of the optional subcommands to filter the list. The `TYPE type` subcommand filters the list by clients' type, where *type* is one of `normal`, `master`, `replica`, and `pubsub`. Note that clients blocked by the `MONITOR` command belong to the `normal` class.
-subcommand filters the list by clients' type, where _type_ is one of `normal`,
-`master`, `replica`, and `pubsub`. Note that clients blocked by the `MONITOR`
-command belong to the `normal` class.
 
-The `ID` filter only returns entries for clients with IDs matching the
+The `ID` filter only returns entries for clients with IDs matching the `client-id` arguments.
-`client-id` arguments.
 
 @return
 
 @bulk-string-reply: a unique string, formatted as follows:
 
-- One client connection per line (separated by LF)
+* One client connection per line (separated by LF)
-- Each line is composed of a succession of `property=value` fields separated by
+* Each line is composed of a succession of `property=value` fields separated
-  a space character.
+  by a space character.
 
 Here is the meaning of the fields:
 
-- `id`: an unique 64-bit client ID.
+* `id`: a unique 64-bit client ID
-- `name`: the name set by the client with `CLIENT SETNAME`
+* `addr`: address/port of the client
-- `addr`: address/port of the client
+* `laddr`: address/port of local address client connected to (bind address)
-- `laddr`: address/port of local address client connected to (bind address)
+* `fd`: file descriptor corresponding to the socket
-- `fd`: file descriptor corresponding to the socket
+* `name`: the name set by the client with `CLIENT SETNAME`
-- `age`: total duration of the connection in seconds
+* `age`: total duration of the connection in seconds
-- `idle`: idle time of the connection in seconds
+* `idle`: idle time of the connection in seconds
-- `flags`: client flags (see below)
+* `flags`: client flags (see below)
-- `db`: current database ID
+* `db`: current database ID
-- `sub`: number of channel subscriptions
+* `sub`: number of channel subscriptions
-- `psub`: number of pattern matching subscriptions
+* `psub`: number of pattern matching subscriptions
-- `multi`: number of commands in a MULTI/EXEC context
+* `ssub`: number of shard channel subscriptions. Added in Redis 7.0.3
-- `qbuf`: query buffer length (0 means no query pending)
+* `multi`: number of commands in a MULTI/EXEC context
-- `qbuf-free`: free space of the query buffer (0 means the buffer is full)
+* `qbuf`: query buffer length (0 means no query pending)
-- `obl`: output buffer length
+* `qbuf-free`: free space of the query buffer (0 means the buffer is full)
-- `oll`: output list length (replies are queued in this list when the buffer is
+* `argv-mem`: incomplete arguments for the next command (already extracted from query buffer)
-  full)
+* `multi-mem`: memory is used up by buffered multi commands. Added in Redis 7.0
-- `omem`: output buffer memory usage
+* `obl`: output buffer length
-- `events`: file descriptor events (see below)
+* `oll`: output list length (replies are queued in this list when the buffer is full)
-- `cmd`: last command played
+* `omem`: output buffer memory usage
-- `argv-mem`: incomplete arguments for the next command (already extracted from
+* `tot-mem`: total memory consumed by this client in its various buffers
-  query buffer)
+* `events`: file descriptor events (see below)
-- `tot-mem`: total memory consumed by this client in its various buffers
+* `cmd`: last command played
-- `redir`: client id of current client tracking redirection
+* `user`: the authenticated username of the client
-- `user`: the authenticated username of the client
+* `redir`: client id of current client tracking redirection
+* `resp`: client RESP protocol version. Added in Redis 7.0
 
 The client flags can be a combination of:
 
@@ -64,7 +61,7 @@ U: the client is connected via a Unix domain socket
 x: the client is in a MULTI/EXEC context
 t: the client enabled keys tracking in order to perform client side caching
 R: the client tracking target client is invalid
-B: the client enabled broadcast tracking mode
+B: the client enabled broadcast tracking mode 
 ```
 
 The file descriptor events can be:
@@ -76,13 +73,7 @@ w: the client socket is writable (event loop)
 
 ## Notes
 
-New fields are regularly added for debugging purpose. Some could be removed in
+New fields are regularly added for debugging purpose. Some could be removed
-the future. A version safe Redis client using this command should parse the
+in the future. A version safe Redis client using this command should parse
-output accordingly (i.e. handling gracefully missing fields, skipping unknown
+the output accordingly (i.e. handling gracefully missing fields, skipping
-fields).
+unknown fields).
-
-@history
-
-- `>= 2.8.12`: Added unique client `id` field.
-- `>= 5.0`: Added optional `TYPE` filter.
-- `>= 6.2`: Added `laddr` field and the optional `ID` filter.

iredis/data/commands/client-no-evict.md

@@ -0,0 +1,11 @@
+The `CLIENT NO-EVICT` command sets the [client eviction](/topics/clients#client-eviction) mode for the current connection.
+
+When turned on and client eviction is configured, the current connection will be excluded from the client eviction process even if we're above the configured client eviction threshold.
+
+When turned off, the current client will be re-included in the pool of potential clients to be evicted (and evicted if needed).
+
+See [client eviction](/topics/clients#client-eviction) for more details.
+
+@return
+
+@simple-string-reply: `OK`.

iredis/data/commands/client-pause.md

@@ -1,62 +1,44 @@
-`CLIENT PAUSE` is a connections control command able to suspend all the Redis
+`CLIENT PAUSE` is a connections control command able to suspend all the Redis clients for the specified amount of time (in milliseconds).
-clients for the specified amount of time (in milliseconds).
 
 The command performs the following actions:
 
-- It stops processing all the pending commands from normal and pub/sub clients
+* It stops processing all the pending commands from normal and pub/sub clients for the given mode. However interactions with replicas will continue normally. Note that clients are formally paused when they try to execute a command, so no work is taken on the server side for inactive clients.
-  for the given mode. However interactions with replicas will continue normally.
+* However it returns OK to the caller ASAP, so the `CLIENT PAUSE` command execution is not paused by itself.
-  Note that clients are formally paused when they try to execute a command, so
+* When the specified amount of time has elapsed, all the clients are unblocked: this will trigger the processing of all the commands accumulated in the query buffer of every client during the pause.
-  no work is taken on the server side for inactive clients.
-- However it returns OK to the caller ASAP, so the `CLIENT PAUSE` command
-  execution is not paused by itself.
-- When the specified amount of time has elapsed, all the clients are unblocked:
-  this will trigger the processing of all the commands accumulated in the query
-  buffer of every client during the pause.
 
 Client pause currently supports two modes:
 
-- `ALL`: This is the default mode. All client commands are blocked.
+* `ALL`: This is the default mode. All client commands are blocked.
-- `WRITE`: Clients are only blocked if they attempt to execute a write command.
+* `WRITE`: Clients are only blocked if they attempt to execute a write command.
 
 For the `WRITE` mode, some commands have special behavior:
 
-- `EVAL`/`EVALSHA`: Will block client for all scripts.
+* `EVAL`/`EVALSHA`: Will block client for all scripts.
-- `PUBLISH`: Will block client.
+* `PUBLISH`: Will block client.
-- `PFCOUNT`: Will block client.
+* `PFCOUNT`: Will block client.
-- `WAIT`: Acknowledgements will be delayed, so this command will appear blocked.
+* `WAIT`: Acknowledgments will be delayed, so this command will appear blocked.
 
-This command is useful as it makes able to switch clients from a Redis instance
+This command is useful as it makes able to switch clients from a Redis instance to another one in a controlled way. For example during an instance upgrade the system administrator could do the following:
-to another one in a controlled way. For example during an instance upgrade the
-system administrator could do the following:
 
-- Pause the clients using `CLIENT PAUSE`
+* Pause the clients using `CLIENT PAUSE`
-- Wait a few seconds to make sure the replicas processed the latest replication
+* Wait a few seconds to make sure the replicas processed the latest replication stream from the master.
-  stream from the master.
+* Turn one of the replicas into a master.
-- Turn one of the replicas into a master.
+* Reconfigure clients to connect with the new master.
-- Reconfigure clients to connect with the new master.
 
-Since Redis 6.2, the recommended mode for client pause is `WRITE`. This mode
+Since Redis 6.2, the recommended mode for client pause is `WRITE`. This mode will stop all replication traffic, can be
-will stop all replication traffic, can be aborted with the `CLIENT UNPAUSE`
+aborted with the `CLIENT UNPAUSE` command, and allows reconfiguring the old master without risking accepting writes after the
-command, and allows reconfiguring the old master without risking accepting
+failover. This is also the mode used during cluster failover.
-writes after the failover. This is also the mode used during cluster failover.
 
-For versions before 6.2, it is possible to send `CLIENT PAUSE` in a MULTI/EXEC
+For versions before 6.2, it is possible to send `CLIENT PAUSE` in a MULTI/EXEC block together with the `INFO replication` command in order to get the current master offset at the time the clients are blocked. This way it is possible to wait for a specific offset in the replica side in order to make sure all the replication stream was processed.
-block together with the `INFO replication` command in order to get the current
-master offset at the time the clients are blocked. This way it is possible to
-wait for a specific offset in the replica side in order to make sure all the
-replication stream was processed.
 
 Since Redis 3.2.10 / 4.0.0, this command also prevents keys to be evicted or
 expired during the time clients are paused. This way the dataset is guaranteed
-to be static not just from the point of view of clients not being able to write,
+to be static not just from the point of view of clients not being able to write, but also from the point of view of internal operations.
-but also from the point of view of internal operations.
 
 @return
 
-@simple-string-reply: The command returns OK or an error if the timeout is
+@simple-string-reply: The command returns OK or an error if the timeout is invalid.
-invalid.
 
-@history
+## Behavior change history
 
-- `>= 3.2.10`: Client pause prevents client pause and key eviction as well.
+*   `>= 3.2.0`: Client pause prevents client pause and key eviction as well.
-- `>= 6.2`: CLIENT PAUSE WRITE mode added along with the `mode` option.

iredis/data/commands/client-reply.md

@@ -1,21 +1,13 @@
-Sometimes it can be useful for clients to completely disable replies from the
+Sometimes it can be useful for clients to completely disable replies from the Redis server. For example when the client sends fire and forget commands or performs a mass loading of data, or in caching contexts where new data is streamed constantly. In such contexts to use server time and bandwidth in order to send back replies to clients, which are going to be ignored, is considered wasteful.
-Redis server. For example when the client sends fire and forget commands or
-performs a mass loading of data, or in caching contexts where new data is
-streamed constantly. In such contexts to use server time and bandwidth in order
-to send back replies to clients, which are going to be ignored, is considered
-wasteful.
 
-The `CLIENT REPLY` command controls whether the server will reply the client's
+The `CLIENT REPLY` command controls whether the server will reply the client's commands. The following modes are available:
-commands. The following modes are available:
 
-- `ON`. This is the default mode in which the server returns a reply to every
+* `ON`. This is the default mode in which the server returns a reply to every command.
-  command.
+* `OFF`. In this mode the server will not reply to client commands.
-- `OFF`. In this mode the server will not reply to client commands.
+* `SKIP`. This mode skips the reply of command immediately after it.
-- `SKIP`. This mode skips the reply of command immediately after it.
 
 @return
 
-When called with either `OFF` or `SKIP` subcommands, no reply is made. When
+When called with either `OFF` or `SKIP` subcommands, no reply is made. When called with `ON`:
-called with `ON`:
 
 @simple-string-reply: `OK`.

iredis/data/commands/client-setname.md

@@ -1,27 +1,18 @@
 The `CLIENT SETNAME` command assigns a name to the current connection.
 
-The assigned name is displayed in the output of `CLIENT LIST` so that it is
+The assigned name is displayed in the output of `CLIENT LIST` so that it is possible to identify the client that performed a given connection.
-possible to identify the client that performed a given connection.
 
-For instance when Redis is used in order to implement a queue, producers and
+For instance when Redis is used in order to implement a queue, producers and consumers of messages may want to set the name of the connection according to their role.
-consumers of messages may want to set the name of the connection according to
-their role.
 
-There is no limit to the length of the name that can be assigned if not the
+There is no limit to the length of the name that can be assigned if not the usual limits of the Redis string type (512 MB). However it is not possible to use spaces in the connection name as this would violate the format of the `CLIENT LIST` reply.
-usual limits of the Redis string type (512 MB). However it is not possible to
-use spaces in the connection name as this would violate the format of the
-`CLIENT LIST` reply.
 
-It is possible to entirely remove the connection name setting it to the empty
+It is possible to entirely remove the connection name setting it to the empty string, that is not a valid connection name since it serves to this specific purpose.
-string, that is not a valid connection name since it serves to this specific
-purpose.
 
 The connection name can be inspected using `CLIENT GETNAME`.
 
 Every new connection starts without an assigned name.
 
-Tip: setting names to connections is a good way to debug connection leaks due to
+Tip: setting names to connections is a good way to debug connection leaks due to bugs in the application using Redis.
-bugs in the application using Redis.
 
 @return
 

iredis/data/commands/client-tracking.md

@@ -1,56 +1,33 @@
-This command enables the tracking feature of the Redis server, that is used for
+This command enables the tracking feature of the Redis server, that is used
-[server assisted client side caching](/topics/client-side-caching).
+for [server assisted client side caching](/topics/client-side-caching).
 
-When tracking is enabled Redis remembers the keys that the connection requested,
+When tracking is enabled Redis remembers the keys that the connection
-in order to send later invalidation messages when such keys are modified.
+requested, in order to send later invalidation messages when such keys are
-Invalidation messages are sent in the same connection (only available when the
+modified. Invalidation messages are sent in the same connection (only available
-RESP3 protocol is used) or redirected in a different connection (available also
+when the RESP3 protocol is used) or redirected in a different connection
-with RESP2 and Pub/Sub). A special _broadcasting_ mode is available where
+(available also with RESP2 and Pub/Sub). A special *broadcasting* mode is
-clients participating in this protocol receive every notification just
+available where clients participating in this protocol receive every
-subscribing to given key prefixes, regardless of the keys that they requested.
+notification just subscribing to given key prefixes, regardless of the
-Given the complexity of the argument please refer to
+keys that they requested. Given the complexity of the argument please
-[the main client side caching documentation](/topics/client-side-caching) for
+refer to [the main client side caching documentation](/topics/client-side-caching) for the details. This manual page is only a reference for the options of this subcommand.
-the details. This manual page is only a reference for the options of this
-subcommand.
 
 In order to enable tracking, use:
 
     CLIENT TRACKING on ... options ...
 
 The feature will remain active in the current connection for all its life,
-unless tracking is turned on with `CLIENT TRACKING off` at some point.
+unless tracking is turned off with `CLIENT TRACKING off` at some point.
 
-The following are the list of options that modify the behavior of the command
+The following are the list of options that modify the behavior of the
-when enabling tracking:
+command when enabling tracking:
 
-- `REDIRECT <id>`: send redirection messages to the connection with the
+* `REDIRECT <id>`: send invalidation messages to the connection with the specified ID. The connection must exist. You can get the ID of a connection using `CLIENT ID`. If the connection we are redirecting to is terminated, when in RESP3 mode the connection with tracking enabled will receive `tracking-redir-broken` push messages in order to signal the condition.
-  specified ID. The connection must exist, you can get the ID of such connection
+* `BCAST`: enable tracking in broadcasting mode. In this mode invalidation messages are reported for all the prefixes specified, regardless of the keys requested by the connection. Instead when the broadcasting mode is not enabled, Redis will track which keys are fetched using read-only commands, and will report invalidation messages only for such keys.
-  using `CLIENT ID`. If the connection we are redirecting to is terminated, when
+* `PREFIX <prefix>`: for broadcasting, register a given key prefix, so that notifications will be provided only for keys starting with this string. This option can be given multiple times to register multiple prefixes. If broadcasting is enabled without this option, Redis will send notifications for every key. You can't delete a single prefix, but you can delete all prefixes by disabling and re-enabling tracking. Using this option adds the additional time complexity of O(N^2), where N is the total number of prefixes tracked. 
-  in RESP3 mode the connection with tracking enabled will receive
+* `OPTIN`: when broadcasting is NOT active, normally don't track keys in read only commands, unless they are called immediately after a `CLIENT CACHING yes` command.
-  `tracking-redir-broken` push messages in order to signal the condition.
+* `OPTOUT`: when broadcasting is NOT active, normally track keys in read only commands, unless they are called immediately after a `CLIENT CACHING no` command.
-- `BCAST`: enable tracking in broadcasting mode. In this mode invalidation
+* `NOLOOP`: don't send notifications about keys modified by this connection itself.
-  messages are reported for all the prefixes specified, regardless of the keys
-  requested by the connection. Instead when the broadcasting mode is not
-  enabled, Redis will track which keys are fetched using read-only commands, and
-  will report invalidation messages only for such keys.
-- `PREFIX <prefix>`: for broadcasting, register a given key prefix, so that
-  notifications will be provided only for keys starting with this string. This
-  option can be given multiple times to register multiple prefixes. If
-  broadcasting is enabled without this option, Redis will send notifications for
-  every key. You can't delete a single prefix, but you can delete all prefixes
-  by disabling and re-enabling tracking. Using this option adds the additional
-  time complexity of O(N^2), where N is the total number of prefixes tracked.
-- `OPTIN`: when broadcasting is NOT active, normally don't track keys in read
-  only commands, unless they are called immediately after a `CLIENT CACHING yes`
-  command.
-- `OPTOUT`: when broadcasting is NOT active, normally track keys in read only
-  commands, unless they are called immediately after a `CLIENT CACHING no`
-  command.
-- `NOLOOP`: don't send notifications about keys modified by this connection
-  itself.
 
 @return
 
-@simple-string-reply: `OK` if the connection was successfully put in tracking
+@simple-string-reply: `OK` if the connection was successfully put in tracking mode or if the tracking mode was successfully disabled. Otherwise an error is returned.
-mode or if the tracking mode was successfully disabled. Otherwise an error is
-returned.

iredis/data/commands/client-trackinginfo.md

@@ -1,25 +1,18 @@
-The command returns information about the current client connection's use of the
+The command returns information about the current client connection's use of the [server assisted client side caching](/topics/client-side-caching) feature.
-[server assisted client side caching](/topics/client-side-caching) feature.
 
 @return
 
-@array-reply: a list of tracking information sections and their respective
+@array-reply: a list of tracking information sections and their respective values, specifically:
-values, specifically:
 
-- **flags**: A list of tracking flags used by the connection. The flags and
+* **flags**: A list of tracking flags used by the connection. The flags and their meanings are as follows:
-  their meanings are as follows:
+  * `off`: The connection isn't using server assisted client side caching.
-  - `off`: The connection isn't using server assisted client side caching.
+  * `on`: Server assisted client side caching is enabled for the connection.
-  - `on`: Server assisted client side caching is enabled for the connection.
+  * `bcast`: The client uses broadcasting mode.
-  - `bcast`: The client uses broadcasting mode.
+  * `optin`: The client does not cache keys by default.
-  - `optin`: The client does not cache keys by default.
+  * `optout`: The client caches keys by default.
-  - `optout`: The client caches keys by default.
+  * `caching-yes`: The next command will cache keys (exists only together with `optin`).
-  - `caching-yes`: The next command will cache keys (exists only together with
+  * `caching-no`: The next command won't cache keys (exists only together with `optout`).
-    `optin`).
+  * `noloop`: The client isn't notified about keys modified by itself.
-  - `caching-no`: The next command won't cache keys (exists only together with
+  * `broken_redirect`: The client ID used for redirection isn't valid anymore.
-    `optout`).
+* **redirect**: The client ID used for notifications redirection, or -1 when none.
-  - `noloop`: The client isn't notified about keys modified by itself.
+* **prefixes**: A list of key prefixes for which notifications are sent to the client.
-  - `broken_redirect`: The client ID used for redirection isn't valid anymore.
-- **redirect**: The client ID used for notifications redirection, or -1 when
-  none.
-- **prefixes**: A list of key prefixes for which notifications are sent to the
-  client.

iredis/data/commands/client-unblock.md

@@ -1,39 +1,34 @@
-This command can unblock, from a different connection, a client blocked in a
+This command can unblock, from a different connection, a client blocked in a blocking operation, such as for instance `BRPOP` or `XREAD` or `WAIT`.
-blocking operation, such as for instance `BRPOP` or `XREAD` or `WAIT`.
 
-By default the client is unblocked as if the timeout of the command was reached,
+By default the client is unblocked as if the timeout of the command was
-however if an additional (and optional) argument is passed, it is possible to
+reached, however if an additional (and optional) argument is passed, it is possible to specify the unblocking behavior, that can be **TIMEOUT** (the default) or **ERROR**. If **ERROR** is specified, the behavior is to unblock the client returning as error the fact that the client was force-unblocked. Specifically the client will receive the following error:
-specify the unblocking behavior, that can be **TIMEOUT** (the default) or
-**ERROR**. If **ERROR** is specified, the behavior is to unblock the client
-returning as error the fact that the client was force-unblocked. Specifically
-the client will receive the following error:
 
     -UNBLOCKED client unblocked via CLIENT UNBLOCK
 
-Note: of course as usually it is not guaranteed that the error text remains the
+Note: of course as usually it is not guaranteed that the error text remains
-same, however the error code will remain `-UNBLOCKED`.
+the same, however the error code will remain `-UNBLOCKED`.
 
-This command is useful especially when we are monitoring many keys with a
+This command is useful especially when we are monitoring many keys with
-limited number of connections. For instance we may want to monitor multiple
+a limited number of connections. For instance we may want to monitor multiple
 streams with `XREAD` without using more than N connections. However at some
-point the consumer process is informed that there is one more stream key to
+point the consumer process is informed that there is one more stream key
-monitor. In order to avoid using more connections, the best behavior would be to
+to monitor. In order to avoid using more connections, the best behavior would
-stop the blocking command from one of the connections in the pool, add the new
+be to stop the blocking command from one of the connections in the pool, add
-key, and issue the blocking command again.
+the new key, and issue the blocking command again.
 
-To obtain this behavior the following pattern is used. The process uses an
+To obtain this behavior the following pattern is used. The process uses
-additional _control connection_ in order to send the `CLIENT UNBLOCK` command if
+an additional *control connection* in order to send the `CLIENT UNBLOCK` command
-needed. In the meantime, before running the blocking operation on the other
+if needed. In the meantime, before running the blocking operation on the other
-connections, the process runs `CLIENT ID` in order to get the ID associated with
+connections, the process runs `CLIENT ID` in order to get the ID associated
-that connection. When a new key should be added, or when a key should no longer
+with that connection. When a new key should be added, or when a key should
-be monitored, the relevant connection blocking command is aborted by sending
+no longer be monitored, the relevant connection blocking command is aborted
-`CLIENT UNBLOCK` in the control connection. The blocking command will return and
+by sending `CLIENT UNBLOCK` in the control connection. The blocking command
-can be finally reissued.
+will return and can be finally reissued.
 
-This example shows the application in the context of Redis streams, however the
+This example shows the application in the context of Redis streams, however
-pattern is a general one and can be applied to other cases.
+the pattern is a general one and can be applied to other cases.
 
-@example
+@examples
 
 ```
 Connection A (blocking connection):
@@ -59,5 +54,5 @@ NULL
 
 @integer-reply, specifically:
 
-- `1` if the client was unblocked successfully.
+* `1` if the client was unblocked successfully.
-- `0` if the client wasn't unblocked.
+* `0` if the client wasn't unblocked.

iredis/data/commands/client-unpause.md

@@ -1,5 +1,4 @@
-`CLIENT UNPAUSE` is used to resume command processing for all clients that were
+`CLIENT UNPAUSE` is used to resume command processing for all clients that were paused by `CLIENT PAUSE`.
-paused by `CLIENT PAUSE`.
 
 @return
 

iredis/data/commands/client.md

@@ -0,0 +1,3 @@
+This is a container command for client connection commands.
+
+To see the list of available commands you can call `CLIENT HELP`.

iredis/data/commands/cluster-addslots.md

@@ -1,55 +1,51 @@
 This command is useful in order to modify a node's view of the cluster
-configuration. Specifically it assigns a set of hash slots to the node receiving
+configuration. Specifically it assigns a set of hash slots to the node
-the command. If the command is successful, the node will map the specified hash
+receiving the command. If the command is successful, the node will map
-slots to itself, and will start broadcasting the new configuration.
+the specified hash slots to itself, and will start broadcasting the new
+configuration.
 
 However note that:
 
-1. The command only works if all the specified slots are, from the point of view
+1. The command only works if all the specified slots are, from the point of view of the node receiving the command, currently not assigned. A node will refuse to take ownership for slots that already belong to some other node (including itself).
-   of the node receiving the command, currently not assigned. A node will refuse
-   to take ownership for slots that already belong to some other node (including
-   itself).
 2. The command fails if the same slot is specified multiple times.
-3. As a side effect of the command execution, if a slot among the ones specified
+3. As a side effect of the command execution, if a slot among the ones specified as argument is set as `importing`, this state gets cleared once the node assigns the (previously unbound) slot to itself.
-   as argument is set as `importing`, this state gets cleared once the node
-   assigns the (previously unbound) slot to itself.
 
 ## Example
 
-For example the following command assigns slots 1 2 3 to the node receiving the
+For example the following command assigns slots 1 2 3 to the node receiving
-command:
+the command:
 
     > CLUSTER ADDSLOTS 1 2 3
     OK
 
-However trying to execute it again results into an error since the slots are
+However trying to execute it again results into an error since the slots
-already assigned:
+are already assigned:
 
     > CLUSTER ADDSLOTS 1 2 3
     ERR Slot 1 is already busy
 
 ## Usage in Redis Cluster
 
-This command only works in cluster mode and is useful in the following Redis
+This command only works in cluster mode and is useful in the following
-Cluster operations:
+Redis Cluster operations:
 
-1. To create a new cluster ADDSLOTS is used in order to initially setup master
+1. To create a new cluster ADDSLOTS is used in order to initially setup master nodes splitting the available hash slots among them.
-   nodes splitting the available hash slots among them.
 2. In order to fix a broken cluster where certain slots are unassigned.
 
 ## Information about slots propagation and warnings
 
 Note that once a node assigns a set of slots to itself, it will start
-propagating this information in heartbeat packet headers. However the other
+propagating this information in heartbeat packet headers. However the
-nodes will accept the information only if they have the slot as not already
+other nodes will accept the information only if they have the slot as
-bound with another node, or if the configuration epoch of the node advertising
+not already bound with another node, or if the configuration epoch of the
-the new hash slot, is greater than the node currently listed in the table.
+node advertising the new hash slot, is greater than the node currently listed
+in the table.
 
 This means that this command should be used with care only by applications
-orchestrating Redis Cluster, like `redis-cli`, and the command if used out of
+orchestrating Redis Cluster, like `redis-cli`, and the command if used
-the right context can leave the cluster in a wrong state or cause data loss.
+out of the right context can leave the cluster in a wrong state or cause
+data loss.
 
 @return
 
-@simple-string-reply: `OK` if the command was successful. Otherwise an error is
+@simple-string-reply: `OK` if the command was successful. Otherwise an error is returned.
-returned.

iredis/data/commands/cluster-addslotsrange.md

@@ -0,0 +1,27 @@
+The `CLUSTER ADDSLOTSRANGE` is similar to the `CLUSTER ADDSLOTS` command in that they both assign hash slots to nodes.
+
+The difference between the two commands is that `ADDSLOTS` takes a list of slots to assign to the node, while `ADDSLOTSRANGE` takes a list of slot ranges (specified by start and end slots) to assign to the node.
+
+## Example
+
+To assign slots 1 2 3 4 5 to the node, the `ADDSLOTS` command is:
+
+    > CLUSTER ADDSLOTS 1 2 3 4 5
+    OK
+
+The same operation can be completed with the following `ADDSLOTSRANGE` command:
+
+    > CLUSTER ADDSLOTSRANGE 1 5
+    OK
+
+
+## Usage in Redis Cluster
+
+This command only works in cluster mode and is useful in the following Redis Cluster operations:
+
+1. To create a new cluster ADDSLOTSRANGE is used in order to initially setup master nodes splitting the available hash slots among them.
+2. In order to fix a broken cluster where certain slots are unassigned.
+
+@return
+
+@simple-string-reply: `OK` if the command was successful. Otherwise an error is returned.

iredis/data/commands/cluster-bumpepoch.md

@@ -1,15 +1,9 @@
 Advances the cluster config epoch.
 
-The `CLUSTER BUMPEPOCH` command triggers an increment to the cluster's config
+The `CLUSTER BUMPEPOCH` command triggers an increment to the cluster's config epoch from the connected node. The epoch will be incremented if the node's config epoch is zero, or if it is less than the cluster's greatest epoch.
-epoch from the connected node. The epoch will be incremented if the node's
-config epoch is zero, or if it is less than the cluster's greatest epoch.
 
-**Note:** config epoch management is performed internally by the cluster, and
+**Note:** config epoch management is performed internally by the cluster, and relies on obtaining a consensus of nodes. The `CLUSTER BUMPEPOCH` attempts to increment the config epoch **WITHOUT** getting the consensus, so using it may violate the "last failover wins" rule. Use it with caution.
-relies on obtaining a consensus of nodes. The `CLUSTER BUMPEPOCH` attempts to
-increment the config epoch **WITHOUT** getting the consensus, so using it may
-violate the "last failover wins" rule. Use it with caution.
 
 @return
 
-@simple-string-reply: `BUMPED` if the epoch was incremented, or `STILL` if the
+@simple-string-reply: `BUMPED` if the epoch was incremented, or `STILL` if the node already has the greatest config epoch in the cluster.
-node already has the greatest config epoch in the cluster.

iredis/data/commands/cluster-count-failure-reports.md

@@ -1,33 +1,21 @@
-The command returns the number of _failure reports_ for the specified node.
+The command returns the number of *failure reports* for the specified node.
-Failure reports are the way Redis Cluster uses in order to promote a `PFAIL`
+Failure reports are the way Redis Cluster uses in order to promote a
-state, that means a node is not reachable, to a `FAIL` state, that means that
+`PFAIL` state, that means a node is not reachable, to a `FAIL` state,
-the majority of masters in the cluster agreed within a window of time that the
+that means that the majority of masters in the cluster agreed within
-node is not reachable.
+a window of time that the node is not reachable.
 
 A few more details:
 
-- A node flags another node with `PFAIL` when the node is not reachable for a
+* A node flags another node with `PFAIL` when the node is not reachable for a time greater than the configured *node timeout*, which is a fundamental configuration parameter of a Redis Cluster.
-  time greater than the configured _node timeout_, which is a fundamental
+* Nodes in `PFAIL` state are provided in gossip sections of heartbeat packets.
-  configuration parameter of a Redis Cluster.
+* Every time a node processes gossip packets from other nodes, it creates (and refreshes the TTL if needed) **failure reports**, remembering that a given node said another given node is in `PFAIL` condition.
-- Nodes in `PFAIL` state are provided in gossip sections of heartbeat packets.
+* Each failure report has a time to live of two times the *node timeout* time.
-- Every time a node processes gossip packets from other nodes, it creates (and
+* If at a given time a node has another node flagged with `PFAIL`, and at the same time collected the majority of other master nodes *failure reports* about this node (including itself if it is a master), then it elevates the failure state of the node from `PFAIL` to `FAIL`, and broadcasts a message forcing all the nodes that can be reached to flag the node as `FAIL`.
-  refreshes the TTL if needed) **failure reports**, remembering that a given
-  node said another given node is in `PFAIL` condition.
-- Each failure report has a time to live of two times the _node timeout_ time.
-- If at a given time a node has another node flagged with `PFAIL`, and at the
-  same time collected the majority of other master nodes _failure reports_ about
-  this node (including itself if it is a master), then it elevates the failure
-  state of the node from `PFAIL` to `FAIL`, and broadcasts a message forcing all
-  the nodes that can be reached to flag the node as `FAIL`.
 
-This command returns the number of failure reports for the current node which
+This command returns the number of failure reports for the current node which are currently not expired (so received within two times the *node timeout* time). The count does not include what the node we are asking this count believes about the node ID we pass as argument, the count *only* includes the failure reports the node received from other nodes.
-are currently not expired (so received within two times the _node timeout_
-time). The count does not include what the node we are asking this count
-believes about the node ID we pass as argument, the count _only_ includes the
-failure reports the node received from other nodes.
 
-This command is mainly useful for debugging, when the failure detector of Redis
+This command is mainly useful for debugging, when the failure detector of
-Cluster is not operating as we believe it should.
+Redis Cluster is not operating as we believe it should.
 
 @return
 

iredis/data/commands/cluster-countkeysinslot.md

@@ -1,6 +1,7 @@
-Returns the number of keys in the specified Redis Cluster hash slot. The command
+Returns the number of keys in the specified Redis Cluster hash slot. The
-only queries the local data set, so contacting a node that is not serving the
+command only queries the local data set, so contacting a node
-specified hash slot will always result in a count of zero being returned.
+that is not serving the specified hash slot will always result in a count of
+zero being returned.
 
 ```
 > CLUSTER COUNTKEYSINSLOT 7000
@@ -9,5 +10,4 @@ specified hash slot will always result in a count of zero being returned.
 
 @return
 
-@integer-reply: The number of keys in the specified hash slot, or an error if
+@integer-reply: The number of keys in the specified hash slot, or an error if the hash slot is invalid.
-the hash slot is invalid.

iredis/data/commands/cluster-delslots.md

@@ -1,47 +1,48 @@
-In Redis Cluster, each node keeps track of which master is serving a particular
+In Redis Cluster, each node keeps track of which master is serving
-hash slot.
+a particular hash slot.
 
-The `DELSLOTS` command asks a particular Redis Cluster node to forget which
+The `CLUSTER DELSLOTS` command asks a particular Redis Cluster node to
-master is serving the hash slots specified as arguments.
+forget which master is serving the hash slots specified as arguments.
 
-In the context of a node that has received a `DELSLOTS` command and has
+In the context of a node that has received a `CLUSTER DELSLOTS` command and
-consequently removed the associations for the passed hash slots, we say those
+has consequently removed the associations for the passed hash slots,
-hash slots are _unbound_. Note that the existence of unbound hash slots occurs
+we say those hash slots are *unbound*. Note that the existence of
-naturally when a node has not been configured to handle them (something that can
+unbound hash slots occurs naturally when a node has not been
-be done with the `ADDSLOTS` command) and if it has not received any information
+configured to handle them (something that can be done with the
-about who owns those hash slots (something that it can learn from heartbeat or
+`CLUSTER ADDSLOTS` command) and if it has not received any information about
-update messages).
+who owns those hash slots (something that it can learn from heartbeat
+or update messages).
 
-If a node with unbound hash slots receives a heartbeat packet from another node
+If a node with unbound hash slots receives a heartbeat packet from
-that claims to be the owner of some of those hash slots, the association is
+another node that claims to be the owner of some of those hash
-established instantly. Moreover, if a heartbeat or update message is received
+slots, the association is established instantly. Moreover, if a
-with a configuration epoch greater than the node's own, the association is
+heartbeat or update message is received with a configuration epoch
-re-established.
+greater than the node's own, the association is re-established.
 
 However, note that:
 
-1. The command only works if all the specified slots are already associated with
+1. The command only works if all the specified slots are already
-   some node.
+associated with some node.
 2. The command fails if the same slot is specified multiple times.
-3. As a side effect of the command execution, the node may go into _down_ state
+3. As a side effect of the command execution, the node may go into
-   because not all hash slots are covered.
+*down* state because not all hash slots are covered.
 
 ## Example
 
-The following command removes the association for slots 5000 and 5001 from the
+The following command removes the association for slots 5000 and
-node receiving the command:
+5001 from the node receiving the command:
 
     > CLUSTER DELSLOTS 5000 5001
     OK
 
 ## Usage in Redis Cluster
 
-This command only works in cluster mode and may be useful for debugging and in
+This command only works in cluster mode and may be useful for
-order to manually orchestrate a cluster configuration when a new cluster is
+debugging and in order to manually orchestrate a cluster configuration
-created. It is currently not used by `redis-cli`, and mainly exists for API
+when a new cluster is created. It is currently not used by `redis-cli`,
-completeness.
+and mainly exists for API completeness.
 
 @return
 
-@simple-string-reply: `OK` if the command was successful. Otherwise an error is
+@simple-string-reply: `OK` if the command was successful. Otherwise
-returned.
+an error is returned.

iredis/data/commands/cluster-delslotsrange.md

@@ -0,0 +1,32 @@
+The `CLUSTER DELSLOTSRANGE` command is similar to the `CLUSTER DELSLOTS` command in that they both remove hash slots from the node.
+The difference is that `CLUSTER DELSLOTS` takes a list of hash slots to remove from the node, while `CLUSTER DELSLOTSRANGE` takes a list of slot ranges (specified by start and end slots) to remove from the node.
+
+## Example
+
+To remove slots 1 2 3 4 5 from the node, the `CLUSTER DELSLOTS` command is:
+
+    > CLUSTER DELSLOTS 1 2 3 4 5
+    OK
+
+The same operation can be completed with the following `CLUSTER DELSLOTSRANGE` command:
+
+    > CLUSTER DELSLOTSRANGE 1 5
+    OK
+
+However, note that:
+
+1. The command only works if all the specified slots are already associated with the node.
+2. The command fails if the same slot is specified multiple times.
+3. As a side effect of the command execution, the node may go into *down* state because not all hash slots are covered.
+
+## Usage in Redis Cluster
+
+This command only works in cluster mode and may be useful for
+debugging and in order to manually orchestrate a cluster configuration
+when a new cluster is created. It is currently not used by `redis-cli`,
+and mainly exists for API completeness.
+
+@return
+
+@simple-string-reply: `OK` if the command was successful. Otherwise
+an error is returned.

iredis/data/commands/cluster-failover.md

@@ -1,81 +1,67 @@
-This command, that can only be sent to a Redis Cluster replica node, forces the
+This command, that can only be sent to a Redis Cluster replica node, forces
-replica to start a manual failover of its master instance.
+the replica to start a manual failover of its master instance.
 
 A manual failover is a special kind of failover that is usually executed when
-there are no actual failures, but we wish to swap the current master with one of
+there are no actual failures, but we wish to swap the current master with one
-its replicas (which is the node we send the command to), in a safe way, without
+of its replicas (which is the node we send the command to), in a safe way,
-any window for data loss. It works in the following way:
+without any window for data loss. It works in the following way:
 
 1. The replica tells the master to stop processing queries from clients.
-2. The master replies to the replica with the current _replication offset_.
+2. The master replies to the replica with the current *replication offset*.
-3. The replica waits for the replication offset to match on its side, to make
+3. The replica waits for the replication offset to match on its side, to make sure it processed all the data from the master before it continues.
-   sure it processed all the data from the master before it continues.
+4. The replica starts a failover, obtains a new configuration epoch from the majority of the masters, and broadcasts the new configuration.
-4. The replica starts a failover, obtains a new configuration epoch from the
+5. The old master receives the configuration update: unblocks its clients and starts replying with redirection messages so that they'll continue the chat with the new master.
-   majority of the masters, and broadcasts the new configuration.
-5. The old master receives the configuration update: unblocks its clients and
-   starts replying with redirection messages so that they'll continue the chat
-   with the new master.
 
-This way clients are moved away from the old master to the new master atomically
+This way clients are moved away from the old master to the new master
-and only when the replica that is turning into the new master has processed all
+atomically and only when the replica that is turning into the new master
-of the replication stream from the old master.
+has processed all of the replication stream from the old master.
 
 ## FORCE option: manual failover when the master is down
 
 The command behavior can be modified by two options: **FORCE** and **TAKEOVER**.
 
 If the **FORCE** option is given, the replica does not perform any handshake
-with the master, that may be not reachable, but instead just starts a failover
+with the master, that may be not reachable, but instead just starts a
-ASAP starting from point 4. This is useful when we want to start a manual
+failover ASAP starting from point 4. This is useful when we want to start
-failover while the master is no longer reachable.
+a manual failover while the master is no longer reachable.
 
-However using **FORCE** we still need the majority of masters to be available in
+However using **FORCE** we still need the majority of masters to be available
-order to authorize the failover and generate a new configuration epoch for the
+in order to authorize the failover and generate a new configuration epoch
-replica that is going to become master.
+for the replica that is going to become master.
 
 ## TAKEOVER option: manual failover without cluster consensus
 
 There are situations where this is not enough, and we want a replica to failover
-without any agreement with the rest of the cluster. A real world use case for
+without any agreement with the rest of the cluster. A real world use case
-this is to mass promote replicas in a different data center to masters in order
+for this is to mass promote replicas in a different data center to masters
-to perform a data center switch, while all the masters are down or partitioned
+in order to perform a data center switch, while all the masters are down
-away.
+or partitioned away.
 
-The **TAKEOVER** option implies everything **FORCE** implies, but also does not
+The **TAKEOVER** option implies everything **FORCE** implies, but also does
-uses any cluster authorization in order to failover. A replica receiving
+not uses any cluster authorization in order to failover. A replica receiving
 `CLUSTER FAILOVER TAKEOVER` will instead:
 
-1. Generate a new `configEpoch` unilaterally, just taking the current greatest
+1. Generate a new `configEpoch` unilaterally, just taking the current greatest epoch available and incrementing it if its local configuration epoch is not already the greatest.
-   epoch available and incrementing it if its local configuration epoch is not
+2. Assign itself all the hash slots of its master, and propagate the new configuration to every node which is reachable ASAP, and eventually to every other node.
-   already the greatest.
-2. Assign itself all the hash slots of its master, and propagate the new
-   configuration to every node which is reachable ASAP, and eventually to every
-   other node.
 
-Note that **TAKEOVER violates the last-failover-wins principle** of Redis
+Note that **TAKEOVER violates the last-failover-wins principle** of Redis Cluster, since the configuration epoch generated by the replica violates the normal generation of configuration epochs in several ways:
-Cluster, since the configuration epoch generated by the replica violates the
-normal generation of configuration epochs in several ways:
 
-1. There is no guarantee that it is actually the higher configuration epoch,
+1. There is no guarantee that it is actually the higher configuration epoch, since, for example, we can use the **TAKEOVER** option within a minority, nor any message exchange is performed to generate the new configuration epoch.
-   since, for example, we can use the **TAKEOVER** option within a minority, nor
+2. If we generate a configuration epoch which happens to collide with another instance, eventually our configuration epoch, or the one of another instance with our same epoch, will be moved away using the *configuration epoch collision resolution algorithm*.
-   any message exchange is performed to generate the new configuration epoch.
-2. If we generate a configuration epoch which happens to collide with another
-   instance, eventually our configuration epoch, or the one of another instance
-   with our same epoch, will be moved away using the _configuration epoch
-   collision resolution algorithm_.
 
 Because of this the **TAKEOVER** option should be used with care.
 
 ## Implementation details and notes
 
-`CLUSTER FAILOVER`, unless the **TAKEOVER** option is specified, does not
+* `CLUSTER FAILOVER`, unless the **TAKEOVER** option is specified, does not execute a failover synchronously.
-execute a failover synchronously, it only _schedules_ a manual failover,
+  It only *schedules* a manual failover, bypassing the failure detection stage.
-bypassing the failure detection stage, so to check if the failover actually
+* An `OK` reply is no guarantee that the failover will succeed.
-happened, `CLUSTER NODES` or other means should be used in order to verify that
+* A replica can only be promoted to a master if it is known as a replica by a majority of the masters in the cluster.
-the state of the cluster changes after some time the command was sent.
+  If the replica is a new node that has just been added to the cluster (for example after upgrading it), it may not yet be known to all the masters in the cluster.
+  To check that the masters are aware of a new replica, you can send `CLUSTER NODES` or `CLUSTER REPLICAS` to each of the master nodes and check that it appears as a replica, before sending `CLUSTER FAILOVER` to the replica.
+* To check that the failover has actually happened you can use `ROLE`, `INFO REPLICATION` (which indicates "role:master" after successful failover), or `CLUSTER NODES` to verify that the state of the cluster has changed sometime after the command was sent.
+* To check if the failover has failed, check the replica's log for "Manual failover timed out", which is logged if the replica has given up after a few seconds.
 
 @return
 
-@simple-string-reply: `OK` if the command was accepted and a manual failover is
+@simple-string-reply: `OK` if the command was accepted and a manual failover is going to be attempted. An error if the operation cannot be executed, for example if we are talking with a node which is already a master.
-going to be attempted. An error if the operation cannot be executed, for example
-if we are talking with a node which is already a master.

iredis/data/commands/cluster-flushslots.md

@@ -1,7 +1,6 @@
 Deletes all slots from a node.
 
-The `CLUSTER FLUSHSLOTS` deletes all information about slots from the connected
+The `CLUSTER FLUSHSLOTS` deletes all information about slots from the connected node. It can only be called when the database is empty.
-node. It can only be called when the database is empty.
 
 @return
 

iredis/data/commands/cluster-forget.md

@@ -1,45 +1,45 @@
-The command is used in order to remove a node, specified via its node ID, from
+The command is used in order to remove a node, specified via its node ID,
-the set of _known nodes_ of the Redis Cluster node receiving the command. In
+from the set of *known nodes* of the Redis Cluster node receiving the command.
-other words the specified node is removed from the _nodes table_ of the node
+In other words the specified node is removed from the *nodes table* of the
-receiving the command.
+node receiving the command.
 
 Because when a given node is part of the cluster, all the other nodes
 participating in the cluster knows about it, in order for a node to be
-completely removed from a cluster, the `CLUSTER FORGET` command must be sent to
+completely removed from a cluster, the `CLUSTER FORGET` command must be
-all the remaining nodes, regardless of the fact they are masters or replicas.
+sent to all the remaining nodes, regardless of the fact they are masters
+or replicas.
 
-However the command cannot simply drop the node from the internal node table of
+However the command cannot simply drop the node from the internal node
-the node receiving the command, it also implements a ban-list, not allowing the
+table of the node receiving the command, it also implements a ban-list, not
-same node to be added again as a side effect of processing the _gossip section_
+allowing the same node to be added again as a side effect of processing the
-of the heartbeat packets received from other nodes.
+*gossip section* of the heartbeat packets received from other nodes.
 
 ## Details on why the ban-list is needed
 
-In the following example we'll show why the command must not just remove a given
+In the following example we'll show why the command must not just remove
-node from the nodes table, but also prevent it for being re-inserted again for
+a given node from the nodes table, but also prevent it for being re-inserted
-some time.
+again for some time.
 
-Let's assume we have four nodes, A, B, C and D. In order to end with just a
+Let's assume we have four nodes, A, B, C and D. In order to
-three nodes cluster A, B, C we may follow these steps:
+end with just a three nodes cluster A, B, C we may follow these steps:
 
 1. Reshard all the hash slots from D to nodes A, B, C.
 2. D is now empty, but still listed in the nodes table of A, B and C.
 3. We contact A, and send `CLUSTER FORGET D`.
 4. B sends node A a heartbeat packet, where node D is listed.
-5. A does no longer known node D (see step 3), so it starts an handshake with D.
+5. A does no longer known node D (see step 3), so it starts a handshake with D.
 6. D ends re-added in the nodes table of A.
 
 As you can see in this way removing a node is fragile, we need to send
-`CLUSTER FORGET` commands to all the nodes ASAP hoping there are no gossip
+`CLUSTER FORGET` commands to all the nodes ASAP hoping there are no
-sections processing in the meantime. Because of this problem the command
+gossip sections processing in the meantime. Because of this problem the
-implements a ban-list with an expire time for each entry.
+command implements a ban-list with an expire time for each entry.
 
 So what the command really does is:
 
 1. The specified node gets removed from the nodes table.
 2. The node ID of the removed node gets added to the ban-list, for 1 minute.
-3. The node will skip all the node IDs listed in the ban-list when processing
+3. The node will skip all the node IDs listed in the ban-list when processing gossip sections received in heartbeat packets from other nodes.
-   gossip sections received in heartbeat packets from other nodes.
 
 This way we have a 60 second window to inform all the nodes in the cluster that
 we want to remove a node.
@@ -49,11 +49,9 @@ we want to remove a node.
 The command does not succeed and returns an error in the following cases:
 
 1. The specified node ID is not found in the nodes table.
-2. The node receiving the command is a replica, and the specified node ID
+2. The node receiving the command is a replica, and the specified node ID identifies its current master.
-   identifies its current master.
 3. The node ID identifies the same node we are sending the command to.
 
 @return
 
-@simple-string-reply: `OK` if the command was executed successfully, otherwise
+@simple-string-reply: `OK` if the command was executed successfully, otherwise an error is returned.
-an error is returned.

iredis/data/commands/cluster-getkeysinslot.md

@@ -1,20 +1,20 @@
 The command returns an array of keys names stored in the contacted node and
-hashing to the specified hash slot. The maximum number of keys to return is
+hashing to the specified hash slot. The maximum number of keys to return
-specified via the `count` argument, so that it is possible for the user of this
+is specified via the `count` argument, so that it is possible for the user
-API to batch-processing keys.
+of this API to batch-processing keys.
 
 The main usage of this command is during rehashing of cluster slots from one
 node to another. The way the rehashing is performed is exposed in the Redis
-Cluster specification, or in a more simple to digest form, as an appendix of the
+Cluster specification, or in a more simple to digest form, as an appendix
-`CLUSTER SETSLOT` command documentation.
+of the `CLUSTER SETSLOT` command documentation.
 
 ```
 > CLUSTER GETKEYSINSLOT 7000 3
-"47344|273766|70329104160040|key_39015"
+1) "key_39015"
-"47344|273766|70329104160040|key_89793"
+2) "key_89793"
-"47344|273766|70329104160040|key_92937"
+3) "key_92937"
 ```
 
 @return
 
-@array-reply: From 0 to _count_ key names in a Redis array reply.
+@array-reply: From 0 to *count* key names in a Redis array reply.

iredis/data/commands/cluster-help.md

@@ -0,0 +1,5 @@
+The `CLUSTER HELP` command returns a helpful text describing the different subcommands.
+
+@return
+
+@array-reply: a list of subcommands and their descriptions

iredis/data/commands/cluster-info.md

@@ -1,6 +1,5 @@
-`CLUSTER INFO` provides `INFO` style information about Redis Cluster vital
+`CLUSTER INFO` provides `INFO` style information about Redis Cluster vital parameters.
-parameters. The following is a sample output, followed by the description of
+The following fields are always present in the reply:
-each field reported.
 
 ```
 cluster_state:ok
@@ -14,43 +13,40 @@ cluster_current_epoch:6
 cluster_my_epoch:2
 cluster_stats_messages_sent:1483972
 cluster_stats_messages_received:1483968
+total_cluster_links_buffer_limit_exceeded:0
 ```
 
-- `cluster_state`: State is `ok` if the node is able to receive queries. `fail`
+* `cluster_state`: State is `ok` if the node is able to receive queries. `fail` if there is at least one hash slot which is unbound (no node associated), in error state (node serving it is flagged with FAIL flag), or if the majority of masters can't be reached by this node.
-  if there is at least one hash slot which is unbound (no node associated), in
+* `cluster_slots_assigned`: Number of slots which are associated to some node (not unbound). This number should be 16384 for the node to work properly, which means that each hash slot should be mapped to a node.
-  error state (node serving it is flagged with FAIL flag), or if the majority of
+* `cluster_slots_ok`: Number of hash slots mapping to a node not in `FAIL` or `PFAIL` state.
-  masters can't be reached by this node.
+* `cluster_slots_pfail`: Number of hash slots mapping to a node in `PFAIL` state. Note that those hash slots still work correctly, as long as the `PFAIL` state is not promoted to `FAIL` by the failure detection algorithm. `PFAIL` only means that we are currently not able to talk with the node, but may be just a transient error.
-- `cluster_slots_assigned`: Number of slots which are associated to some node
+* `cluster_slots_fail`: Number of hash slots mapping to a node in `FAIL` state. If this number is not zero the node is not able to serve queries unless `cluster-require-full-coverage` is set to `no` in the configuration.
-  (not unbound). This number should be 16384 for the node to work properly,
+* `cluster_known_nodes`: The total number of known nodes in the cluster, including nodes in `HANDSHAKE` state that may not currently be proper members of the cluster.
-  which means that each hash slot should be mapped to a node.
+* `cluster_size`: The number of master nodes serving at least one hash slot in the cluster.
-- `cluster_slots_ok`: Number of hash slots mapping to a node not in `FAIL` or
+* `cluster_current_epoch`: The local `Current Epoch` variable. This is used in order to create unique increasing version numbers during fail overs.
-  `PFAIL` state.
+* `cluster_my_epoch`: The `Config Epoch` of the node we are talking with. This is the current configuration version assigned to this node.
-- `cluster_slots_pfail`: Number of hash slots mapping to a node in `PFAIL`
+* `cluster_stats_messages_sent`: Number of messages sent via the cluster node-to-node binary bus.
-  state. Note that those hash slots still work correctly, as long as the `PFAIL`
+* `cluster_stats_messages_received`: Number of messages received via the cluster node-to-node binary bus.
-  state is not promoted to `FAIL` by the failure detection algorithm. `PFAIL`
+* `total_cluster_links_buffer_limit_exceeded`: Accumulated count of cluster links freed due to exceeding the `cluster-link-sendbuf-limit` configuration.
-  only means that we are currently not able to talk with the node, but may be
-  just a transient error.
-- `cluster_slots_fail`: Number of hash slots mapping to a node in `FAIL` state.
-  If this number is not zero the node is not able to serve queries unless
-  `cluster-require-full-coverage` is set to `no` in the configuration.
-- `cluster_known_nodes`: The total number of known nodes in the cluster,
-  including nodes in `HANDSHAKE` state that may not currently be proper members
-  of the cluster.
-- `cluster_size`: The number of master nodes serving at least one hash slot in
-  the cluster.
-- `cluster_current_epoch`: The local `Current Epoch` variable. This is used in
-  order to create unique increasing version numbers during fail overs.
-- `cluster_my_epoch`: The `Config Epoch` of the node we are talking with. This
-  is the current configuration version assigned to this node.
-- `cluster_stats_messages_sent`: Number of messages sent via the cluster
-  node-to-node binary bus.
-- `cluster_stats_messages_received`: Number of messages received via the cluster
-  node-to-node binary bus.
 
-More information about the Current Epoch and Config Epoch variables are
+The following message-related fields may be included in the reply if the value is not 0:
-available in the Redis Cluster specification document.
+Each message type includes statistics on the number of messages sent and received.
+Here are the explanation of these fields:
+
+* `cluster_stats_messages_ping_sent` and `cluster_stats_messages_ping_received`: Cluster bus PING (not to be confused with the client command `PING`).
+* `cluster_stats_messages_pong_sent` and `cluster_stats_messages_pong_received`: PONG (reply to PING).
+* `cluster_stats_messages_meet_sent` and `cluster_stats_messages_meet_received`: Handshake message sent to a new node, either through gossip or `CLUSTER MEET`.
+* `cluster_stats_messages_fail_sent` and `cluster_stats_messages_fail_received`: Mark node xxx as failing.
+* `cluster_stats_messages_publish_sent` and `cluster_stats_messages_publish_received`: Pub/Sub Publish propagation, see [Pubsub](/topics/pubsub#pubsub).
+* `cluster_stats_messages_auth-req_sent` and `cluster_stats_messages_auth-req_received`: Replica initiated leader election to replace its master.
+* `cluster_stats_messages_auth-ack_sent` and `cluster_stats_messages_auth-ack_received`: Message indicating a vote during leader election.
+* `cluster_stats_messages_update_sent` and `cluster_stats_messages_update_received`: Another node slots configuration.
+* `cluster_stats_messages_mfstart_sent` and `cluster_stats_messages_mfstart_received`: Pause clients for manual failover.
+* `cluster_stats_messages_module_sent` and `cluster_stats_messages_module_received`: Module cluster API message.
+* `cluster_stats_messages_publishshard_sent` and `cluster_stats_messages_publishshard_received`: Pub/Sub Publish shard propagation, see [Sharded Pubsub](/topics/pubsub#sharded-pubsub).
+
+More information about the Current Epoch and Config Epoch variables are available in the [Redis Cluster specification document](/topics/cluster-spec#cluster-current-epoch).
 
 @return
 
-@bulk-string-reply: A map between named fields and values in the form of
+@bulk-string-reply: A map between named fields and values in the form of `<field>:<value>` lines separated by newlines composed by the two bytes `CRLF`.
-`<field>:<value>` lines separated by newlines composed by the two bytes `CRLF`.

iredis/data/commands/cluster-keyslot.md

@@ -1,31 +1,23 @@
-Returns an integer identifying the hash slot the specified key hashes to. This
+Returns an integer identifying the hash slot the specified key hashes to.
-command is mainly useful for debugging and testing, since it exposes via an API
+This command is mainly useful for debugging and testing, since it exposes
-the underlying Redis implementation of the hashing algorithm. Example use cases
+via an API the underlying Redis implementation of the hashing algorithm.
-for this command:
+Example use cases for this command:
 
-1. Client libraries may use Redis in order to test their own hashing algorithm,
+1. Client libraries may use Redis in order to test their own hashing algorithm, generating random keys and hashing them with both their local implementation and using Redis `CLUSTER KEYSLOT` command, then checking if the result is the same.
-   generating random keys and hashing them with both their local implementation
+2. Humans may use this command in order to check what is the hash slot, and then the associated Redis Cluster node, responsible for a given key.
-   and using Redis `CLUSTER KEYSLOT` command, then checking if the result is the
-   same.
-2. Humans may use this command in order to check what is the hash slot, and then
-   the associated Redis Cluster node, responsible for a given key.
 
 ## Example
 
 ```
 > CLUSTER KEYSLOT somekey
-11058
+(integer) 11058
 > CLUSTER KEYSLOT foo{hash_tag}
 (integer) 2515
 > CLUSTER KEYSLOT bar{hash_tag}
 (integer) 2515
 ```
 
-Note that the command implements the full hashing algorithm, including support
+Note that the command implements the full hashing algorithm, including support for **hash tags**, that is the special property of Redis Cluster key hashing algorithm, of hashing just what is between `{` and `}` if such a pattern is found inside the key name, in order to force multiple keys to be handled by the same node.
-for **hash tags**, that is the special property of Redis Cluster key hashing
-algorithm, of hashing just what is between `{` and `}` if such a pattern is
-found inside the key name, in order to force multiple keys to be handled by the
-same node.
 
 @return
 

iredis/data/commands/cluster-links.md

@@ -0,0 +1,48 @@
+Each node in a Redis Cluster maintains a pair of long-lived TCP link with each peer in the cluster: One for sending outbound messages towards the peer and one for receiving inbound messages from the peer.
+
+`CLUSTER LINKS` outputs information of all such peer links as an array, where each array element is a map that contains attributes and their values for an individual link.
+
+@examples
+
+The following is an example output:
+
+```
+> CLUSTER LINKS
+1)  1) "direction"
+    2) "to"
+    3) "node"
+    4) "8149d745fa551e40764fecaf7cab9dbdf6b659ae"
+    5) "create-time"
+    6) (integer) 1639442739375
+    7) "events"
+    8) "rw"
+    9) "send-buffer-allocated"
+   10) (integer) 4512
+   11) "send-buffer-used"
+   12) (integer) 0
+2)  1) "direction"
+    2) "from"
+    3) "node"
+    4) "8149d745fa551e40764fecaf7cab9dbdf6b659ae"
+    5) "create-time"
+    6) (integer) 1639442739411
+    7) "events"
+    8) "r"
+    9) "send-buffer-allocated"
+   10) (integer) 0
+   11) "send-buffer-used"
+   12) (integer) 0
+```
+
+Each map is composed of the following attributes of the corresponding cluster link and their values:
+
+1. `direction`: This link is established by the local node `to` the peer, or accepted by the local node `from` the peer.
+2. `node`: The node id of the peer.
+3. `create-time`: Creation time of the link. (In the case of a `to` link, this is the time when the TCP link is created by the local node, not the time when it is actually established.)
+4. `events`: Events currently registered for the link. `r` means readable event, `w` means writable event.
+5. `send-buffer-allocated`: Allocated size of the link's send buffer, which is used to buffer outgoing messages toward the peer.
+6. `send-buffer-used`: Size of the portion of the link's send buffer that is currently holding data(messages).
+
+@return
+
+@array-reply: An array of maps where each map contains various attributes and their values of a cluster link.

iredis/data/commands/cluster-meet.md

@@ -2,54 +2,41 @@
 support enabled, into a working cluster.
 
 The basic idea is that nodes by default don't trust each other, and are
-considered unknown, so that it is unlikely that different cluster nodes will mix
+considered unknown, so that it is unlikely that different cluster nodes will
-into a single one because of system administration errors or network addresses
+mix into a single one because of system administration errors or network
-modifications.
+addresses modifications.
 
 So in order for a given node to accept another one into the list of nodes
 composing a Redis Cluster, there are only two ways:
 
-1. The system administrator sends a `CLUSTER MEET` command to force a node to
+1. The system administrator sends a `CLUSTER MEET` command to force a node to meet another one.
-   meet another one.
+2. An already known node sends a list of nodes in the gossip section that we are not aware of. If the receiving node trusts the sending node as a known node, it will process the gossip section and send a handshake to the nodes that are still not known.
-2. An already known node sends a list of nodes in the gossip section that we are
-   not aware of. If the receiving node trusts the sending node as a known node,
-   it will process the gossip section and send an handshake to the nodes that
-   are still not known.
 
-Note that Redis Cluster needs to form a full mesh (each node is connected with
+Note that Redis Cluster needs to form a full mesh (each node is connected with each other node), but in order to create a cluster, there is no need to send all the `CLUSTER MEET` commands needed to form the full mesh. What matter is to send enough `CLUSTER MEET` messages so that each node can reach each other node through a *chain of known nodes*. Thanks to the exchange of gossip information in heartbeat packets, the missing links will be created.
-each other node), but in order to create a cluster, there is no need to send all
-the `CLUSTER MEET` commands needed to form the full mesh. What matter is to send
-enough `CLUSTER MEET` messages so that each node can reach each other node
-through a _chain of known nodes_. Thanks to the exchange of gossip information
-in heartbeat packets, the missing links will be created.
 
-So, if we link node A with node B via `CLUSTER MEET`, and B with C, A and C will
+So, if we link node A with node B via `CLUSTER MEET`, and B with C, A and C will find their ways to handshake and create a link.
-find their ways to handshake and create a link.
 
-Another example: if we imagine a cluster formed of the following four nodes
+Another example: if we imagine a cluster formed of the following four nodes called A, B, C and D, we may send just the following set of commands to A:
-called A, B, C and D, we may send just the following set of commands to A:
 
 1. `CLUSTER MEET B-ip B-port`
 2. `CLUSTER MEET C-ip C-port`
 3. `CLUSTER MEET D-ip D-port`
 
-As a side effect of `A` knowing and being known by all the other nodes, it will
+As a side effect of `A` knowing and being known by all the other nodes, it will send gossip sections in the heartbeat packets that will allow each other node to create a link with each other one, forming a full mesh in a matter of seconds, even if the cluster is large.
-send gossip sections in the heartbeat packets that will allow each other node to
-create a link with each other one, forming a full mesh in a matter of seconds,
-even if the cluster is large.
 
-Moreover `CLUSTER MEET` does not need to be reciprocal. If I send the command to
+Moreover `CLUSTER MEET` does not need to be reciprocal. If I send the command to A in order to join B, I don't need to also send it to B in order to join A.
-A in order to join B, I don't need to also send it to B in order to join A.
+
+If the optional `cluster_bus_port` argument is not provided, the default of port + 10000 will be used.
 
 ## Implementation details: MEET and PING packets
 
 When a given node receives a `CLUSTER MEET` message, the node specified in the
-command still does not know the node we sent the command to. So in order for the
+command still does not know the node we sent the command to. So in order for
-node to force the receiver to accept it as a trusted node, it sends a `MEET`
+the node to force the receiver to accept it as a trusted node, it sends a
-packet instead of a `PING` packet. The two packets have exactly the same format,
+`MEET` packet instead of a `PING` packet. The two packets have exactly the
-but the former forces the receiver to acknowledge the node as trusted.
+same format, but the former forces the receiver to acknowledge the node as
+trusted.
 
 @return
 
-@simple-string-reply: `OK` if the command was successful. If the address or port
+@simple-string-reply: `OK` if the command was successful. If the address or port specified are invalid an error is returned.
-specified are invalid an error is returned.

iredis/data/commands/cluster-myid.md

@@ -1,8 +1,7 @@
 Returns the node's id.
 
-The `CLUSTER MYID` command returns the unique, auto-generated identifier that is
+The `CLUSTER MYID` command returns the unique, auto-generated identifier that is associated with the connected cluster node.
-associated with the connected cluster node.
 
 @return
 
-@bulk-string-reply: The node id.
+@bulk-string-reply: The node id.

iredis/data/commands/cluster-nodes.md

@@ -4,20 +4,21 @@ nodes, their flags, properties and assigned slots, and so forth.
 
 `CLUSTER NODES` provides all this information, that is, the current cluster
 configuration of the node we are contacting, in a serialization format which
-happens to be exactly the same as the one used by Redis Cluster itself in order
+happens to be exactly the same as the one used by Redis Cluster itself in
-to store on disk the cluster state (however the on disk cluster state has a few
+order to store on disk the cluster state (however the on disk cluster state
-additional info appended at the end).
+has a few additional info appended at the end).
 
-Note that normally clients willing to fetch the map between Cluster hash slots
+Note that normally clients willing to fetch the map between Cluster
-and node addresses should use `CLUSTER SLOTS` instead. `CLUSTER NODES`, that
+hash slots and node addresses should use `CLUSTER SLOTS` instead.
-provides more information, should be used for administrative tasks, debugging,
+`CLUSTER NODES`, that provides more information, should be used for
-and configuration inspections. It is also used by `redis-cli` in order to manage
+administrative tasks, debugging, and configuration inspections.
-a cluster.
+It is also used by `redis-cli` in order to manage a cluster.
 
 ## Serialization format
 
-The output of the command is just a space-separated CSV string, where each line
+The output of the command is just a space-separated CSV string, where
-represents a node in the cluster. The following is an example of output:
+each line represents a node in the cluster. The following is an example
+of output:
 
 ```
 07c37dfeb235213a872192d90877d0cd55635b91 127.0.0.1:30004@31004 slave e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca 0 1426238317239 4 connected
@@ -36,113 +37,74 @@ Each line is composed of the following fields:
 
 The meaning of each filed is the following:
 
-1. `id`: The node ID, a 40 characters random string generated when a node is
+1. `id`: The node ID, a 40 characters random string generated when a node is created and never changed again (unless `CLUSTER RESET HARD` is used).
-   created and never changed again (unless `CLUSTER RESET HARD` is used).
+2. `ip:port@cport`: The node address where clients should contact the node to run queries.
-2. `ip:port@cport`: The node address where clients should contact the node to
+3. `flags`: A list of comma separated flags: `myself`, `master`, `slave`, `fail?`, `fail`, `handshake`, `noaddr`, `nofailover`, `noflags`. Flags are explained in detail in the next section.
-   run queries.
+4. `master`: If the node is a replica, and the master is known, the master node ID, otherwise the "-" character.
-3. `flags`: A list of comma separated flags: `myself`, `master`, `slave`,
+5. `ping-sent`: Milliseconds unix time at which the currently active ping was sent, or zero if there are no pending pings.
-   `fail?`, `fail`, `handshake`, `noaddr`, `nofailover`, `noflags`. Flags are
-   explained in detail in the next section.
-4. `master`: If the node is a replica, and the master is known, the master node
-   ID, otherwise the "-" character.
-5. `ping-sent`: Milliseconds unix time at which the currently active ping was
-   sent, or zero if there are no pending pings.
 6. `pong-recv`: Milliseconds unix time the last pong was received.
-7. `config-epoch`: The configuration epoch (or version) of the current node (or
+7. `config-epoch`: The configuration epoch (or version) of the current node (or of the current master if the node is a replica). Each time there is a failover, a new, unique, monotonically increasing configuration epoch is created. If multiple nodes claim to serve the same hash slots, the one with higher configuration epoch wins.
-   of the current master if the node is a replica). Each time there is a
+8. `link-state`: The state of the link used for the node-to-node cluster bus. We use this link to communicate with the node. Can be `connected` or `disconnected`.
-   failover, a new, unique, monotonically increasing configuration epoch is
+9. `slot`: A hash slot number or range. Starting from argument number 9, but there may be up to 16384 entries in total (limit never reached). This is the list of hash slots served by this node. If the entry is just a number, is parsed as such. If it is a range, it is in the form `start-end`, and means that the node is responsible for all the hash slots from `start` to `end` including the start and end values.
-   created. If multiple nodes claim to serve the same hash slots, the one with
-   higher configuration epoch wins.
-8. `link-state`: The state of the link used for the node-to-node cluster bus. We
-   use this link to communicate with the node. Can be `connected` or
-   `disconnected`.
-9. `slot`: A hash slot number or range. Starting from argument number 9, but
-   there may be up to 16384 entries in total (limit never reached). This is the
-   list of hash slots served by this node. If the entry is just a number, is
-   parsed as such. If it is a range, it is in the form `start-end`, and means
-   that the node is responsible for all the hash slots from `start` to `end`
-   including the start and end values.
 
 Meaning of the flags (field number 3):
 
-- `myself`: The node you are contacting.
+* `myself`: The node you are contacting.
-- `master`: Node is a master.
+* `master`: Node is a master.
-- `slave`: Node is a replica.
+* `slave`: Node is a replica.
-- `fail?`: Node is in `PFAIL` state. Not reachable for the node you are
+* `fail?`: Node is in `PFAIL` state. Not reachable for the node you are contacting, but still logically reachable (not in `FAIL` state).
-  contacting, but still logically reachable (not in `FAIL` state).
+* `fail`: Node is in `FAIL` state. It was not reachable for multiple nodes that promoted the `PFAIL` state to `FAIL`.
-- `fail`: Node is in `FAIL` state. It was not reachable for multiple nodes that
+* `handshake`: Untrusted node, we are handshaking.
-  promoted the `PFAIL` state to `FAIL`.
+* `noaddr`: No address known for this node.
-- `handshake`: Untrusted node, we are handshaking.
+* `nofailover`: Replica will not try to failover.
-- `noaddr`: No address known for this node.
+* `noflags`: No flags at all.
-- `nofailover`: Replica will not try to failover.
-- `noflags`: No flags at all.
 
 ## Notes on published config epochs
 
 Replicas broadcast their master's config epochs (in order to get an `UPDATE`
-message if they are found to be stale), so the real config epoch of the replica
+message if they are found to be stale), so the real config epoch of the
-(which is meaningless more or less, since they don't serve hash slots) can be
+replica (which is meaningless more or less, since they don't serve hash slots)
-only obtained checking the node flagged as `myself`, which is the entry of the
+can be only obtained checking the node flagged as `myself`, which is the entry
-node we are asking to generate `CLUSTER NODES` output. The other replicas epochs
+of the node we are asking to generate `CLUSTER NODES` output. The other
-reflect what they publish in heartbeat packets, which is, the configuration
+replicas epochs reflect what they publish in heartbeat packets, which is, the
-epoch of the masters they are currently replicating.
+configuration epoch of the masters they are currently replicating.
 
 ## Special slot entries
 
-Normally hash slots associated to a given node are in one of the following
+Normally hash slots associated to a given node are in one of the following formats,
-formats, as already explained above:
+as already explained above:
 
 1. Single number: 3894
 2. Range: 3900-4000
 
-However node hash slots can be in a special state, used in order to communicate
+However node hash slots can be in a special state, used in order to communicate errors after a node restart (mismatch between the keys in the AOF/RDB file, and the node hash slots configuration), or when there is a resharding operation in progress. This two states are **importing** and **migrating**.
-errors after a node restart (mismatch between the keys in the AOF/RDB file, and
-the node hash slots configuration), or when there is a resharding operation in
-progress. This two states are **importing** and **migrating**.
 
-The meaning of the two states is explained in the Redis Specification, however
+The meaning of the two states is explained in the Redis Specification, however the gist of the two states is the following:
-the gist of the two states is the following:
 
-- **Importing** slots are yet not part of the nodes hash slot, there is a
+* **Importing** slots are yet not part of the nodes hash slot, there is a migration in progress. The node will accept queries about these slots only if the `ASK` command is used.
-  migration in progress. The node will accept queries about these slots only if
+* **Migrating** slots are assigned to the node, but are being migrated to some other node. The node will accept queries if all the keys in the command exist already, otherwise it will emit what is called an **ASK redirection**, to force new keys creation directly in the importing node.
-  the `ASK` command is used.
-- **Migrating** slots are assigned to the node, but are being migrated to some
-  other node. The node will accept queries if all the keys in the command exist
-  already, otherwise it will emit what is called an **ASK redirection**, to
-  force new keys creation directly in the importing node.
 
-Importing and migrating slots are emitted in the `CLUSTER NODES` output as
+Importing and migrating slots are emitted in the `CLUSTER NODES` output as follows:
-follows:
 
-- **Importing slot:** `[slot_number-<-importing_from_node_id]`
+* **Importing slot:** `[slot_number-<-importing_from_node_id]`
-- **Migrating slot:** `[slot_number->-migrating_to_node_id]`
+* **Migrating slot:** `[slot_number->-migrating_to_node_id]`
 
 The following are a few examples of importing and migrating slots:
 
-- `[93-<-292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]`
+* `[93-<-292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]`
-- `[1002-<-67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1]`
+* `[1002-<-67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1]`
-- `[77->-e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca]`
+* `[77->-e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca]`
-- `[16311->-292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]`
+* `[16311->-292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]`
 
-Note that the format does not have any space, so `CLUSTER NODES` output format
+Note that the format does not have any space, so `CLUSTER NODES` output format is plain CSV with space as separator even when this special slots are emitted. However a complete parser for the format should be able to handle them.
-is plain CSV with space as separator even when this special slots are emitted.
-However a complete parser for the format should be able to handle them.
 
 Note that:
 
-1. Migration and importing slots are only added to the node flagged as `myself`.
+1. Migration and importing slots are only added to the node flagged as `myself`. This information is local to a node, for its own slots.
-   This information is local to a node, for its own slots.
+2. Importing and migrating slots are provided as **additional info**. If the node has a given hash slot assigned, it will be also a plain number in the list of hash slots, so clients that don't have a clue about hash slots migrations can just skip this special fields.
-2. Importing and migrating slots are provided as **additional info**. If the
-   node has a given hash slot assigned, it will be also a plain number in the
-   list of hash slots, so clients that don't have a clue about hash slots
-   migrations can just skip this special fields.
 
 @return
 
 @bulk-string-reply: The serialized cluster configuration.
 
-**A note about the word slave used in this man page and command name**: Starting
+**A note about the word slave used in this man page and command name**: Starting with Redis 5, if not for backward compatibility, the Redis project no longer uses the word slave. Unfortunately in this command the word slave is part of the protocol, so we'll be able to remove such occurrences only when this API will be naturally deprecated.
-with Redis 5, if not for backward compatibility, the Redis project no longer
-uses the word slave. Unfortunately in this command the word slave is part of the
-protocol, so we'll be able to remove such occurrences only when this API will be
-naturally deprecated.

iredis/data/commands/cluster-replicas.md

@@ -1,15 +1,14 @@
 The command provides a list of replica nodes replicating from the specified
-master node. The list is provided in the same format used by `CLUSTER NODES`
+master node. The list is provided in the same format used by `CLUSTER NODES` (please refer to its documentation for the specification of the format).
-(please refer to its documentation for the specification of the format).
 
-The command will fail if the specified node is not known or if it is not a
+The command will fail if the specified node is not known or if it is not
-master according to the node table of the node receiving the command.
+a master according to the node table of the node receiving the command.
 
-Note that if a replica is added, moved, or removed from a given master node, and
+Note that if a replica is added, moved, or removed from a given master node,
-we ask `CLUSTER REPLICAS` to a node that has not yet received the configuration
+and we ask `CLUSTER REPLICAS` to a node that has not yet received the
-update, it may show stale information. However eventually (in a matter of
+configuration update, it may show stale information. However eventually
-seconds if there are no network partitions) all the nodes will agree about the
+(in a matter of seconds if there are no network partitions) all the nodes
-set of nodes associated with a given master.
+will agree about the set of nodes associated with a given master.
 
 @return
 

iredis/data/commands/cluster-replicate.md

@@ -1,6 +1,6 @@
-The command reconfigures a node as a replica of the specified master. If the
+The command reconfigures a node as a replica of the specified master.
-node receiving the command is an _empty master_, as a side effect of the
+If the node receiving the command is an *empty master*, as a side effect
-command, the node role is changed from master to replica.
+of the command, the node role is changed from master to replica.
 
 Once a node is turned into the replica of another master node, there is no need
 to inform the other cluster nodes about the change: heartbeat packets exchanged
@@ -9,21 +9,18 @@ between nodes will propagate the new configuration automatically.
 A replica will always accept the command, assuming that:
 
 1. The specified node ID exists in its nodes table.
-2. The specified node ID does not identify the instance we are sending the
+2. The specified node ID does not identify the instance we are sending the command to.
-   command to.
 3. The specified node ID is a master.
 
-If the node receiving the command is not already a replica, but is a master, the
+If the node receiving the command is not already a replica, but is a master,
-command will only succeed, and the node will be converted into a replica, only
+the command will only succeed, and the node will be converted into a replica,
-if the following additional conditions are met:
+only if the following additional conditions are met:
 
 1. The node is not serving any hash slots.
 2. The node is empty, no keys are stored at all in the key space.
 
-If the command succeeds the new replica will immediately try to contact its
+If the command succeeds the new replica will immediately try to contact its master in order to replicate from it.
-master in order to replicate from it.
 
 @return
 
-@simple-string-reply: `OK` if the command was executed successfully, otherwise
+@simple-string-reply: `OK` if the command was executed successfully, otherwise an error is returned.
-an error is returned.

iredis/data/commands/cluster-reset.md

@@ -1,29 +1,25 @@
-Reset a Redis Cluster node, in a more or less drastic way depending on the reset
+Reset a Redis Cluster node, in a more or less drastic way depending on the
-type, that can be **hard** or **soft**. Note that this command **does not work
+reset type, that can be **hard** or **soft**. Note that this command
-for masters if they hold one or more keys**, in that case to completely reset a
+**does not work for masters if they hold one or more keys**, in that case
-master node keys must be removed first, e.g. by using `FLUSHALL` first, and then
+to completely reset a master node keys must be removed first, e.g. by using `FLUSHALL` first,
-`CLUSTER RESET`.
+and then `CLUSTER RESET`.
 
 Effects on the node:
 
 1. All the other nodes in the cluster are forgotten.
-2. All the assigned / open slots are reset, so the slots-to-nodes mapping is
+2. All the assigned / open slots are reset, so the slots-to-nodes mapping is totally cleared.
-   totally cleared.
+3. If the node is a replica it is turned into an (empty) master. Its dataset is flushed, so at the end the node will be an empty master.
-3. If the node is a replica it is turned into an (empty) master. Its dataset is
-   flushed, so at the end the node will be an empty master.
 4. **Hard reset only**: a new Node ID is generated.
 5. **Hard reset only**: `currentEpoch` and `configEpoch` vars are set to 0.
-6. The new configuration is persisted on disk in the node cluster configuration
+6. The new configuration is persisted on disk in the node cluster configuration file.
-   file.
 
-This command is mainly useful to re-provision a Redis Cluster node in order to
+This command is mainly useful to re-provision a Redis Cluster node
-be used in the context of a new, different cluster. The command is also
+in order to be used in the context of a new, different cluster. The command
-extensively used by the Redis Cluster testing framework in order to reset the
+is also extensively used by the Redis Cluster testing framework in order to
-state of the cluster every time a new test unit is executed.
+reset the state of the cluster every time a new test unit is executed.
 
 If no reset type is specified, the default is **soft**.
 
 @return
 
-@simple-string-reply: `OK` if the command was successful. Otherwise an error is
+@simple-string-reply: `OK` if the command was successful. Otherwise an error is returned.
-returned.

iredis/data/commands/cluster-saveconfig.md

@@ -1,14 +1,14 @@
 Forces a node to save the `nodes.conf` configuration on disk. Before to return
-the command calls `fsync(2)` in order to make sure the configuration is flushed
+the command calls `fsync(2)` in order to make sure the configuration is
-on the computer disk.
+flushed on the computer disk.
 
-This command is mainly used in the event a `nodes.conf` node state file gets
+This command is mainly used in the event a `nodes.conf` node state file
-lost / deleted for some reason, and we want to generate it again from scratch.
+gets lost / deleted for some reason, and we want to generate it again from
-It can also be useful in case of mundane alterations of a node cluster
+scratch. It can also be useful in case of mundane alterations of a node cluster
 configuration via the `CLUSTER` command in order to ensure the new configuration
-is persisted on disk, however all the commands should normally be able to auto
+is persisted on disk, however all the commands should normally be able to
-schedule to persist the configuration on disk when it is important to do so for
+auto schedule to persist the configuration on disk when it is important
-the correctness of the system in the event of a restart.
+to do so for the correctness of the system in the event of a restart.
 
 @return
 

iredis/data/commands/cluster-set-config-epoch.md

@@ -1,25 +1,25 @@
-This command sets a specific _config epoch_ in a fresh node. It only works when:
+This command sets a specific *config epoch* in a fresh node. It only works when:
 
 1. The nodes table of the node is empty.
-2. The node current _config epoch_ is zero.
+2. The node current *config epoch* is zero.
 
 These prerequisites are needed since usually, manually altering the
 configuration epoch of a node is unsafe, we want to be sure that the node with
 the higher configuration epoch value (that is the last that failed over) wins
 over other nodes in claiming the hash slots ownership.
 
-However there is an exception to this rule, and it is when a new cluster is
+However there is an exception to this rule, and it is when a new
-created from scratch. Redis Cluster _config epoch collision resolution_
+cluster is created from scratch. Redis Cluster *config epoch collision
-algorithm can deal with new nodes all configured with the same configuration at
+resolution* algorithm can deal with new nodes all configured with the
-startup, but this process is slow and should be the exception, only to make sure
+same configuration at startup, but this process is slow and should be
-that whatever happens, two more nodes eventually always move away from the state
+the exception, only to make sure that whatever happens, two more
-of having the same configuration epoch.
+nodes eventually always move away from the state of having the same
+configuration epoch.
 
-So, using `CONFIG SET-CONFIG-EPOCH`, when a new cluster is created, we can
+So, using `CLUSTER SET-CONFIG-EPOCH`, when a new cluster is created, we can
-assign a different progressive configuration epoch to each node before joining
+assign a different progressive configuration epoch to each node before
-the cluster together.
+joining the cluster together.
 
 @return
 
-@simple-string-reply: `OK` if the command was executed successfully, otherwise
+@simple-string-reply: `OK` if the command was executed successfully, otherwise an error is returned.
-an error is returned.

iredis/data/commands/cluster-setslot.md

@@ -1,133 +1,85 @@
-`CLUSTER SETSLOT` is responsible of changing the state of a hash slot in the
+`CLUSTER SETSLOT` is responsible of changing the state of a hash slot in the receiving node in different ways. It can, depending on the subcommand used:
-receiving node in different ways. It can, depending on the subcommand used:
 
-1. `MIGRATING` subcommand: Set a hash slot in _migrating_ state.
+1. `MIGRATING` subcommand: Set a hash slot in *migrating* state.
-2. `IMPORTING` subcommand: Set a hash slot in _importing_ state.
+2. `IMPORTING` subcommand: Set a hash slot in *importing* state.
 3. `STABLE` subcommand: Clear any importing / migrating state from hash slot.
 4. `NODE` subcommand: Bind the hash slot to a different node.
 
-The command with its set of subcommands is useful in order to start and end
+The command with its set of subcommands is useful in order to start and end cluster live resharding operations, which are accomplished by setting a hash slot in migrating state in the source node, and importing state in the destination node.
-cluster live resharding operations, which are accomplished by setting a hash
-slot in migrating state in the source node, and importing state in the
-destination node.
 
-Each subcommand is documented below. At the end you'll find a description of how
+Each subcommand is documented below. At the end you'll find a description of
-live resharding is performed using this command and other related commands.
+how live resharding is performed using this command and other related commands.
 
 ## CLUSTER SETSLOT `<slot>` MIGRATING `<destination-node-id>`
 
-This subcommand sets a slot to _migrating_ state. In order to set a slot in this
+This subcommand sets a slot to *migrating* state. In order to set a slot
-state, the node receiving the command must be the hash slot owner, otherwise an
+in this state, the node receiving the command must be the hash slot owner,
-error is returned.
+otherwise an error is returned.
 
 When a slot is set in migrating state, the node changes behavior in the
 following way:
 
-1. If a command is received about an existing key, the command is processed as
+1. If a command is received about an existing key, the command is processed as usually.
-   usually.
+2. If a command is received about a key that does not exists, an `ASK` redirection is emitted by the node, asking the client to retry only that specific query into `destination-node`. In this case the client should not update its hash slot to node mapping.
-2. If a command is received about a key that does not exists, an `ASK`
+3. If the command contains multiple keys, in case none exist, the behavior is the same as point 2, if all exist, it is the same as point 1, however if only a partial number of keys exist, the command emits a `TRYAGAIN` error in order for the keys interested to finish being migrated to the target node, so that the multi keys command can be executed.
-   redirection is emitted by the node, asking the client to retry only that
-   specific query into `destination-node`. In this case the client should not
-   update its hash slot to node mapping.
-3. If the command contains multiple keys, in case none exist, the behavior is
-   the same as point 2, if all exist, it is the same as point 1, however if only
-   a partial number of keys exist, the command emits a `TRYAGAIN` error in order
-   for the keys interested to finish being migrated to the target node, so that
-   the multi keys command can be executed.
 
 ## CLUSTER SETSLOT `<slot>` IMPORTING `<source-node-id>`
 
-This subcommand is the reverse of `MIGRATING`, and prepares the destination node
+This subcommand is the reverse of `MIGRATING`, and prepares the destination
-to import keys from the specified source node. The command only works if the
+node to import keys from the specified source node. The command only works if
-node is not already owner of the specified hash slot.
+the node is not already owner of the specified hash slot.
 
-When a slot is set in importing state, the node changes behavior in the
+When a slot is set in importing state, the node changes behavior in the following way:
-following way:
 
-1. Commands about this hash slot are refused and a `MOVED` redirection is
+1. Commands about this hash slot are refused and a `MOVED` redirection is generated as usually, but in the case the command follows an `ASKING` command, in this case the command is executed.
-   generated as usually, but in the case the command follows an `ASKING`
-   command, in this case the command is executed.
 
-In this way when a node in migrating state generates an `ASK` redirection, the
+In this way when a node in migrating state generates an `ASK` redirection, the client contacts the target node, sends `ASKING`, and immediately after sends the command. This way commands about non-existing keys in the old node or keys already migrated to the target node are executed in the target node, so that:
-client contacts the target node, sends `ASKING`, and immediately after sends the
-command. This way commands about non-existing keys in the old node or keys
-already migrated to the target node are executed in the target node, so that:
 
-1. New keys are always created in the target node. During a hash slot migration
+1. New keys are always created in the target node. During a hash slot migration we'll have to move only old keys, not new ones.
-   we'll have to move only old keys, not new ones.
+2. Commands about keys already migrated are correctly processed in the context of the node which is the target of the migration, the new hash slot owner, in order to guarantee consistency.
-2. Commands about keys already migrated are correctly processed in the context
+3. Without `ASKING` the behavior is the same as usually. This guarantees that clients with a broken hash slots mapping will not write for error in the target node, creating a new version of a key that has yet to be migrated.
-   of the node which is the target of the migration, the new hash slot owner, in
-   order to guarantee consistency.
-3. Without `ASKING` the behavior is the same as usually. This guarantees that
-   clients with a broken hash slots mapping will not write for error in the
-   target node, creating a new version of a key that has yet to be migrated.
 
 ## CLUSTER SETSLOT `<slot>` STABLE
 
 This subcommand just clears migrating / importing state from the slot. It is
-mainly used to fix a cluster stuck in a wrong state by
+mainly used to fix a cluster stuck in a wrong state by `redis-cli --cluster fix`.
-`redis-cli --cluster fix`. Normally the two states are cleared automatically at
+Normally the two states are cleared automatically at the end of the migration
-the end of the migration using the `SETSLOT ... NODE ...` subcommand as
+using the `SETSLOT ... NODE ...` subcommand as explained in the next section.
-explained in the next section.
 
 ## CLUSTER SETSLOT `<slot>` NODE `<node-id>`
 
-The `NODE` subcommand is the one with the most complex semantics. It associates
+The `NODE` subcommand is the one with the most complex semantics. It
-the hash slot with the specified node, however the command works only in
+associates the hash slot with the specified node, however the command works
-specific situations and has different side effects depending on the slot state.
+only in specific situations and has different side effects depending on the
-The following is the set of pre-conditions and side effects of the command:
+slot state. The following is the set of pre-conditions and side effects of the
+command:
 
-1. If the current hash slot owner is the node receiving the command, but for
+1. If the current hash slot owner is the node receiving the command, but for effect of the command the slot would be assigned to a different node, the command will return an error if there are still keys for that hash slot in the node receiving the command.
-   effect of the command the slot would be assigned to a different node, the
+2. If the slot is in *migrating* state, the state gets cleared when the slot is assigned to another node.
-   command will return an error if there are still keys for that hash slot in
+3. If the slot was in *importing* state in the node receiving the command, and the command assigns the slot to this node (which happens in the target node at the end of the resharding of a hash slot from one node to another), the command has the following side effects: A) the *importing* state is cleared. B) If the node config epoch is not already the greatest of the cluster, it generates a new one and assigns the new config epoch to itself. This way its new hash slot ownership will win over any past configuration created by previous failovers or slot migrations.
-   the node receiving the command.
-2. If the slot is in _migrating_ state, the state gets cleared when the slot is
-   assigned to another node.
-3. If the slot was in _importing_ state in the node receiving the command, and
-   the command assigns the slot to this node (which happens in the target node
-   at the end of the resharding of a hash slot from one node to another), the
-   command has the following side effects: A) the _importing_ state is cleared.
-   B) If the node config epoch is not already the greatest of the cluster, it
-   generates a new one and assigns the new config epoch to itself. This way its
-   new hash slot ownership will win over any past configuration created by
-   previous failovers or slot migrations.
 
-It is important to note that step 3 is the only time when a Redis Cluster node
+It is important to note that step 3 is the only time when a Redis Cluster node will create a new config epoch without agreement from other nodes. This only happens when a manual configuration is operated. However it is impossible that this creates a non-transient setup where two nodes have the same config epoch, since Redis Cluster uses a config epoch collision resolution algorithm.
-will create a new config epoch without agreement from other nodes. This only
-happens when a manual configuration is operated. However it is impossible that
-this creates a non-transient setup where two nodes have the same config epoch,
-since Redis Cluster uses a config epoch collision resolution algorithm.
 
 @return
 
-@simple-string-reply: All the subcommands return `OK` if the command was
+@simple-string-reply: All the subcommands return `OK` if the command was successful. Otherwise an error is returned.
-successful. Otherwise an error is returned.
 
 ## Redis Cluster live resharding explained
 
-The `CLUSTER SETSLOT` command is an important piece used by Redis Cluster in
+The `CLUSTER SETSLOT` command is an important piece used by Redis Cluster in order to migrate all the keys contained in one hash slot from one node to another. This is how the migration is orchestrated, with the help of other commands as well. We'll call the node that has the current ownership of the hash slot the `source` node, and the node where we want to migrate the `destination` node.
-order to migrate all the keys contained in one hash slot from one node to
-another. This is how the migration is orchestrated, with the help of other
-commands as well. We'll call the node that has the current ownership of the hash
-slot the `source` node, and the node where we want to migrate the `destination`
-node.
 
-1. Set the destination node slot to _importing_ state using
+1. Set the destination node slot to *importing* state using `CLUSTER SETSLOT <slot> IMPORTING <source-node-id>`.
-   `CLUSTER SETSLOT <slot> IMPORTING <source-node-id>`.
+2. Set the source node slot to *migrating* state using `CLUSTER SETSLOT <slot> MIGRATING <destination-node-id>`.
-2. Set the source node slot to _migrating_ state using
+3. Get keys from the source node with `CLUSTER GETKEYSINSLOT` command and move them into the destination node using the `MIGRATE` command.
-   `CLUSTER SETSLOT <slot> MIGRATING <destination-node-id>`.
+4. Send `CLUSTER SETSLOT <slot> NODE <destination-node-id>` to the destination node.
-3. Get keys from the source node with `CLUSTER GETKEYSINSLOT` command and move
+5. Send `CLUSTER SETSLOT <slot> NODE <destination-node-id>` to the source node.
-   them into the destination node using the `MIGRATE` command.
+6. Send `CLUSTER SETSLOT <slot> NODE <destination-node-id>` to the other master nodes (optional).
-4. Use `CLUSTER SETSLOT <slot> NODE <destination-node-id>` in the source or
-   destination.
 
 Notes:
 
-- The order of step 1 and 2 is important. We want the destination node to be
+* The order of step 1 and 2 is important. We want the destination node to be ready to accept `ASK` redirections when the source node is configured to redirect.
-  ready to accept `ASK` redirections when the source node is configured to
+* The order of step 4 and 5 is important.
-  redirect.
+  The destination node is responsible for propagating the change to the rest of the cluster.
-- Step 4 does not technically need to use `SETSLOT` in the nodes not involved in
+  If the source node is informed before the destination node and the destination node crashes before it is set as new slot owner, the slot is left with no owner, even after a successful failover.
-  the resharding, since the configuration will eventually propagate itself,
+* Step 6, sending `SETSLOT` to the nodes not involved in the resharding, is not technically necessary since the configuration will eventually propagate itself.
-  however it is a good idea to do so in order to stop nodes from pointing to the
+  However, it is a good idea to do so in order to stop nodes from pointing to the wrong node for the hash slot moved as soon as possible, resulting in less redirections to find the right node.
-  wrong node for the hash slot moved as soon as possible, resulting in less
-  redirections to find the right node.

iredis/data/commands/cluster-shards.md

@@ -0,0 +1,153 @@
+`CLUSTER SHARDS` returns details about the shards of the cluster.
+A shard is defined as a collection of nodes that serve the same set of slots and that replicate from each other.
+A shard may only have a single master at a given time, but may have multiple or no replicas.
+It is possible for a shard to not be serving any slots while still having replicas.
+
+This command replaces the `CLUSTER SLOTS` command, by providing a more efficient and extensible representation of the cluster. 
+
+The command is suitable to be used by Redis Cluster client libraries in order to understand the topology of the cluster.
+A client should issue this command on startup in order to retrieve the map associating cluster *hash slots* with actual node information.
+This map should be used to direct commands to the node that is likely serving the slot associated with a given command.
+In the event the command is sent to the wrong node, in that it received a '-MOVED' redirect, this command can then be used to update the topology of the cluster.
+
+The command returns an array of shards, with each shard containing two fields, 'slots' and 'nodes'. 
+
+The 'slots' field is a list of slot ranges served by this shard, stored as pair of integers representing the inclusive start and end slots of the ranges.
+For example, if a node owns the slots 1, 2, 3, 5, 7, 8 and 9, the slots ranges would be stored as [1-3], [5-5], [7-9].
+The slots field would therefor be represented by the following list of integers.
+
+```
+1) 1) "slots"
+   2) 1) (integer) 1
+      2) (integer) 3
+      3) (integer) 5
+      4) (integer) 5
+      5) (integer) 7
+      6) (integer) 9
+```
+
+The 'nodes' field contains a list of all nodes within the shard.
+Each individual node is a map of attributes that describe the node. 
+Some attributes are optional and more attributes may be added in the future. 
+The current list of attributes:
+
+* id: The unique node id for this particular node.
+* endpoint: The preferred endpoint to reach the node, see below for more information about the possible values of this field.
+* ip: The IP address to send requests to for this node.
+* hostname (optional): The announced hostname to send requests to for this node.
+* port (optional): The TCP (non-TLS) port of the node. At least one of port or tls-port will be present.
+* tls-port (optional): The TLS port of the node. At least one of port or tls-port will be present.
+* role: The replication role of this node.
+* replication-offset: The replication offset of this node. This information can be used to send commands to the most up to date replicas.
+* health: Either `online`, `failed`, or `loading`. This information should be used to determine which nodes should be sent traffic. The `loading` health state should be used to know that a node is not currently eligible to serve traffic, but may be eligible in the future. 
+
+The endpoint, along with the port, defines the location that clients should use to send requests for a given slot.
+A NULL value for the endpoint indicates the node has an unknown endpoint and the client should connect to the same endpoint it used to send the `CLUSTER SHARDS` command but with the port returned from the command.
+This unknown endpoint configuration is useful when the Redis nodes are behind a load balancer that Redis doesn't know the endpoint of.
+Which endpoint is set is determined by the `cluster-preferred-endpoint-type` config.
+
+@return
+
+@array-reply: nested list of a map of hash ranges and shard nodes.
+
+@examples
+
+```
+> CLUSTER SHARDS
+1) 1) "slots"
+   2) 1) (integer) 10923
+      2) (integer) 11110
+      3) (integer) 11113
+      4) (integer) 16111
+      5) (integer) 16113
+      6) (integer) 16383
+   3) "nodes"
+   4) 1)  1) "id"
+          2) "71f058078c142a73b94767a4e78e9033d195dfb4"
+          3) "port"
+          4) (integer) 6381
+          5) "ip"
+          6) "127.0.0.1"
+          7) "role"
+          8) "primary"
+          9) "replication-offset"
+         10) (integer) 1500
+         11) "health"
+         12) "online"
+      2)  1) "id"
+          2) "1461967c62eab0e821ed54f2c98e594fccfd8736"
+          3) "port"
+          4) (integer) 7381
+          5) "ip"
+          6) "127.0.0.1"
+          7) "role"
+          8) "replica"
+          9) "replication-offset"
+         10) (integer) 700
+         11) "health"
+         12) "fail"
+2) 1) "slots"
+   2) 1) (integer) 5461
+      2) (integer) 10922
+   3) "nodes"
+   4) 1)  1) "id"
+          2) "9215e30cd4a71070088778080565de6ef75fd459"
+          3) "port"
+          4) (integer) 6380
+          5) "ip"
+          6) "127.0.0.1"
+          7) "role"
+          8) "primary"
+          9) "replication-offset"
+         10) (integer) 1200
+         11) "health"
+         12) "online"
+      2)  1) "id"
+          2) "877fa59da72cb902d0563d3d8def3437fc3a0196"
+          3) "port"
+          4) (integer) 7380
+          5) "ip"
+          6) "127.0.0.1"
+          7) "role"
+          8) "replica"
+          9) "replication-offset"
+         10) (integer) 1100
+         11) "health"
+         12) "loading"
+3) 1) "slots"
+   2) 1) (integer) 0
+      2) (integer) 5460
+      3) (integer) 11111
+      4) (integer) 11112
+      3) (integer) 16112
+      4) (integer) 16112
+   3) "nodes"
+   4) 1)  1) "id"
+          2) "b7e9acc0def782aabe6b596f67f06c73c2ffff93"
+          3) "port"
+          4) (integer) 7379
+          5) "ip"
+          6) "127.0.0.1"
+          7) "hostname"
+          8) "example.com"
+          9) "role"
+         10) "replica"
+         11) "replication-offset"
+         12) "primary"
+         13) "health"
+         14) "online"
+      2)  1) "id"
+          2) "e2acf1a97c055fd09dcc2c0dcc62b19a6905dbc8"
+          3) "port"
+          4) (integer) 6379
+          5) "ip"
+          6) "127.0.0.1"
+          7) "hostname"
+          8) "example.com"
+          9) "role"
+         10) "replica"
+         11) "replication-offset"
+         12) (integer) 0
+         13) "health"
+         14) "loading"
+```

iredis/data/commands/cluster-slaves.md

@@ -1,21 +1,16 @@
-**A note about the word slave used in this man page and command name**: Starting
+**A note about the word slave used in this man page and command name**: starting with Redis version 5, if not for backward compatibility, the Redis project no longer uses the word slave. Please use the new command `CLUSTER REPLICAS`. The command `CLUSTER SLAVES` will continue to work for backward compatibility.
-with Redis 5 this command: starting with Redis version 5, if not for backward
-compatibility, the Redis project no longer uses the word slave. Please use the
-new command `CLUSTER REPLICAS`. The command `SLAVEOF` will continue to work for
-backward compatibility.
 
 The command provides a list of replica nodes replicating from the specified
-master node. The list is provided in the same format used by `CLUSTER NODES`
+master node. The list is provided in the same format used by `CLUSTER NODES` (please refer to its documentation for the specification of the format).
-(please refer to its documentation for the specification of the format).
 
-The command will fail if the specified node is not known or if it is not a
+The command will fail if the specified node is not known or if it is not
-master according to the node table of the node receiving the command.
+a master according to the node table of the node receiving the command.
 
-Note that if a replica is added, moved, or removed from a given master node, and
+Note that if a replica is added, moved, or removed from a given master node,
-we ask `CLUSTER SLAVES` to a node that has not yet received the configuration
+and we ask `CLUSTER SLAVES` to a node that has not yet received the
-update, it may show stale information. However eventually (in a matter of
+configuration update, it may show stale information. However eventually
-seconds if there are no network partitions) all the nodes will agree about the
+(in a matter of seconds if there are no network partitions) all the nodes
-set of nodes associated with a given master.
+will agree about the set of nodes associated with a given master.
 
 @return
 

iredis/data/commands/cluster-slots.md

@@ -1,102 +1,92 @@
-`CLUSTER SLOTS` returns details about which cluster slots map to which Redis
+`CLUSTER SLOTS` returns details about which cluster slots map to which Redis instances. 
-instances. The command is suitable to be used by Redis Cluster client libraries
+The command is suitable to be used by Redis Cluster client libraries implementations in order to retrieve (or update when a redirection is received) the map associating cluster *hash slots* with actual nodes network information, so that when a command is received, it can be sent to what is likely the right instance for the keys specified in the command. 
-implementations in order to retrieve (or update when a redirection is received)
+
-the map associating cluster _hash slots_ with actual nodes network coordinates
+The networking information for each node is an array containing the following elements:
-(composed of an IP address and a TCP port), so that when a command is received,
+
-it can be sent to what is likely the right instance for the keys specified in
+* Preferred endpoint (Either an IP address, hostname, or NULL)
-the command.
+* Port number
+* The node ID
+* A map of additional networking metadata
+
+The preferred endpoint, along with the port, defines the location that clients should use to send requests for a given slot.
+A NULL value for the endpoint indicates the node has an unknown endpoint and the client should connect to the same endpoint it used to send the `CLUSTER SLOTS` command but with the port returned from the command.
+This unknown endpoint configuration is useful when the Redis nodes are behind a load balancer that Redis doesn't know the endpoint of.
+Which endpoint is set as preferred is determined by the `cluster-preferred-endpoint-type` config.
+
+Additional networking metadata is provided as a map on the fourth argument for each node. 
+The following networking metadata may be returned:
+
+* IP: When the preferred endpoint is not set to IP.
+* Hostname: When a node has an announced hostname but the primary endpoint is not set to hostname.
 
 ## Nested Result Array
-
 Each nested result is:
 
-- Start slot range
+  - Start slot range
-- End slot range
+  - End slot range
-- Master for slot range represented as nested IP/Port array
+  - Master for slot range represented as nested networking information
-- First replica of master for slot range
+  - First replica of master for slot range
-- Second replica
+  - Second replica
-- ...continues until all replicas for this master are returned.
+  - ...continues until all replicas for this master are returned.
 
-Each result includes all active replicas of the master instance for the listed
+Each result includes all active replicas of the master instance
-slot range. Failed replicas are not returned.
+for the listed slot range.  Failed replicas are not returned.
 
-The third nested reply is guaranteed to be the IP/Port pair of the master
+The third nested reply is guaranteed to be the networking information of the master instance for the slot range.
-instance for the slot range. All IP/Port pairs after the third nested reply are
+All networking information after the third nested reply are replicas of the master.
-replicas of the master.
 
-If a cluster instance has non-contiguous slots (e.g. 1-400,900,1800-6000) then
+If a cluster instance has non-contiguous slots (e.g. 1-400,900,1800-6000) then master and replica networking information results will be duplicated for each top-level slot range reply.
-master and replica IP/Port results will be duplicated for each top-level slot
-range reply.
-
-**Warning:** Newer versions of Redis Cluster will output, for each Redis
-instance, not just the IP and port, but also the node ID as third element of the
-array. In future versions there could be more elements describing the node
-better. In general a client implementation should just rely on the fact that
-certain parameters are at fixed positions as specified, but more parameters may
-follow and should be ignored. Similarly a client library should try if possible
-to cope with the fact that older versions may just have the IP and port
-parameter.
 
 @return
 
-@array-reply: nested list of slot ranges with IP/Port mappings.
+@array-reply: nested list of slot ranges with networking information.
 
-### Sample Output (old version)
+@examples
 
 ```
-127.0.0.1:7001> cluster slots
+> CLUSTER SLOTS
-1) 1) (integer) 0
-   2) (integer) 4095
-   3) 1) "127.0.0.1"
-      2) (integer) 7000
-   4) 1) "127.0.0.1"
-      2) (integer) 7004
-2) 1) (integer) 12288
-   2) (integer) 16383
-   3) 1) "127.0.0.1"
-      2) (integer) 7003
-   4) 1) "127.0.0.1"
-      2) (integer) 7007
-3) 1) (integer) 4096
-   2) (integer) 8191
-   3) 1) "127.0.0.1"
-      2) (integer) 7001
-   4) 1) "127.0.0.1"
-      2) (integer) 7005
-4) 1) (integer) 8192
-   2) (integer) 12287
-   3) 1) "127.0.0.1"
-      2) (integer) 7002
-   4) 1) "127.0.0.1"
-      2) (integer) 7006
-```
-
-### Sample Output (new version, includes IDs)
-
-```
-127.0.0.1:30001> cluster slots
 1) 1) (integer) 0
    2) (integer) 5460
    3) 1) "127.0.0.1"
       2) (integer) 30001
       3) "09dbe9720cda62f7865eabc5fd8857c5d2678366"
+      4) 1) hostname
+         2) "host-1.redis.example.com"
    4) 1) "127.0.0.1"
       2) (integer) 30004
       3) "821d8ca00d7ccf931ed3ffc7e3db0599d2271abf"
+      4) 1) hostname
+         2) "host-2.redis.example.com"
 2) 1) (integer) 5461
    2) (integer) 10922
    3) 1) "127.0.0.1"
       2) (integer) 30002
       3) "c9d93d9f2c0c524ff34cc11838c2003d8c29e013"
+      4) 1) hostname
+         2) "host-3.redis.example.com"
    4) 1) "127.0.0.1"
       2) (integer) 30005
       3) "faadb3eb99009de4ab72ad6b6ed87634c7ee410f"
+      4) 1) hostname
+         2) "host-4.redis.example.com"
 3) 1) (integer) 10923
    2) (integer) 16383
    3) 1) "127.0.0.1"
       2) (integer) 30003
       3) "044ec91f325b7595e76dbcb18cc688b6a5b434a1"
+      4) 1) hostname
+         2) "host-5.redis.example.com"
    4) 1) "127.0.0.1"
       2) (integer) 30006
       3) "58e6e48d41228013e5d9c1c37c5060693925e97e"
+      4) 1) hostname
+         2) "host-6.redis.example.com"
 ```
+
+**Warning:** In future versions there could be more elements describing the node better.
+In general a client implementation should just rely on the fact that certain parameters are at fixed positions as specified, but more parameters may follow and should be ignored.
+Similarly a client library should try if possible to cope with the fact that older versions may just have the primary endpoint and port parameter.
+
+## Behavior change history
+
+*   `>= 7.0.0`: Added support for hostnames and unknown endpoints in first field of node response.

iredis/data/commands/cluster.md

@@ -0,0 +1,3 @@
+This is a container command for Redis Cluster commands.
+
+To see the list of available commands you can call `CLUSTER HELP`.

iredis/data/commands/command-docs.md

@@ -0,0 +1,55 @@
+Return documentary information about commands.
+
+By default, the reply includes all of the server's commands.
+You can use the optional _command-name_ argument to specify the names of one or more commands.
+
+The reply includes a map for each returned command.
+The following keys may be included in the mapped reply:
+
+* **summary:** short command description.
+* **since:** the Redis version that added the command (or for module commands, the module version).
+* **group:** the functional group to which the command belongs.
+  Possible values are:
+  - _bitmap_
+  - _cluster_
+  - _connection_
+  - _generic_
+  - _geo_
+  - _hash_
+  - _hyperloglog_
+  - _list_
+  - _module_
+  - _pubsub_
+  - _scripting_
+  - _sentinel_
+  - _server_
+  - _set_
+  - _sorted-set_
+  - _stream_
+  - _string_
+  - _transactions_
+* **complexity:** a short explanation about the command's time complexity.
+* **doc_flags:** an array of documentation flags.
+  Possible values are:
+  - _deprecated:_ the command is deprecated.
+  - _syscmd:_ a system command that isn't meant to be called by users.
+* **deprecated_since:** the Redis version that deprecated the command (or for module commands, the module version)..
+* **replaced_by:** the alternative for a deprecated command.
+* **history:** an array of historical notes describing changes to the command's behavior or arguments.
+  Each entry is an array itself, made up of two elements:
+  1. The Redis version that the entry applies to.
+  2. The description of the change.
+* **arguments:** an array of maps that describe the command's arguments.
+  Please refer to the [Redis command arguments][td] page for more information.
+
+[td]: /topics/command-arguments
+
+@return
+
+@array-reply: a map as a flattened array as described above.
+
+@examples
+
+```cli
+COMMAND DOCS SET
+```

iredis/data/commands/command-getkeys.md

@@ -1,12 +1,12 @@
 Returns @array-reply of keys from a full Redis command.
 
-`COMMAND GETKEYS` is a helper command to let you find the keys from a full Redis
+`COMMAND GETKEYS` is a helper command to let you find the keys
-command.
+from a full Redis command.
+
+`COMMAND` provides information on how to find the key names of each command (see `firstkey`, [key specifications](/topics/key-specs#logical-operation-flags), and `movablekeys`),
+but in some cases it's not possible to find keys of certain commands and then the entire command must be parsed to discover some / all key names.
+You can use `COMMAND GETKEYS` or `COMMAND GETKEYSANDFLAGS` to discover key names directly from how Redis parses the commands.
 
-`COMMAND` shows some commands as having movablekeys meaning the entire command
-must be parsed to discover storage or retrieval keys. You can use
-`COMMAND GETKEYS` to discover key positions directly from how Redis parses the
-commands.
 
 @return
 

iredis/data/commands/command-getkeysandflags.md

@@ -0,0 +1,22 @@
+Returns @array-reply of keys from a full Redis command and their usage flags.
+
+`COMMAND GETKEYSANDFLAGS` is a helper command to let you find the keys from a full Redis command together with flags indicating what each key is used for.
+
+`COMMAND` provides information on how to find the key names of each command (see `firstkey`, [key specifications](/topics/key-specs#logical-operation-flags), and `movablekeys`),
+but in some cases it's not possible to find keys of certain commands and then the entire command must be parsed to discover some / all key names.
+You can use `COMMAND GETKEYS` or `COMMAND GETKEYSANDFLAGS` to discover key names directly from how Redis parses the commands.
+
+Refer to [key specifications](/topics/key-specs#logical-operation-flags) for information about the meaning of the key flags.
+
+@return
+
+@array-reply: list of keys from your command.
+Each element of the array is an array containing key name in the first entry, and flags in the second.
+
+@examples
+
+```cli
+COMMAND GETKEYS MSET a b c d e f
+COMMAND GETKEYS EVAL "not consulted" 3 key1 key2 key3 arg1 arg2 arg3 argN
+COMMAND GETKEYSANDFLAGS LMOVE mylist1 mylist2 left left
+```

iredis/data/commands/command-help.md

@@ -0,0 +1,5 @@
+The `COMMAND HELP` command returns a helpful text describing the different subcommands.
+
+@return
+
+@array-reply: a list of subcommands and their descriptions

iredis/data/commands/command-info.md

@@ -1,10 +1,11 @@
 Returns @array-reply of details about multiple Redis commands.
 
-Same result format as `COMMAND` except you can specify which commands get
+Same result format as `COMMAND` except you can specify which commands
-returned.
+get returned.
+
+If you request details about non-existing commands, their return
+position will be nil.
 
-If you request details about non-existing commands, their return position will
-be nil.
 
 @return
 

iredis/data/commands/command-list.md

@@ -0,0 +1,11 @@
+Return an array of the server's command names.
+
+You can use the optional _FILTERBY_ modifier to apply one of the following filters:
+
+ - **MODULE module-name**: get the commands that belong to the module specified by _module-name_.
+ - **ACLCAT category**: get the commands in the [ACL category](/docs/manual/security/acl/#command-categories) specified by _category_.
+ - **PATTERN pattern**: get the commands that match the given glob-like _pattern_.
+
+@return
+
+@array-reply: a list of command names.

iredis/data/commands/command.md

@@ -1,94 +1,91 @@
-Returns @array-reply of details about all Redis commands.
+Return an array with details about every Redis command.
 
-Cluster clients must be aware of key positions in commands so commands can go to
+The `COMMAND` command is introspective.
-matching instances, but Redis commands vary between accepting one key, multiple
+Its reply describes all commands that the server can process.
-keys, or even multiple keys separated by other data.
+Redis clients can call it to obtain the server's runtime capabilities during the handshake.
 
-You can use `COMMAND` to cache a mapping between commands and key positions for
+`COMMAND` also has several subcommands.
-each command to enable exact routing of commands to cluster instances.
+Please refer to its subcommands for further details.
 
-## Nested Result Array
+**Cluster note:**
+this command is especially beneficial for cluster-aware clients.
+Such clients must identify the names of keys in commands to route requests to the correct shard.
+Although most commands accept a single key as their first argument, there are many exceptions to this rule. 
+You can call `COMMAND` and then keep the mapping between commands and their respective key specification rules cached in the client.
 
-Each top-level result contains six nested results. Each nested result is:
+The reply it returns is an array with an element per command.
+Each element that describes a Redis command is represented as an array by itself.
 
-- command name
+The command's array consists of a fixed number of elements.
-- command arity specification
+The exact number of elements in the array depends on the server's version.
-- nested @array-reply of command flags
-- position of first key in argument list
-- position of last key in argument list
-- step count for locating repeating keys
 
-### Command Name
+1. Name
+1. Arity
+1. Flags
+1. First key
+1. Last key
+1. Step
+1. [ACL categories][ta] (as of Redis 6.0)
+1. [Tips][tb] (as of Redis 7.0)
+1. [Key specifications][td] (as of Redis 7.0)
+1. Subcommands (as of Redis 7.0)
 
-Command name is the command returned as a lowercase string.
+## Name
 
-### Command Arity
+This is the command's name in lowercase.
 
-<table style="width:50%">
+**Note:**
-<tr><td>
+Redis command names are case-insensitive.
-<pre>
-<code>1) 1) "get"
-   2) (integer) 2
-   3) 1) readonly
-   4) (integer) 1
-   5) (integer) 1
-   6) (integer) 1
-</code>
-</pre>
-</td>
-<td>
-<pre>
-<code>1) 1) "mget"
-   2) (integer) -2
-   3) 1) readonly
-   4) (integer) 1
-   5) (integer) -1
-   6) (integer) 1
-</code>
-</pre>
-</td></tr>
-</table>
 
-Command arity follows a simple pattern:
+## Arity
 
-- positive if command has fixed number of required arguments.
+Arity is the number of arguments a command expects.
-- negative if command has minimum number of required arguments, but may have
+It follows a simple pattern:
-  more.
 
-Command arity _includes_ counting the command name itself.
+* A positive integer means a fixed number of arguments.
+* A negative integer means a minimal number of arguments.
+
+Command arity _always includes_ the command's name itself (and the subcommand when applicable).
 
 Examples:
 
-- `GET` arity is 2 since the command only accepts one argument and always has
+* `GET`'s arity is _2_ since the command only accepts one argument and always has the format `GET _key_`.
-  the format `GET _key_`.
+* `MGET`'s arity is _-2_ since the command accepts at least one argument, but possibly multiple ones: `MGET _key1_ [key2] [key3] ...`.
-- `MGET` arity is -2 since the command accepts at a minimum one argument, but up
-  to an unlimited number: `MGET _key1_ [key2] [key3] ...`.
 
-Also note with `MGET`, the -1 value for "last key position" means the list of
+## Flags
-keys may have unlimited length.
 
-### Flags
+Command flags are an array. It can contain the following simple strings (status reply):
 
-Command flags is @array-reply containing one or more status replies:
+* **admin:** the command is an administrative command.
+* **asking:** the command is allowed even during hash slot migration.
+  This flag is relevant in Redis Cluster deployments.
+* **blocking:** the command may block the requesting client.
+* **denyoom**: the command is rejected if the server's memory usage is too high (see the _maxmemory_ configuration directive).
+* **fast:** the command operates in constant or log(N) time.
+  This flag is used for monitoring latency with the `LATENCY` command.
+* **loading:** the command is allowed while the database is loading.
+* **movablekeys:** the _first key_, _last key_, and _step_ values don't determine all key positions.
+  Clients need to use `COMMAND GETKEYS` or [key specifications][td] in this case.
+  See below for more details.
+* **no_auth:** executing the command doesn't require authentication.
+* **no_async_loading:** the command is denied during asynchronous loading (that is when a replica uses disk-less `SWAPDB SYNC`, and allows access to the old dataset).
+* **no_mandatory_keys:** the command may accept key name arguments, but these aren't mandatory.
+* **no_multi:** the command isn't allowed inside the context of a [transaction](/topics/transactions).
+* **noscript:** the command can't be called from [scripts](/topics/eval-intro) or [functions](/topics/functions-intro).
+* **pubsub:** the command is related to [Redis Pub/Sub](/topics/pubsub).
+* **random**: the command returns random results, which is a concern with verbatim script replication.
+  As of Redis 7.0, this flag is a [command tip][tb].
+* **readonly:** the command doesn't modify data.
+* **sort_for_script:** the command's output is sorted when called from a script.
+* **skip_monitor:** the command is not shown in `MONITOR`'s output.
+* **skip_slowlog:** the command is not shown in `SLOWLOG`'s output.
+  As of Redis 7.0, this flag is a [command tip][tb].
+* **stale:** the command is allowed while a replica has stale data.
+* **write:** the command may modify data.
 
-- _write_ - command may result in modifications
+### Movablekeys
-- _readonly_ - command will never modify keys
-- _denyoom_ - reject command if currently out of memory
-- _admin_ - server admin command
-- _pubsub_ - pubsub-related command
-- _noscript_ - deny this command from scripts
-- _random_ - command has random results, dangerous for scripts
-- _sort_for_script_ - if called from script, sort output
-- _loading_ - allow command while database is loading
-- _stale_ - allow command while replica has stale data
-- _skip_monitor_ - do not show this command in MONITOR
-- _asking_ - cluster related - accept even if importing
-- _fast_ - command operates in constant or log(N) time. Used for latency
-  monitoring.
-- _movablekeys_ - keys have no pre-determined position. You must discover keys
-  yourself.
 
-### Movable Keys
+Consider `SORT`:
 
 ```
 1) 1) "sort"
@@ -99,85 +96,146 @@ Command flags is @array-reply containing one or more status replies:
    4) (integer) 1
    5) (integer) 1
    6) (integer) 1
+   ...
 ```
 
-Some Redis commands have no predetermined key locations. For those commands,
+Some Redis commands have no predetermined key locations or are not easy to find.
-flag `movablekeys` is added to the command flags @array-reply. Your Redis
+For those commands, the _movablekeys_ flag indicates that the _first key_, _last key_, and _step_ values are insufficient to find all the keys.
-Cluster client needs to parse commands marked `movablekeys` to locate all
-relevant key positions.
 
-Complete list of commands currently requiring key location parsing:
+Here are several examples of commands that have the _movablekeys_ flag:
 
-- `SORT` - optional `STORE` key, optional `BY` weights, optional `GET` keys
+* `SORT`: the optional _STORE_, _BY_, and _GET_ modifiers are followed by names of keys.
-- `ZUNION` - keys stop when `WEIGHT` or `AGGREGATE` starts
+* `ZUNION`: the _numkeys_ argument specifies the number key name arguments.
-- `ZUNIONSTORE` - keys stop when `WEIGHT` or `AGGREGATE` starts
+* `MIGRATE`: the keys appear _KEYS_ keyword and only when the second argument is the empty string.
-- `ZINTER` - keys stop when `WEIGHT` or `AGGREGATE` starts
-- `ZINTERSTORE` - keys stop when `WEIGHT` or `AGGREGATE` starts
-- `ZDIFF` - keys stop after `numkeys` count arguments
-- `ZDIFFSTORE` - keys stop after `numkeys` count arguments
-- `EVAL` - keys stop after `numkeys` count arguments
-- `EVALSHA` - keys stop after `numkeys` count arguments
 
-Also see `COMMAND GETKEYS` for getting your Redis server tell you where keys are
+Redis Cluster clients need to use other measures, as follows, to locate the keys for such commands.
-in any given command.
 
-### First Key in Argument List
+You can use the `COMMAND GETKEYS` command and have your Redis server report all keys of a given command's invocation.
 
-For most commands the first key is position 1. Position 0 is always the command
+As of Redis 7.0, clients can use the [key specifications](#key-specifications) to identify the positions of key names.
-name itself.
+The only commands that require using `COMMAND GETKEYS` are `SORT` and `MIGRATE` for clients that parse keys' specifications.
 
-### Last Key in Argument List
+For more information, please refer to the [key specifications page][tr].
 
-Redis commands usually accept one key, two keys, or an unlimited number of keys.
+## First key
 
-If a command accepts one key, the first key and last key positions is 1.
+The position of the command's first key name argument.
+For most commands, the first key's position is 1.
+Position 0 is always the command name itself.
 
-If a command accepts two keys (e.g. `BRPOPLPUSH`, `SMOVE`, `RENAME`, ...) then
+## Last key
-the last key position is the location of the last key in the argument list.
 
-If a command accepts an unlimited number of keys, the last key position is -1.
+The position of the command's last key name argument.
+Redis commands usually accept one, two or multiple number of keys.
 
-### Step Count
+Commands that accept a single key have both _first key_ and _last key_ set to 1.
 
-<table style="width:50%">
+Commands that accept two key name arguments, e.g. `BRPOPLPUSH`, `SMOVE` and `RENAME`, have this value set to the position of their second key.
-<tr><td>
+
-<pre>
+Multi-key commands that accept an arbitrary number of keys, such as `MSET`, use the value -1.
-<code>1) 1) "mset"
+
+## Step
+
+The step, or increment, between the _first key_ and the position of the next key.
+
+Consider the following two examples:
+
+```
+1) 1) "mset"
    2) (integer) -3
    3) 1) write
       2) denyoom
    4) (integer) 1
    5) (integer) -1
    6) (integer) 2
-</code>
+   ...
-</pre>
+```
-</td>
+
-<td>
+```
-<pre>
+1) 1) "mget"
-<code>1) 1) "mget"
    2) (integer) -2
    3) 1) readonly
+      2) fast
    4) (integer) 1
    5) (integer) -1
    6) (integer) 1
-</code>
+   ...
-</pre>
+```
-</td></tr>
-</table>
 
-Key step count allows us to find key positions in commands like `MSET` where the
+The step count allows us to find keys' positions. 
-format is `MSET _key1_ _val1_ [key2] [val2] [key3] [val3]...`.
+For example `MSET`: Its syntax is `MSET _key1_ _val1_ [key2] [val2] [key3] [val3]...`, so the keys are at every other position (step value of _2_).
+Unlike `MGET`, which uses a step value of _1_.
 
-In the case of `MSET`, keys are every other position so the step value is 2.
+## ACL categories
-Compare with `MGET` above where the step value is just 1.
+
+This is an array of simple strings that are the ACL categories to which the command belongs.
+Please refer to the [Access Control List][ta] page for more information.
+
+## Command tips
+
+Helpful information about the command.
+To be used by clients/proxies.
+
+Please check the [Command tips][tb] page for more information.
+
+## Key specifications
+
+This is an array consisting of the command's key specifications.
+Each element in the array is a map describing a method for locating keys in the command's arguments.
+
+For more information please check the [key specifications page][td].
+
+## Subcommands
+
+This is an array containing all of the command's subcommands, if any.
+Some Redis commands have subcommands (e.g., the `REWRITE` subcommand of `CONFIG`).
+Each element in the array represents one subcommand and follows the same specifications as those of `COMMAND`'s reply.
+
+[ta]: /topics/acl
+[tb]: /topics/command-tips
+[td]: /topics/key-specs
+[tr]: /topics/key-specs
 
 @return
 
-@array-reply: nested list of command details. Commands are returned in random
+@array-reply: a nested list of command details.
-order.
+
+The order of commands in the array is random.
 
 @examples
 
-```cli
+The following is `COMMAND`'s output for the `GET` command:
-COMMAND
+
+```
+1)  1) "get"
+    2) (integer) 2
+    3) 1) readonly
+       2) fast
+    4) (integer) 1
+    5) (integer) 1
+    6) (integer) 1
+    7) 1) @read
+       2) @string
+       3) @fast
+    8) (empty array)
+    9) 1) 1) "flags"
+          2) 1) read
+          3) "begin_search"
+          4) 1) "type"
+             2) "index"
+             3) "spec"
+             4) 1) "index"
+                2) (integer) 1
+          5) "find_keys"
+          6) 1) "type"
+             2) "range"
+             3) "spec"
+             4) 1) "lastkey"
+                2) (integer) 0
+                3) "keystep"
+                4) (integer) 1
+                5) "limit"
+                6) (integer) 0
+   10) (empty array)
+...
 ```

iredis/data/commands/config-get.md

@@ -1,51 +1,44 @@
 The `CONFIG GET` command is used to read the configuration parameters of a
-running Redis server. Not all the configuration parameters are supported in
+running Redis server.
-Redis 2.4, while Redis 2.6 can read the whole configuration of a server using
+Not all the configuration parameters are supported in Redis 2.4, while Redis 2.6
-this command.
+can read the whole configuration of a server using this command.
 
-The symmetric command used to alter the configuration at run time is
+The symmetric command used to alter the configuration at run time is `CONFIG
-`CONFIG SET`.
+SET`.
 
-`CONFIG GET` takes a single argument, which is a glob-style pattern. All the
+`CONFIG GET` takes multiple arguments, which are glob-style patterns.
-configuration parameters matching this parameter are reported as a list of
+Any configuration parameter matching any of the patterns are reported as a list
-key-value pairs. Example:
+of key-value pairs.
+Example:
 
 ```
-redis> config get *max-*-entries*
+redis> config get *max-*-entries* maxmemory
-1) "hash-max-zipmap-entries"
+ 1) "maxmemory"
-2) "512"
+ 2) "0"
-3) "list-max-ziplist-entries"
+ 3) "hash-max-listpack-entries"
-4) "512"
+ 4) "512"
-5) "set-max-intset-entries"
+ 5) "hash-max-ziplist-entries"
-6) "512"
+ 6) "512"
+ 7) "set-max-intset-entries"
+ 8) "512"
+ 9) "zset-max-listpack-entries"
+10) "128"
+11) "zset-max-ziplist-entries"
+12) "128"
 ```
 
 You can obtain a list of all the supported configuration parameters by typing
 `CONFIG GET *` in an open `redis-cli` prompt.
 
 All the supported parameters have the same meaning of the equivalent
-configuration parameter used in the [redis.conf][hgcarr22rc] file, with the
+configuration parameter used in the [redis.conf][hgcarr22rc] file:
-following important differences:
 
-[hgcarr22rc]: http://github.com/redis/redis/raw/2.8/redis.conf
+[hgcarr22rc]: http://github.com/redis/redis/raw/unstable/redis.conf
 
-- Where bytes or other quantities are specified, it is not possible to use the
+Note that you should look at the redis.conf file relevant to the version you're
-  `redis.conf` abbreviated form (`10k`, `2gb` ... and so forth), everything
+working with as configuration options might change between versions. The link
-  should be specified as a well-formed 64-bit integer, in the base unit of the
+above is to the latest development version.
-  configuration directive.
-- The save parameter is a single string of space-separated integers. Every pair
-  of integers represent a seconds/modifications threshold.
 
-For instance what in `redis.conf` looks like:
-
-```
-save 900 1
-save 300 10
-```
-
-that means, save after 900 seconds if there is at least 1 change to the dataset,
-and after 300 seconds if there are at least 10 changes to the dataset, will be
-reported by `CONFIG GET` as "900 1 300 10".
 
 @return
 

iredis/data/commands/config-help.md

@@ -0,0 +1,5 @@
+The `CONFIG HELP` command returns a helpful text describing the different subcommands.
+
+@return
+
+@array-reply: a list of subcommands and their descriptions

iredis/data/commands/config-resetstat.md

@@ -2,14 +2,14 @@ Resets the statistics reported by Redis using the `INFO` command.
 
 These are the counters that are reset:
 
-- Keyspace hits
+* Keyspace hits
-- Keyspace misses
+* Keyspace misses
-- Number of commands processed
+* Number of commands processed
-- Number of connections received
+* Number of connections received
-- Number of expired keys
+* Number of expired keys
-- Number of rejected connections
+* Number of rejected connections
-- Latest fork(2) time
+* Latest fork(2) time
-- The `aof_delayed_fsync` counter
+* The `aof_delayed_fsync` counter
 
 @return
 

iredis/data/commands/config-rewrite.md

@@ -1,35 +1,18 @@
-The `CONFIG REWRITE` command rewrites the `redis.conf` file the server was
+The `CONFIG REWRITE` command rewrites the `redis.conf` file the server was started with, applying the minimal changes needed to make it reflect the configuration currently used by the server, which may be different compared to the original one because of the use of the `CONFIG SET` command.
-started with, applying the minimal changes needed to make it reflect the
-configuration currently used by the server, which may be different compared to
-the original one because of the use of the `CONFIG SET` command.
 
 The rewrite is performed in a very conservative way:
 
-- Comments and the overall structure of the original redis.conf are preserved as
+* Comments and the overall structure of the original redis.conf are preserved as much as possible.
-  much as possible.
+* If an option already exists in the old redis.conf file, it will be rewritten at the same position (line number).
-- If an option already exists in the old redis.conf file, it will be rewritten
+* If an option was not already present, but it is set to its default value, it is not added by the rewrite process.
-  at the same position (line number).
+* If an option was not already present, but it is set to a non-default value, it is appended at the end of the file.
-- If an option was not already present, but it is set to its default value, it
+* Non used lines are blanked. For instance if you used to have multiple `save` directives, but the current configuration has fewer or none as you disabled RDB persistence, all the lines will be blanked.
-  is not added by the rewrite process.
-- If an option was not already present, but it is set to a non-default value, it
-  is appended at the end of the file.
-- Non used lines are blanked. For instance if you used to have multiple `save`
-  directives, but the current configuration has fewer or none as you disabled
-  RDB persistence, all the lines will be blanked.
 
-CONFIG REWRITE is also able to rewrite the configuration file from scratch if
+CONFIG REWRITE is also able to rewrite the configuration file from scratch if the original one no longer exists for some reason. However if the server was started without a configuration file at all, the CONFIG REWRITE will just return an error.
-the original one no longer exists for some reason. However if the server was
-started without a configuration file at all, the CONFIG REWRITE will just return
-an error.
 
 ## Atomic rewrite process
 
-In order to make sure the redis.conf file is always consistent, that is, on
+In order to make sure the redis.conf file is always consistent, that is, on errors or crashes you always end with the old file, or the new one, the rewrite is performed with a single `write(2)` call that has enough content to be at least as big as the old file. Sometimes additional padding in the form of comments is added in order to make sure the resulting file is big enough, and later the file gets truncated to remove the padding at the end.
-errors or crashes you always end with the old file, or the new one, the rewrite
-is performed with a single `write(2)` call that has enough content to be at
-least as big as the old file. Sometimes additional padding in the form of
-comments is added in order to make sure the resulting file is big enough, and
-later the file gets truncated to remove the padding at the end.
 
 @return
 

iredis/data/commands/config-set.md

@@ -1,6 +1,7 @@
 The `CONFIG SET` command is used in order to reconfigure the server at run time
-without the need to restart Redis. You can change both trivial parameters or
+without the need to restart Redis.
-switch from one to another persistence option using this command.
+You can change both trivial parameters or switch from one to another persistence
+option using this command.
 
 The list of configuration parameters supported by `CONFIG SET` can be obtained
 issuing a `CONFIG GET *` command, that is the symmetrical command used to obtain
@@ -10,34 +11,18 @@ All the configuration parameters set using `CONFIG SET` are immediately loaded
 by Redis and will take effect starting with the next command executed.
 
 All the supported parameters have the same meaning of the equivalent
-configuration parameter used in the [redis.conf][hgcarr22rc] file, with the
+configuration parameter used in the [redis.conf][hgcarr22rc] file.
-following important differences:
 
-[hgcarr22rc]: http://github.com/redis/redis/raw/6.0/redis.conf
+[hgcarr22rc]: http://github.com/redis/redis/raw/unstable/redis.conf
 
-- In options where bytes or other quantities are specified, it is not possible
+Note that you should look at the redis.conf file relevant to the version you're
-  to use the `redis.conf` abbreviated form (`10k`, `2gb` ... and so forth),
+working with as configuration options might change between versions. The link
-  everything should be specified as a well-formed 64-bit integer, in the base
+above is to the latest development version.
-  unit of the configuration directive. However since Redis version 3.0 or
-  greater, it is possible to use `CONFIG SET` with memory units for `maxmemory`,
-  client output buffers, and replication backlog size.
-- The save parameter is a single string of space-separated integers. Every pair
-  of integers represent a seconds/modifications threshold.
-
-For instance what in `redis.conf` looks like:
-
-```
-save 900 1
-save 300 10
-```
-
-that means, save after 900 seconds if there is at least 1 change to the dataset,
-and after 300 seconds if there are at least 10 changes to the dataset, should be
-set using `CONFIG SET SAVE "900 1 300 10"`.
 
 It is possible to switch persistence from RDB snapshotting to append-only file
-(and the other way around) using the `CONFIG SET` command. For more information
+(and the other way around) using the `CONFIG SET` command.
-about how to do that please check the [persistence page][tp].
+For more information about how to do that please check the [persistence
+page][tp].
 
 [tp]: /topics/persistence
 
@@ -52,5 +37,5 @@ options are not mutually exclusive.
 
 @return
 
-@simple-string-reply: `OK` when the configuration was set properly. Otherwise an
+@simple-string-reply: `OK` when the configuration was set properly.
-error is returned.
+Otherwise an error is returned.