ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

Docs: Clean up of 'file' module docs (#46327)

Browse source 
This is part of a series of module doc cleanups.
This commit is contained in:
Dag Wieers 2018-10-03 21:22:35 +02:00 committed by Sandra McCann
parent 0ab448531b
commit 79511d02a7
1 changed files with 87 additions and 78 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

165
lib/ansible/modules/files/file.py
View file

@ -12,155 +12,164 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'], 'status': ['stableinterface'],
'supported_by': 'core'} 'supported_by': 'core'}
DOCUMENTATION = r'''
DOCUMENTATION = '''
--- ---
module: file module: file
version_added: "historical" version_added: historical
short_description: Sets attributes of files short_description: Manage files and file properties
extends_documentation_fragment: files extends_documentation_fragment: files
description: description:
- Sets attributes of files, symlinks, and directories, or removes - Set attributes of files, symlinks or directories.
files/symlinks/directories. Many other modules support the same options as - Alternatively, remove files, symlinks or directories.
the C(file) module - including M(copy), M(template), and M(assemble). - Many other modules support the same options as the C(file) module - including M(copy), M(template), and M(assemble).
- For Windows targets, use the M(win_file) module instead. - For Windows targets, use the M(win_file) module instead.
notes: notes:
- For Windows targets, use the M(win_file) module instead. - For Windows targets, use the M(win_file) module instead.
- See also M(copy), M(template), M(assemble) - See also M(copy), M(template) and M(assemble).
author: author:
- Ansible Core Team - Ansible Core Team
- Michael DeHaan - Michael DeHaan
options: options:
path: path:
description: description:
- Path to the file being managed. - Path to the file being managed.
required: true required: yes
aliases: [ dest, name ] aliases: [ dest, name ]
state: state:
description: description:
- If C(directory), all intermediate subdirectories will be created if they - If C(absent), directories will be recursively deleted, and files or symlinks will
do not exist. Since Ansible 1.7 they will be created with the supplied permissions. be unlinked. Note that C(absent) will not cause C(file) to fail if the C(path) does
If C(file), the file will NOT be created if it does not exist; see the C(touch) not exist as the state did not change.
value or the M(copy) or M(template) module if you want that behavior. If C(link), the - If C(directory), all intermediate subdirectories will be created if they
symbolic link will be created or changed. Use C(hard) for hardlinks. If C(absent), do not exist. Since Ansible 1.7 they will be created with the supplied permissions.
directories will be recursively deleted, and files or symlinks will be unlinked. - If C(file), the file will NOT be created if it does not exist; see the C(touch)
Note that C(absent) will not cause C(file) to fail if the C(path) does not exist value or the M(copy) or M(template) module if you want that behavior.
as the state did not change. - If C(hard), the hard link will be created or changed.
If C(touch) (new in 1.4), an empty file will be created if the C(path) does not - If C(link), the symbolic link will be created or changed.
exist, while an existing file or directory will receive updated file access and - If C(touch) (new in 1.4), an empty file will be created if the C(path) does not
modification times (similar to the way `touch` works from the command line). exist, while an existing file or directory will receive updated file access and
modification times (similar to the way C(touch) works from the command line).
default: file default: file
choices: [ absent, directory, file, hard, link, touch ] choices: [ absent, directory, file, hard, link, touch ]
src: src:
description: description:
- path of the file to link to (applies only to C(state=link) and C(state=hard)). Will accept - Path of the file to link to.
absolute, relative and nonexisting paths. Relative paths are relative to the file being - This applies only to C(state=link) and C(state=hard).
created (C(path)) which is how the UNIX command C(ln -s SRC DEST) treats relative paths. - Will accept absolute, relative and non-existing paths.
- Relative paths are relative to the file being created (C(path)) which is how
the Unix command C(ln -s SRC DEST) treats relative paths.
recurse: recurse:
description: description:
- recursively set the specified file attributes (applies only to C(state=directory)) - Recursively set the specified file attributes.
- This applies only to C(state=directory).
type: bool type: bool
default: 'no' default: no
version_added: "1.1" version_added: '1.1'
force: force:
description: description:
- 'force the creation of the symlinks in two cases: the source file does - >
not exist (but will appear later); the destination exists and is a file (so, we need to unlink the Force the creation of the symlinks in two cases: the source file does
"path" file and create symlink to the "src" file in place of it).' not exist (but will appear later); the destination exists and is a file (so, we need to unlink the
C(path) file and create symlink to the C(src) file in place of it).
type: bool type: bool
default: 'no' default: no
follow: follow:
description: description:
- 'This flag indicates that filesystem links, if they exist, should be followed.' - This flag indicates that filesystem links, if they exist, should be followed.
- 'Previous to Ansible 2.5, this was C(no) by default.' - Previous to Ansible 2.5, this was C(no) by default.
type: bool type: bool
default: 'yes' default: yes
version_added: "1.8" version_added: '1.8'
modification_time: modification_time:
description: description:
- This parameter indicates the time the file's modification time should be set to - This parameter indicates the time the file's modification time should be set to.
- 'Should be C(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or C(now)' - Should be C(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or C(now).
- 'Default is None meaning that C(preserve) is the default for C(state=[file,directory,link,hard]) and C(now) is default for C(state=touch)' - Default is None meaning that C(preserve) is the default for C(state=[file,directory,link,hard]) and C(now) is default for C(state=touch).
version_added: "2.7" version_added: "2.7"
modification_time_format: modification_time_format:
description: description:
- 'When used with C(modification_time), indicates the time format that must be used.' - When used with C(modification_time), indicates the time format that must be used.
- 'Based on default Python format (see time.strftime doc)' - Based on default Python format (see time.strftime doc).
default: "%Y%m%d%H%M.%S" default: "%Y%m%d%H%M.%S"
version_added: "2.7" version_added: '2.7'
access_time: access_time:
description: description:
- This parameter indicates the time the file's access time should be set to - This parameter indicates the time the file's access time should be set to.
- 'Should be C(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or C(now)' - Should be C(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or C(now).
- 'Default is None meaning that C(preserve) is the default for C(state=[file,directory,link,hard]) and C(now) is default for C(state=touch)' - Default is C(None) meaning that C(preserve) is the default for C(state=[file,directory,link,hard]) and C(now) is default for C(state=touch).
version_added: "2.7" version_added: '2.7'
access_time_format: access_time_format:
description: description:
- 'When used with C(access_time), indicates the time format that must be used.' - When used with C(access_time), indicates the time format that must be used.
- 'Based on default Python format (see time.strftime doc)' - Based on default Python format (see time.strftime doc).
default: "%Y%m%d%H%M.%S" default: "%Y%m%d%H%M.%S"
version_added: "2.7" version_added: '2.7'
''' '''
EXAMPLES = ''' EXAMPLES = '''
# change file ownership, group and mode - name: Change file ownership, group and permissions
- file: file:
path: /etc/foo.conf path: /etc/foo.conf
owner: foo owner: foo
group: foo group: foo
# when specifying mode using octal numbers, add a leading 0 # When specifying mode using octal numbers, add a leading 0
mode: 0644 mode: 0644
- file:
- name: Create an insecure file
file:
path: /work path: /work
owner: root owner: root
group: root group: root
mode: 01777 # Or use quotes instead
- file: mode: '1777'
- name: Create a symbolic link
file:
src: /file/to/link/to src: /file/to/link/to
dest: /path/to/symlink dest: /path/to/symlink
owner: foo owner: foo
group: foo group: foo
state: link state: link
- file:
- name: Create two hard links
file:
src: '/tmp/{{ item.src }}' src: '/tmp/{{ item.src }}'
dest: '{{ item.dest }}' dest: '{{ item.dest }}'
state: link state: link
with_items: with_items:
- { src: 'x', dest: 'y' } - { src: x, dest: y }
- { src: 'z', dest: 'k' } - { src: z, dest: k }
# touch a file, using symbolic modes to set the permissions (equivalent to 0644) - name: Touch a file, using symbolic modes to set the permissions (equivalent to 0644)
- file: file:
path: /etc/foo.conf path: /etc/foo.conf
state: touch state: touch
mode: "u=rw,g=r,o=r" mode: u=rw,g=r,o=r
# touch the same file, but add/remove some permissions - name: Touch the same file, but add/remove some permissions
- file: file:
path: /etc/foo.conf path: /etc/foo.conf
state: touch state: touch
mode: "u+rw,g-wx,o-rwx" mode: u+rw,g-wx,o-rwx
# touch again the same file, but dont change times - name: Touch again the same file, but dont change times this makes the task idempotent
# this makes the task idempotents file:
- file:
path: /etc/foo.conf path: /etc/foo.conf
state: touch state: touch
mode: "u+rw,g-wx,o-rwx" mode: u+rw,g-wx,o-rwx
modification_time: "preserve" modification_time: preserve
access_time: "preserve" access_time: preserve
# create a directory if it doesn't exist - name: Create a directory if it does not exist
- file: file:
path: /etc/some_directory path: /etc/some_directory
state: directory state: directory
mode: 0755 mode: 0755
# updates modification and access time of given file - name: Update modification and access time of given file
- file: file:
path: /etc/some_file path: /etc/some_file
state: file state: file
mode: 0755
modification_time: now modification_time: now
access_time: now access_time: now
''' '''