Skip to content

Commit

Permalink
Clarify documentation for no-changed-when
Browse files Browse the repository at this point in the history
Fixes: #2629
  • Loading branch information
ssbarnea committed Feb 17, 2023
1 parent 95d8895 commit 0fa79e2
Showing 1 changed file with 15 additions and 3 deletions.
18 changes: 15 additions & 3 deletions src/ansiblelint/rules/no_changed_when.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,19 @@
# no-changed-when

This rule checks that tasks return changes to results or conditions.
Unless tasks only read information, you should ensure that they return changes in the following ways:
This rule checks that tasks return changes to results or conditions. Unless
tasks only read information, you should ensure that they return changes in the
following ways:

- Register results or conditions and use the `changed_when` clause.
- Use the `creates` or `removes` argument.

You should use the `when` clause to run tasks only if a check returns a particular result.
You should always use the `changed_when` clause on tasks that do not naturally
detect if a change has occurred or not. Some of the most common examples are
[shell] and [command] modules, which run arbitrary commands.

One very common workaround is to use a boolean value like `changed_when: false`
but you can also use any expressions, including ones that use the registered
result of a task, like in our example below.

## Problematic Code

Expand All @@ -31,3 +38,8 @@ You should use the `when` clause to run tasks only if a check returns a particul
register: my_output # <- Registers the command output.
changed_when: my_output.rc != 0 # <- Uses the return code to define when the task has changed.
```

[shell]:
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/shell_module.html
[command]:
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/command_module.html

0 comments on commit 0fa79e2

Please sign in to comment.