Support streams and fix Marshal for 'p4 cstat'
[puppet_vcsrepo.git] / README.markdown
index d0b9169..d977886 100644 (file)
@@ -13,6 +13,7 @@
     * [CVS](#cvs)
     * [Git](#git)
     * [Mercurial](#mercurial)
+    * [Perforce](#perforce)
     * [Subversion](#subversion)  
 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
     * [Type: vcsrepo](#type-vcsrepo)
@@ -25,7 +26,7 @@
 
 ##Overview
 
-The vcsrepo module allows you to use Puppet to easily deploy code from your version control system (VCS).
+The vcsrepo module allows you to use Puppet to easily deploy content from your version control system (VCS).
 
 ##Module Description
 
@@ -57,6 +58,7 @@ The vcsrepo module works with the following VCSs:
 * [CVS (cvs)](#cvs)
 * [Git (git)](#git)
 * [Mercurial (hg)](#mercurial)
+* [Perforce (p4)](#perforce)
 * [Subversion (svn)](#subversion)
 
 ###Bazaar
@@ -246,7 +248,7 @@ For SSH keys associated with a user, enter the username in the `user` parameter.
 
 #####Further Examples
 
-For for more examples using Git, see `examples/git/`.
+For more examples using Git, see `examples/git/`.
 
 ###Mercurial
 
@@ -314,6 +316,71 @@ When your source uses SSH, such as 'ssh://...', you can manage your SSH keys wit
 
 For more examples using Mercurial, see `examples/hg/`.
 
+###Perforce
+
+#####To create an empty Workspace
+
+To create an empty Workspace, define a `vcsrepo` without a `source` or `revision`.  The 
+Environment variables P4PORT, P4USER, etc... are used to define the Perforce server
+connection settings.
+
+    vcsrepo { "/path/to/repo":
+      ensure     => present,
+      provider   => p4
+    }
+
+If no `P4CLIENT` environment name is provided a workspace generated name is calculated
+based on the Digest of path and hostname.  For example:
+
+    puppet-91bc00640c4e5a17787286acbe2c021c
+
+A Perforce configuration file can be used by setting the `P4CONFIG` environment or
+defining `p4config`.  If a configuration is defined, then the environment variable for 
+`P4CLIENT` is replaced.
+    vcsrepo { "/path/to/repo":
+      ensure     => present,
+      provider   => p4,
+      p4config   => '.p4config'
+    }
+
+#####To create/update and sync a Perforce workspace
+
+To sync a depot path to head, ensure `latest`:
+
+    vcsrepo { "/path/to/repo":
+        ensure   => latest,
+        provider => p4,
+        source   => '//depot/branch/...'
+    }
+
+For a specific changelist, ensure `present` and specify a `revision`:
+
+    vcsrepo { "/path/to/repo":
+        ensure   => present,
+        provider => p4,
+        source   => '//depot/branch/...',
+        revision => '2341'
+    }
+
+You can also set `revision` to a label:
+
+    vcsrepo { "/path/to/repo":
+        ensure   => present,
+        provider => p4,
+        source   => '//depot/branch/...',
+        revision => 'my_label'
+    }
+
+#####To authenticate against the Perforce server
+
+Either set the environment variables `P4USER` and `P4PASSWD` or use a configuration file.
+For secure servers set the `P4PASSWD` with a valid ticket generated using `p4 login -p`.
+
+#####Further Examples
+
+For examples you can run, see `examples/p4/`
+
 ###Subversion
 
 #####To create a blank repository
@@ -415,7 +482,7 @@ The vcsrepo module is slightly unusual in that it is simply a type and providers
 * `module` - Specifies the repository module to manage. (Requires the `modules` feature.)
 * `owner` - Specifies the user/uid that owns the repository files.
 *  `path` - Specifies the absolute path to the repository. If omitted, the value defaults to the resource's title.
-* `provider` - The specific backend to use for this vcsrepo resource. Puppet will usually discover the appropriate provider for your platform.
+* `provider` - Specifies the backend to use for this vcsrepo resource. 
 * `remote` - Specifies the remote repository to track. (Requires the `multiple_remotes` feature.)
 * `revision` - Sets the revision of the repository. Values can match /^\S+$/.
 * `source` - Specifies the source URI for the repository.