From 04196e20a8964ae0748bba9e7eb6a1ecc05291d6 Mon Sep 17 00:00:00 2001
From: Matthew Williams <matthew@flowroute.com>
Date: Sun, 1 Apr 2012 17:03:13 -0700
Subject: [PATCH] docs for file module -- symbolic links

---
 rst/modules.rst | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/rst/modules.rst b/rst/modules.rst
index c7c205e1efb..d9e46e21cce 100644
--- a/rst/modules.rst
+++ b/rst/modules.rst
@@ -124,8 +124,9 @@ module behind the scenes.
 file
 ````
 
-Sets attributes of files and directories, or removes files/directories.  All parameters available 
-to the file module are also available when running the `copy` or `template` modules.
+Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. 
+All parameters available to the file module are also available when running the `copy` or 
+`template` modules.
 
 *dest*:
 
@@ -133,7 +134,7 @@ to the file module are also available when running the `copy` or `template` modu
 
 *state*:
 
-* either 'file', 'directory', or 'absent'.  The default is 'file'.  If 'directory', the directory and all immediate subdirectories will be created if they do not exist.  If 'file', the file will NOT be created if it does not exist, specify `copy` or `template` for the module name instead if you need to put content at the specified location.  If 'absent', directories will be recursively deleted, and files or symlinks will be unlinked.
+* either 'file', 'link', 'directory', or 'absent'.  The default is 'file'.  If 'directory', the directory and all immediate subdirectories will be created if they do not exist.  If 'file', the file will NOT be created if it does not exist, specify `copy` or `template` for the module name instead if you need to put content at the specified location.  if 'link', the symbolic link will be created or changed.  If 'absent', directories will be recursively deleted, and files or symlinks will be unlinked.
 
 *mode*:
 
@@ -147,12 +148,21 @@ to the file module are also available when running the `copy` or `template` modu
 
 * name of group that should own the file or directory, as would be given to `chgrp`
 
-Example action from Ansible :doc:`playbooks`::
+*src*:
+
+* path to the file to link to (applies only to 'link' state)
+
+*dest*:
+
+* location where the symlink is to be created (applies only to 'link' state)
 
-    file dest=/etc/foo.conf owner=foo group=foo mode=0644
-    file dest=/some/path owner=foo group=foo state=directory
-    file dest/path/to/delete state=absent
 
+Example action from Ansible :doc:`playbooks`::
+
+    file path=/etc/foo.conf owner=foo group=foo mode=0644
+    file path=/some/path owner=foo group=foo state=directory
+    file /path/to/delete state=absent
+    file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link
 
 git
 ```