Add tt cat, play, rocks

doc/reference/tt_cli/cat.rst

@@ -0,0 +1,71 @@
+Printing the contents of .snap and .xlog files
+==============================================
+
+..  code-block:: bash
+
+    tt cat FILE .. [flags]
+
+``tt cat`` prints the contents of :ref:`snapshot <internals-snapshot>` (``.snap``) and
+:ref:`WAL <internals-wal>` (``.xlog``) files to stdout. A single call of ``tt cat`` can
+print the contents of multiple files.
+
+
+Flags
+-----
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 20 80
+        :header-rows: 0
+
+        *   -   ``--format``
+            -   Output format: ``yaml`` (default), ``json``, or ``lua``
+        *   -   ``--from``
+            -   Show operations starting from the given LSN
+        *   -   ``--to``
+            -   Show operations up to the given LSN. Default: 18446744073709551615
+        *   -   ``--replica``
+            -   Filter the output by replica ID. Can be passed more than once
+        *   -   ``--space``
+            -   Filter the output by space ID. Can be passed more than once
+        *   -   ``--show-system``
+            -   Show the contents of system spaces
+
+Details
+-------
+
+When calling ``tt cat`` with filters by LSN (``--from`` and ``--to`` flags) and
+replica ID (``--replica``), remember that LSNs differ across replicas.
+Thus, if you pass more than one replica ID via ``--from`` or ``--to``,
+the result may not reflect the actual sequence of operations.
+
+Examples
+--------
+
+*   Output contents of ``00000000000000000000.xlog`` WAL file in the YAML format:
+
+    ..  code-block:: bash
+
+        tt cat 00000000000000000000.xlog
+
+*   Output operations on spaces with ``space_id`` 512 and 513 from the
+    ``00000000000000000012.snap`` snapshot file in the JSON format:
+
+    ..  code-block:: bash
+
+        tt cat 00000000000000000012.snap --space 512 --space 513 --format json
+
+*   Output operations on all spaces, including system spaces,
+    from the ``00000000000000000000.xlog`` WAL file:
+
+    ..  code-block:: bash
+
+        tt cat 00000000000000000000.xlog --show-system
+
+*   Output operations with LSNs between 100 and 500 on replica 1
+    from the ``00000000000000000000.xlog`` WAL file:
+
+    ..  code-block:: bash
+
+        tt cat 00000000000000000000.xlog --from 100 --to 500 --replica 1

doc/reference/tt_cli/commands.rst

@@ -32,11 +32,11 @@ help for the given command.
             -   Check an application file for syntax errors
         *   -   :doc:`connect <connect>`
             -   Connect to a Tarantool instance
-        *   -   ``rocks``
+        *   -   :doc:`rocks <rocks>`
             -   Use the LuaRocks package manager
-        *   -   ``cat``
+        *   -   :doc:`cat <cat>`
             -   Print the contents of ``.snap`` or ``.xlog`` files into stdout
-        *   -   ``play``
+        *   -   :doc:`play <play>`
             -   Play the contents of ``.snap`` or ``.xlog`` files to another Tarantool instance
 
 ..  toctree::
@@ -51,4 +51,7 @@ help for the given command.
     help <help>
     logrotate <logrotate>
     check <check>
-    connect <connect>
+    connect <connect>
+    rocks <rocks>
+    cat <cat>
+    play <play>

doc/reference/tt_cli/play.rst

@@ -0,0 +1,77 @@
+Playing the contents of .snap and .xlog files to a Tarantool instance
+=====================================================================
+
+..  code-block:: bash
+
+    tt play URI FILE .. [flags]
+
+``tt play`` plays the contents of :ref:`snapshot <internals-snapshot>` (``.snap``) and
+:ref:`WAL <internals-wal>` (``.xlog``) files to another Tarantool instance.
+A single call of ``tt play`` can play multiple files.
+
+Flags
+-----
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 20 80
+        :header-rows: 0
+
+        *   -   ``--from``
+            -   Play operations starting from the given LSN
+        *   -   ``--to``
+            -   Play operations up to the given LSN. Default: 18446744073709551615
+        *   -   ``--replica``
+            -   Filter the operations by replica id. Can be passed more than once
+        *   -   ``--space``
+            -   Filter the operations by space id. Can be passed more than once
+        *   -   ``--show-system``
+            -   Play the operations on system spaces
+
+Details
+-------
+
+``tt play`` plays operations from ``.xlog`` and ``.snap`` files to the destination
+instance one by one. All data changes happen the same way as if they were performed
+on this instance. This means that:
+
+*   All affected spaces must exist on the destination instance. They must have the same structure
+    and ``space_id`` as on the instance that created the snapshot or WAL file.
+
+    To play a snapshot or a WAL to a clean instance, include the operations on system spaces
+    by adding the ``--show-system`` flag. With this flag, ``tt`` plays the operations that
+    create and configure user-defined spaces.
+
+*   The operations' LSNs will change unless you play all operations that took place since the instance startup.
+
+*   Replica IDs will change in accordance with the destination instance configuration.
+
+
+When calling ``tt play`` with filters by LSN (``--from`` and ``--to`` flags) and
+replica ID (``--replica``), remember that LSNs differ across replicas.
+Thus, if you pass more than one replica ID via ``--from`` or ``--to``,
+the result may not reflect the actual sequence of operations.
+
+Examples
+--------
+
+*   Play the contents of ``00000000000000000000.xlog`` to the instance on
+    ``192.168.10.10:3301``:
+
+    ..  code-block:: bash
+
+        tt play 192.168.10.10:3301 00000000000000000000.xlog
+
+*   Play operations on spaces with ``space_id`` 512 and 513 from the
+    ``00000000000000000012.snap`` snapshot file:
+
+    ..  code-block:: bash
+
+        tt play 192.168.10.10:3301 00000000000000000012.snap --space 512 --space 513
+
+*   Play the contents of ``00000000000000000000.xlog`` including operations on system spaces:
+
+    ..  code-block:: bash
+
+        tt play 192.168.10.10:3301 00000000000000000000.xlog --show-system

