From 698123713032c1a968797d088eb7d797985a149f Mon Sep 17 00:00:00 2001
From: Abhijeet Kasurde <akasurde@redhat.com>
Date: Sat, 25 Sep 2021 00:10:13 +0530
Subject: [PATCH] ad-hoc: add documentation about pattern (#73303)

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
---
 docs/docsite/rst/user_guide/intro_adhoc.rst   |  6 ++++
 .../docsite/rst/user_guide/intro_patterns.rst | 30 +++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/docs/docsite/rst/user_guide/intro_adhoc.rst b/docs/docsite/rst/user_guide/intro_adhoc.rst
index 4d91abe8c3a..a0de3fa8e8d 100644
--- a/docs/docsite/rst/user_guide/intro_adhoc.rst
+++ b/docs/docsite/rst/user_guide/intro_adhoc.rst
@@ -190,6 +190,12 @@ Facts represent discovered variables about a system. You can use facts to implem
 
 You can also filter this output to display only certain facts, see the :ref:`ansible.builtin.setup <setup_module>` module documentation for details.
 
+Patterns and ad-hoc commands
+----------------------------
+
+See the :ref:`patterns <intro_patterns>` documentation for details on all of the available options, including
+how to limit using patterns in ad-hoc commands.
+
 Now that you understand the basic elements of Ansible execution, you are ready to learn to automate repetitive tasks using :ref:`Ansible Playbooks <playbooks_intro>`.
 
 .. seealso::
diff --git a/docs/docsite/rst/user_guide/intro_patterns.rst b/docs/docsite/rst/user_guide/intro_patterns.rst
index 8d7615f9c6c..ec38301a519 100644
--- a/docs/docsite/rst/user_guide/intro_patterns.rst
+++ b/docs/docsite/rst/user_guide/intro_patterns.rst
@@ -142,6 +142,36 @@ You can specify a pattern as a regular expression by starting the pattern with `
 
     ~(web|db).*\.example\.com
 
+Patterns and ad-hoc commands
+----------------------------
+
+You can change the behavior of the patterns defined in ad-hoc commands using command-line options.
+You can also limit the hosts you target on a particular run with the ``--limit`` flag.
+
+* Limit to one host
+
+.. code-block:: bash
+
+    $ ansible -m [module] -a "[module options]" --limit "host1"
+
+* Limit to multiple hosts
+
+.. code-block:: bash
+
+    $ ansible -m [module] -a "[module options]" --limit "host1,host2"
+
+* Negated limit. Note that single quotes MUST be used to prevent bash interpolation.
+
+.. code-block:: bash
+
+    $ ansible -m [module] -a "[module options]" --limit 'all:!host1'
+
+* Limit to host group
+
+.. code-block:: bash
+
+    $ ansible -m [module] -a "[module options]" --limit 'group1'
+
 Patterns and ansible-playbook flags
 -----------------------------------