with_filetree:: use splitext for compatibility with template: (#2285)

* with_filetree: use splitext for compatibility with template

The example code given deploys files with their .j2 extensions intact, which is probably not what you want.

* Explain how templates interact with splitext|first

* Update plugins/lookup/filetree.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Don't encourage setting the mode of symlinks

On ext4, maybe most filesystems, symlinks always have the artificial mode of 0777, and `chmod $mode $symlink` *writes through* the symlink to its target file.

An effect of this is that if you deploy a file and a symlink to it (e.g. this common situation: /etc/nginx/sites-available/default and /etc/nginx/sites-enabled/default -> ../sites-available/default) then `with_filetree` will forever first deploy the file with the right mode, then corrupt its mode to 0777, and every redeploy will see a change to fix, forever in a loop.

Probably `file:` should refuse `mode:` on `state: link`s, but in the meantime, avoid recommending it in `filetree`

* Use `follow: false` instead of just the mode.

This should be more cross-compatible.

https://github.com/ansible-collections/community.general/pull/2285#discussion_r616571873

* Update plugins/lookup/filetree.py

Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/lookup/filetree.py

@@ -31,7 +31,9 @@ EXAMPLES = r"""
 - name: Template files (explicitly skip directories in order to use the 'src' attribute)
   ansible.builtin.template:
     src: '{{ item.src }}'
-    dest: /web/{{ item.path }}
+    # Your template files should be stored with a .j2 file extension,
+    # but should not be deployed with it. splitext|first removes it.
+    dest: /web/{{ item.path | splitext | first }}
     mode: '{{ item.mode }}'
   with_community.general.filetree: web/
   when: item.state == 'file'
@@ -41,6 +43,7 @@ EXAMPLES = r"""
     src: '{{ item.src }}'
     dest: /web/{{ item.path }}
     state: link
+    follow: false  # avoid corrupting target files if the link already exists
     force: yes
     mode: '{{ item.mode }}'
   with_community.general.filetree: web/