Merge pull request #41 from mgwilliams/file-module-symlinks

docs for file module -- symbolic links

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
 ```