Merging upstream version 24.6.1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 42 insertions, 5 deletions

diff --git a/docs/configuring.md b/docs/configuring.md
index e67bbbc..f61f1f7 100644
--- a/docs/configuring.md
+++ b/docs/configuring.md
@@ -5,10 +5,10 @@ You can ignore certain rules, enable `opt-in` rules, and control various other
 settings.
 
 Ansible-lint loads configuration from a file in the current working directory or
-from a file that you specify in the command line. If you provide configuration
-on both via a config file and on the command line, list values are merged (for
-example `exclude_paths`) and **True** is preferred for boolean values like
-`quiet`.
+from a file that you specify in the command line.
+
+Any configuration option that is passed from the command line will override
+the one specified inside the configuration file.
 
 ## Using local configuration files
 
@@ -57,17 +57,54 @@ Keep in mind that this will override any existing file content.
 
 ## Pre-commit setup
 
-To use Ansible-lint with [pre-commit], add the following to the
+To use Ansible-lint with the [pre-commit] tool, add the following to the
 `.pre-commit-config.yaml` file in your local repository.
 
+Do not confuse the [pre-commit] tool with the git hook feature that has the same name.
+While the [pre-commit] tool can also make use of git hooks, it does not require
+them and it does not install them by default.
+
+[pre-commit.ci] is a hosted service that can run pre-commit for you
+on each change but you can also run the tool yourself using the CI of your choice.
+
 Change **rev:** to either a commit sha or tag of Ansible-lint that contains
 `.pre-commit-hooks.yaml`.
 
 ```yaml
+---
+ci:
+  # This section is specific to pre-commit.ci, telling it to create a pull request
+  # to update the linter version tag every month.
+  autoupdate_schedule: monthly
+  # If you have other Ansible collection dependencies (requirements.yml)
+  # `pre-commit.ci` will not be able to install them because it runs in offline mode,
+  # and you will need to tell it to skip the hook.
+  # skip:
+  #   - ansible-lint
+repos:
 - repo: https://github.com/ansible/ansible-lint
   rev: ... # put latest release tag from https://github.com/ansible/ansible-lint/releases/
   hooks:
     - id: ansible-lint
+      # Uncomment if you need the full Ansible community bundle instead of ansible-core:
+      # additional_dependencies:
+      #   - ansible
 ```
 
+!!! warning
+
+    [pre-commit] always uses python virtual environments. If you happen to
+    use the [Ansible package] instead of just [ansible-core] you might be surprised
+    to see that pre-commit is not able to find these collections, even if
+    your local Ansible does. This is because they are installed inside a location
+    that is not available to the virtual environment in which pre-commit hook
+    is installed. In this case, you might want to uncomment the commented lines
+    from the hook definition above, so the bundle will be installed.
+
+    You should note that collection installed into `~/.ansible` are found by
+    the hook.
+
 [pre-commit]: https://pre-commit.com/
+[Ansible package]: https://pypi.org/project/ansible/
+[ansible-core]: https://pypi.org/project/ansible-core/
+[pre-commit.ci]: https://pre-commit.ci/