From 02f44176b940b8432ff31fc49a4632ed3315522e Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Mon, 26 Mar 2018 08:01:54 -0700 Subject: [PATCH] Document the relationship between octal numbers and the leading zero Fixes #37875 --- lib/ansible/utils/module_docs_fragments/files.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/lib/ansible/utils/module_docs_fragments/files.py b/lib/ansible/utils/module_docs_fragments/files.py index 8f263f73d41..a50dfbce16a 100644 --- a/lib/ansible/utils/module_docs_fragments/files.py +++ b/lib/ansible/utils/module_docs_fragments/files.py @@ -23,9 +23,12 @@ class ModuleDocFragment(object): options: mode: description: - - Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers (like C(0644) or C(01777)). - Leaving off the leading zero will likely have unexpected results. - As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). + - "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers. + You must either specify the leading zero so that Ansible's YAML parser knows it is an octal + number (like C(0644) or C(01777)) or quote it (like C('644') or C('0644') so Ansible + receives a string and can do its own conversion from string into number. Giving Ansible a number + without following one of these rules will end up with a decimal number which will have unexpected results. + As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r))." owner: description: - Name of the user that should own the file/directory, as would be fed to I(chown).