doc/reference/tt_cli/rocks.rst

@@ -0,0 +1,145 @@
+Using the LuaRocks package manager
+==================================
+
+..  code-block:: bash
+
+    tt rocks [FLAG ...] [VAR=VALUE] COMMAND [ARGUMENT]
+
+``tt rocks`` provides means to manage Lua modules (rocks) via the
+`LuaRocks <https://luarocks.org/>`_ package manager. `tt` uses its own
+LuaRocks installation connected to the `Tarantool rocks repository <https://www.tarantool.io/en/download/rocks>`_.
+
+Below are lists of supported LuaRocks flags and commands. For detailed information on
+their usage, refer to `LuaRocks documentation <https://github.com/luarocks/luarocks/wiki/Documentation>`_.
+
+Flags
+-----
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 30 70
+        :header-rows: 0
+
+        *   -   ``--dev``
+            -   Enable the sub-repositories in rocks servers
+                for rockspecs of in-development versions
+        *   -   ``--server=<server>``
+            -   Fetch rocks/rockspecs from this server
+                (takes priority over config file)
+        *   -   ``--only-server=<server>``
+            -   Fetch rocks/rockspecs from this server only
+                (overrides any entries in the config file)
+        *   -   ``--only-sources=<url>``
+            -   Restrict downloads to paths matching the given URL
+        *   -   ``--lua-dir=<prefix>``
+            -   Specify which Lua installation to use
+        *   -   ``--lua-version=<ver>``
+            -   Specify which Lua version to use
+        *   -   ``--tree=<tree>``
+            -   Specify which tree to operate on
+        *   -   ``--local``
+            -   Use the tree in the user's home directory.
+                Call ``tt rocks help path`` to learn how to enable it
+        *   -   ``--global``
+            -   Use the system tree when `local_by_default` is `true`
+        *   -   ``--verbose``
+            -   Display verbose output for the command executed
+        *   -   ``--timeout=<seconds>``
+            -   Timeout on network operations, in seconds.
+                0 means no timeout (wait forever). Default: 30
+
+Commands
+--------
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 20 80
+        :header-rows: 0
+
+        *   -   ``build``
+            -   Build and compile a rock
+        *   -   ``config``
+            -   Query information about the LuaRocks configuration
+        *   -   ``doc``
+            -   Show documentation for an installed rock
+        *   -   ``download``
+            -   Download a specific rock file from a rocks server
+        *   -   ``help``
+            -   Help on commands. Type ``tt rocks help <command>`` for more
+        *   -   ``init``
+            -   Initialize a directory for a Lua project using LuaRocks
+        *   -   ``install``
+            -   Install a rock
+        *   -   ``lint``
+            -   Check syntax of a rockspec
+        *   -   ``list``
+            -   List the currently installed rocks
+        *   -   ``make``
+            -   Compile package in the current directory using a rockspec
+        *   -   ``make_manifest``
+            -   Compile a manifest file for a repository
+        *   -   ``new_version``
+            -   Auto-write a rockspec for a new version of a rock
+        *   -   ``pack``
+            -   Create a rock, packing sources or binaries
+        *   -   ``purge``
+            -   Remove all installed rocks from a tree
+        *   -   ``remove``
+            -   Uninstall a rock
+        *   -   ``search``
+            -   Query the LuaRocks servers
+        *   -   ``show``
+            -   Show information about an installed rock
+        *   -   ``test``
+            -   Run the test suite in the current directory
+        *   -   ``unpack``
+            -   Unpack the contents of a rock
+        *   -   ``which``
+            -   Tell which file corresponds to a given module name
+        *   -   ``write_rockspec``
+            -   Write a template for a rockspec file
+
+Examples
+--------
+
+*   Install the rock ``queue`` from the Tarantool rocks repository:
+
+    ..  code-block:: bash
+
+        tt rocks install queue
+
+*   Search for the rock ``queue`` in **both** the Tarantool rocks repository and
+    the `default LuaRocks repository <https://luarocks.org>`_:
+
+    ..  code-block:: bash
+
+        tt rocks search queue --server='https://luarocks.org'
+
+*   List the documentation files for the installed rock ``queue``:
+
+    ..  code-block:: bash
+
+        tt rocks doc queue --list
+
+    Without the ``--list`` flag, this command displays documentation in the user's default browser.
+
+*   Create a ``*.rock`` file from the installed rock ``queue``:
+
+    ..  code-block:: bash
+
+        tt rocks pack queue
+
+*   Unpack a ``*.rock`` file:
+
+    ..  code-block:: bash
+
+        tt rocks unpack queue-scm-1.all.rock
+
+*   Remove the installed rock ``queue``:
+
+    ..  code-block:: bash
+
+        tt rocks remove queue
+