diff --git a/docs/source/code_examples/macro_commands/opt.ys b/docs/source/code_examples/macro_commands/opt.ys
index cb883bc58..ebd938836 100644
--- a/docs/source/code_examples/macro_commands/opt.ys
+++ b/docs/source/code_examples/macro_commands/opt.ys
@@ -9,6 +9,7 @@ do
     opt_merge
     opt_share  (-full only)
     opt_dff  (except when called with -noff)
+    opt_hier (-hier only)
     opt_clean
     opt_expr
 while <changed design>
diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst
index 743b24997..43b558739 100644
--- a/docs/source/using_yosys/synthesis/opt.rst
+++ b/docs/source/using_yosys/synthesis/opt.rst
@@ -192,6 +192,13 @@ control inputs.
 Called with ``-nodffe`` and ``-nosdff``, this pass is used to prepare a design
 for :doc:`/using_yosys/synthesis/fsm`.
 
+Hierarchical optimization - `opt_hier` pass
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This pass considers the design hierarchy and propagates unused signals, constant
+signals, and tied-together signals across module boundaries to facilitate
+optimization by other passes.
+
 Removing unused cells and wires - `opt_clean` pass
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~