Update the gel.toml description.

Add `[hooks]` and `[[watch]]` documentation.
Update the docs for the `gel watch` command as well.

docs/reference/cli/gel_watch.rst

@@ -5,25 +5,51 @@
 gel watch
 =========
 
-Start a long-running process that watches for changes in schema files in your
-project's ``dbschema`` directory and applies those changes to your current
-|branch| in real time. Starting it is as simple as running this command:
+Start a long-running process that watches for changes as specified in the
+:ref:`gel.toml <ref_reference_gel_toml>` file. This process will monitor the
+project for changes specified in the ``[[watch]]`` table array and run the
+associated scripts in response to those changes.
+
+When multiple changes target the same ``[[watch]]`` element, the corresponding
+script will be triggered only once. All triggered watch scripts will be
+executed in parallel. If the same script is triggered before it finishes
+executing, the next execution will wait for the already running script to
+terminate (i.e. only one instance of the same script will be runing at the
+same time).
 
-.. cli:synopsis::
+.. note::
 
-	gel watch
+    Any output that the triggered scripts produce will be shown in the
+    :gelcmd:`watch` console. This includes any error messages. So if you're
+    not seeing a change you've expected, check on the watch process to make
+    sure there aren't any unexpected errors in the triggered scripts.
 
-.. note::
+To learn about our recommended development migration workflow using
+:gelcmd:`watch`, read our :ref:`intro to migrations <ref_intro_migrations>`.
+
+Options
+=======
+
+.. warning::
+
+    This command changed in version 6. In older versions it only monitored the
+    schema file changes and it had no additional options.
+
+.. versionadded:: 6.0
+
+:cli:synopsis:`--migrate`
+    Watches for changes in schema files in your project's ``dbschema``
+    directory and applies those changes to your current |branch| in real time.
 
     If a schema change cannot be applied, you will see an error in the
     :gelcmd:`watch` console. You will also receive the error when you
     try to run a query with any |Gel| client binding.
 
-To learn about our recommended development migration workflow using
-:gelcmd:`watch`, read our :ref:`intro to migrations <ref_intro_migrations>`.
+    .. note::
 
-.. note::
+        If you want to apply a migration in the same manner as ``watch
+        --migrate`` but without the long-running process, use :gelcmd:`migrate
+        --dev-mode`. See :ref:`ref_cli_gel_migration_apply` for more details.
 
-    If you want to apply a migration in the same manner as ``watch`` but
-    without the long-running process, use :gelcmd:`migrate --dev-mode`. See
-    :ref:`ref_cli_gel_migration_apply` for more details.
+:cli:synopsis:`-v, --verbose`
+    Verbose output.

docs/reference/reference/gel_toml.rst

@@ -7,7 +7,7 @@ gel.toml
 The |gel.toml| file is created in the project root after running
 :ref:`ref_cli_gel_project_init`. If this file is present in a directory, it
 signals to the CLI and client bindings that the directory is an instance-linked
-|Gel| project. It supports two configuration settings across two tables:
+|Gel| project. It supports the following configuration settings:
 
 .. note::
 
@@ -45,6 +45,91 @@ signals to the CLI and client bindings that the directory is an instance-linked
   Defaults to ``dbschema``.
 
 
+[hooks] table
+=============
+
+.. versionadded:: 6
+
+This table may contain the following keys, all of which are optional:
+
+- ``project.init.before``
+- ``project.init.after``
+- ``branch.switch.before``
+- ``branch.wipe.before``
+- ``migration.apply.before``
+- ``schema.update.before``
+- ``branch.switch.after``
+- ``branch.wipe.after``
+- ``migration.apply.after``
+- ``schema.update.after``
+
+Each key represents a command hook that will be executed together with a CLI
+command. All keys have a string value which is going to be executed as a shell
+command when the corresponding hook is triggered.
+
+Hooks are divided into two categories: ``before`` and ``after`` as indicated
+by their names. All of the ``before`` hooks are executed prior to their
+corresponding commands, so they happen before any changes are made. All of the
+``after`` hooks run after the CLI command and thus the effects from the
+command are already in place. Any error during the hook script execution will
+terminate the CLI command (thus ``before`` hooks are able to prevent their
+commands from executing if certain conditions are not met).
+
+Overall, when multiple hooks are triggered they all execute sequentially in
+the order they are listed above.
+
+Here is a breakdown of which command trigger which hooks:
+
+- :ref:`ref_cli_gel_project_init` command triggers the ``project.init.before``
+  and ``project.init.after`` hook. If the migrations are applied at the end of
+  the initialization, then the ``migration.apply.before``,
+  ``schema.update.before``, ``migration.apply.after``, and
+  ``schema.update.after`` hooks are also triggered.
+- :ref:`ref_cli_gel_branch_switch` command triggers ``branch.switch.before``,
+  ``schema.update.before``, ``branch.switch.after``, and ``schema.update.after``
+  hooks in that relative order.
+- :ref:`ref_cli_gel_branch_wipe` command triggers the ``branch.wipe.before``,
+  ``schema.update.before``, ``branch.wipe.after``, and ``schema.update.after``
+  hooks in that relative order.
+- :ref:`ref_cli_gel_branch_rebase` and :ref:`ref_cli_gel_branch_merge`
+  commands trigger ``migration.apply.before``, ``schema.update.before``,
+  ``migration.apply.after``, and ``schema.update.after`` hooks in that
+  relative order. Notice that although these are branch commands, but they do
+  not change the current branch, instead they modify and apply migrations.
+  That's why they trigger the ``migration.apply`` hooks.
+- :ref:`ref_cli_gel_migration_apply` command triggers
+  ``migration.apply.before``, ``schema.update.before``,
+  ``migration.apply.after``, and ``schema.update.after`` hooks in that
+  relative order.
+
+  .. note::
+
+    All of these hooks are intended as project management tools. For this
+    reason they will only be triggered by the CLI commands that *don't
+    override* default project settings. Any CLI command that uses
+    :ref:`connection options <ref_cli_gel_connopts>` will not trigger any
+    hooks.
+
+This is implementing `RFC 1028 <rfc1028_>`_.
+
+[[watch]] table array
+=====================
+
+.. versionadded:: 6
+
+Each element of this table array may contain the following required keys:
+
+- ``files = ["<path-string>", ...]`` - specify file(s) being watched.
+
+  The paths must use ``/`` (\*nix-style) as path separators. They can also contain glob pattrens (``*``, ``**``, ``?``, etc.) in order to specify multiple files at one.
+
+- ``script = "<command>"`` - command to be executed by the shell.
+
+The watch mode can be activated by the :ref:`ref_cli_gel_watch` command.
+
+This is implementing `RFC 1028 <rfc1028_>`_.
+
+
 Example
 =======
 
@@ -56,9 +141,22 @@ Example
     [project]
     schema-dir = "db/schema"
 
+    [hooks]
+    project.init.after="setup_dsn.sh"
+    branch.wipe.after=""
+    branch.switch.after="setup_dsn.sh"
+    schema.update.after="gel-orm sqlalchemy --mod compat --out compat"
+
+    [[watch]]
+    files = ["queries/*.edgeql"]
+    script = "npx @edgedb/generate queries"
+
 .. lint-off
 
 .. _all of the same version specifications as Cargo:
    https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies
 
+.. _rfc1028:
+    https://github.com/edgedb/rfcs/blob/master/text/1028-cli-hooks.rst
+
 .. lint-on