From 74b120329c528e1e92619b60c2bbd52a398dc858 Mon Sep 17 00:00:00 2001
From: Brian Coca <bcoca@users.noreply.github.com>
Date: Wed, 14 Feb 2018 17:01:36 -0500
Subject: [PATCH] never tags docs and test (#35964)

* fufilling the promise

* moved changes

* Copy edit

(cherry picked from commit 0cf70a897032c75c7d20b65942de40d220b5c69f)
---
 docs/docsite/rst/user_guide/playbooks_tags.rst | 18 +++++++++++++++---
 test/integration/targets/tags/runme.sh         |  4 ++++
 test/integration/targets/tags/test_tags.yml    |  3 +++
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/docs/docsite/rst/user_guide/playbooks_tags.rst b/docs/docsite/rst/user_guide/playbooks_tags.rst
index 00c86009a39..82fd91ff7a0 100644
--- a/docs/docsite/rst/user_guide/playbooks_tags.rst
+++ b/docs/docsite/rst/user_guide/playbooks_tags.rst
@@ -129,11 +129,23 @@ Example::
           tags:
             - tag1
 
-There are another 3 special keywords for tags, ``tagged``, ``untagged`` and ``all``, which run only tagged, only untagged
-and all tasks respectively.
+.. versionadded:: 2.5
+
+Another special tag is ``never``, which will prevent a task from running unless a tag is specifically requested.
 
-By default ansible runs as if ``--tags all`` had been specified.
+Example::
+
+    tasks:
+      - debug: msg='{{ showmevar}}'
+        tags: [ 'never', 'debug' ]
+
+In this example, the task will only run when the ``debug`` or ``never`` tag is explicitly requested.
+
+
+There are another 3 special keywords for tags: ``tagged``, ``untagged`` and ``all``, which run only tagged, only untagged
+and all tasks respectively.
 
+By default, Ansible runs as if ``--tags all`` had been specified.
 
 .. seealso::
 
diff --git a/test/integration/targets/tags/runme.sh b/test/integration/targets/tags/runme.sh
index d1f26c41d0a..a8b1c90e1ae 100755
--- a/test/integration/targets/tags/runme.sh
+++ b/test/integration/targets/tags/runme.sh
@@ -35,3 +35,7 @@ export LC_ALL=en_US.UTF-8
 # Run a tag from a list of tags and always
 [ "$("${COMMAND[@]}" --tags café | grep -F Task_with | xargs)" = \
 "Task_with_always_tag TAGS: [always] Task_with_list_of_tags TAGS: [café, press]" ]
+
+# Run tag with never
+[ "$("${COMMAND[@]}" --tags donever | grep -F Task_with | xargs)" = \
+"Task_with_always_tag TAGS: [always] Task_with_never_tag TAGS: [donever, never]" ]
diff --git a/test/integration/targets/tags/test_tags.yml b/test/integration/targets/tags/test_tags.yml
index f7e0467fe70..5f575da7627 100644
--- a/test/integration/targets/tags/test_tags.yml
+++ b/test/integration/targets/tags/test_tags.yml
@@ -20,3 +20,6 @@
       - press
     - name: Task_without_tag
       debug: msg=
+    - name: Task_with_never_tag
+      debug: msg=NEVER
+      tags: ['never', 'donever']