diff --git a/docs/docsite/rst/user_guide/playbooks_tags.rst b/docs/docsite/rst/user_guide/playbooks_tags.rst index 0a66e5b2e94..09c043e1164 100644 --- a/docs/docsite/rst/user_guide/playbooks_tags.rst +++ b/docs/docsite/rst/user_guide/playbooks_tags.rst @@ -5,11 +5,6 @@ If you have a large playbook, it may become useful to be able to run only a specific part of it rather than running *everything* in the playbook. Ansible supports a "tags:" attribute for this reason. -When you execute a playbook, you can filter tasks based on tags in two ways: - -- On the command line, with the ``--tags`` or ``--skip-tags`` options -- In Ansible configuration settings, with the ``TAGS_RUN`` and ``TAGS_SKIP`` options - Tags can be applied to *many* structures in Ansible (see "tag inheritance", below), but its simplest use is with individual tasks. Here is an example that tags two tasks with different tags:: @@ -29,7 +24,14 @@ that tags two tasks with different tags:: tags: - configuration -If you wanted to just run the "configuration" and "packages" part of a very long playbook, you can use the ``--tags`` option on the command line:: +When you execute a playbook, you can filter tasks based on tags in two ways: + +- On the command line, with the ``--tags`` or ``--skip-tags`` options +- In Ansible configuration settings, with the ``TAGS_RUN`` + and ``TAGS_SKIP`` options + +For example, if you wanted to just run the "configuration" and "packages" part +of a very long playbook, you can use the ``--tags`` option on the command line:: ansible-playbook example.yml --tags "configuration,packages" @@ -38,8 +40,15 @@ tasks, you can use the ``--skip-tags`` command-line option:: ansible-playbook example.yml --skip-tags "packages" +You can see which tasks will be executed with ``--tags`` or ``--skip-tags`` by +combining it with ``--list-tasks``:: + + ansible-playbook example.yml --tags "configuration,packages" --list-tasks + .. warning:: - * Fact gathering is tagged with 'always' by default. It is ONLY skipped if you apply a tag and then use a different tag in ``--tags`` or the same tag in ``--skip-tags``. + * Fact gathering is tagged with 'always' by default. It is ONLY skipped if + you apply a tag and then use a different tag in ``--tags`` or the same + tag in ``--skip-tags``. .. _tag_reuse: @@ -129,14 +138,16 @@ Tags are applied *down* the dependency chain. In order for a tag to be inherited to a dependent role's tasks, the tag should be applied to the role declaration or static import, not to all the tasks within the role. -There is no way to 'import only these tags'; you probably want to split into smaller roles/includes if you find yourself looking for such a feature. +There is no way to 'import only these tags'; you probably want to split +into smaller roles/includes if you find yourself looking for such a feature. -The above information does not apply to `include_tasks` or other dynamic includes, -as the attributes applied to an include, only affect the include itself. +The above information does not apply to `include_tasks` or other dynamic +includes, as the attributes applied to an include, only affect the include +itself. You can see which tags are applied to tasks, roles, and static imports by running ``ansible-playbook`` with the ``--list-tasks`` option. You can -display all tags applied to the tasks with the ``--list-tags`` option. +display all tags available with the ``--list-tags`` option. .. note:: The above information does not apply to `include_tasks`, `include_roles`, @@ -175,7 +186,8 @@ Role tasks file:: Special Tags ```````````` -There is a special ``always`` tag that will always run a task, unless specifically skipped (``--skip-tags always``) +There is a special ``always`` tag that will always run a task, unless +specifically skipped (``--skip-tags always``) Example:: @@ -192,7 +204,8 @@ Example:: .. versionadded:: 2.5 -Another special tag is ``never``, which will prevent a task from running unless a tag is specifically requested. +Another special tag is ``never``, which will prevent a task from running unless +a tag is specifically requested. Example:: @@ -200,10 +213,12 @@ Example:: - debug: msg="{{ showmevar }}" tags: [ never, debug ] -In this example, the task will only run when the ``debug`` or ``never`` tag is explicitly requested. +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 +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.