+#vcsrepo\r
+\r
+####Table of Contents\r
+\r
+1. [Overview](#overview)\r
+2. [Module Description - What the module does and why it is useful](#module-description)\r
+3. [Setup - The basics of getting started with vcsrepo](#setup)\r
+ * [Setup requirements](#setup-requirements)\r
+ * [Beginning with vcsrepo](#beginning-with-vcsrepo)\r
+4. [Usage - Configuration options and additional functionality](#usage)\r
+ * [Git](#git)\r
+ * [Bazaar](#bazaar)\r
+ * [CVS](#cvs)\r
+ * [Mercurial](#mercurial)\r
+ * [Perforce](#perforce)\r
+ * [Subversion](#subversion) \r
+5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\r
+ * [Type: vcsrepo](#type-vcsrepo)\r
+ * [Providers](#providers)\r
+ * [Features](#features)\r
+ * [Parameters](#parameters)\r
+5. [Limitations - OS compatibility, etc.](#limitations)\r
+6. [Development - Guide for contributing to the module](#development)\r
+\r
+##Overview\r
+\r
+The vcsrepo module lets you use Puppet to easily deploy content from your version control system (VCS).\r
+\r
+##Module Description\r
+\r
+The vcsrepo module provides a single type with providers to support the following version control systems:\r
+\r
+* [Git](#git)\r
+* [Bazaar](#bazaar)\r
+* [CVS](#cvs)\r
+* [Mercurial](#mercurial)\r
+* [Perforce](#perforce)\r
+* [Subversion](#subversion)\r
+\r
+**Note:** `git` is the only vcs provider officially [supported by Puppet Labs](https://forge.puppetlabs.com/supported).\r
+\r
+##Setup\r
+\r
+###Setup Requirements\r
+\r
+The `vcsrepo` module does not install any VCS software for you. You must install a VCS before you can use this module.\r
+\r
+Like Puppet in general, the `vcsrepo` module does not automatically create parent directories for the files it manages. Make sure to set up any needed directory structures before you get started.\r
+\r
+###Beginning with vcsrepo\r
+\r
+To create and manage a blank repository, define the type `vcsrepo` with a path to your repository and supply the `provider` parameter based on the [VCS you're using](#usage).\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => git,\r
+}\r
+~~~\r
+\r
+##Usage\r
+\r
+**Note:** `git` is the only vcsrepo provider officially [supported by Puppet Labs](https://forge.puppetlabs.com/supported).\r
+\r
+###Git\r
+\r
+####Create a blank repository\r
+\r
+To create a blank repository, suitable for use as a central repository, define `vcsrepo` without `source` or `revision`:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => git,\r
+}\r
+~~~\r
+\r
+If you're managing a central or official repository, you might want to make it a bare repository. To do this, set `ensure` to 'bare':\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => bare,\r
+ provider => git,\r
+}\r
+~~~\r
+\r
+####Clone/pull a repository\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => git,\r
+ source => 'git://example.com/repo.git',\r
+}\r
+~~~\r
+\r
+By default, `vcsrepo` will use the HEAD of the source repository's master branch. To use another branch or a specific commit, set `revision` to either a branch name or a commit SHA or tag.\r
+\r
+Branch name:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => git,\r
+ source => 'git://example.com/repo.git',\r
+ revision => 'development',\r
+}\r
+~~~\r
+\r
+SHA:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => git,\r
+ source => 'git://example.com/repo.git',\r
+ revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31',\r
+}\r
+~~~\r
+\r
+Tag:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => git,\r
+ source => 'git://example.com/repo.git',\r
+ revision => '1.1.2rc1',\r
+}\r
+~~~\r
+\r
+To check out a branch as a specific user, supply the `user` parameter:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => git,\r
+ source => 'git://example.com/repo.git',\r
+ revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31',\r
+ user => 'someUser',\r
+}\r
+~~~\r
+\r
+To keep the repository at the latest revision, set `ensure` to 'latest'.\r
+\r
+**WARNING:** this overwrites any local changes to the repository:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => latest,\r
+ provider => git,\r
+ source => 'git://example.com/repo.git',\r
+ revision => 'master',\r
+}\r
+~~~\r
+\r
+To clone the repository but skip initializing submodules, set `submodules` to 'false':\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => latest,\r
+ provider => git,\r
+ source => 'git://example.com/repo.git',\r
+ submodules => false,\r
+}\r
+~~~\r
+\r
+####Use multiple remotes with a repository\r
+In place of a single string, you can set `source` to a hash of one or more name => URL pairs:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => git,\r
+ remote => 'origin'\r
+ source => {\r
+ 'origin' => 'https://github.com/puppetlabs/puppetlabs-vcsrepo.git', \r
+ 'other_remote' => 'https://github.com/other_user/puppetlabs-vcsrepo.git'\r
+ },\r
+}\r
+~~~\r
+\r
+**Note:** if you set `source` to a hash, one of the names you specify must match the value of the `remote` parameter. That remote serves as the upstream of your managed repository.
+\r
+####Connect via SSH\r
+\r
+To connect to your source repository via SSH (e.g., 'username@server:…'), we recommend managing your SSH keys with Puppet and using the [`require`](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) metaparameter to make sure they are present before the `vcsrepo` resource is applied.\r
+\r
+To use SSH keys associated with a user, specify the username in the `user` parameter:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => latest,\r
+ provider => git,\r
+ source => 'git://username@example.com/repo.git',\r
+ user => 'toto', #uses toto's $HOME/.ssh setup\r
+ require => File['/home/toto/.ssh/id_rsa'],\r
+}\r
+~~~
+\r
+###Bazaar\r
+\r
+####Create a blank repository\r
+\r
+To create a blank repository, suitable for use as a central repository, define `vcsrepo` without `source` or `revision`:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => bzr,\r
+}\r
+~~~\r
+\r
+####Branch from an existing repository\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => bzr,\r
+ source => '/some/path',\r
+}\r
+~~~\r
+\r
+To branch from a specific revision, set `revision` to a valid [Bazaar revisionspec](http://wiki.bazaar.canonical.com/BzrRevisionSpec):\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => bzr,\r
+ source => '/some/path',\r
+ revision => 'menesis@pov.lt-20100309191856-4wmfqzc803fj300x',\r
+}\r
+~~~\r
+\r
+####Connect via SSH\r
+\r
+To connect to your source repository via SSH (e.g., `'bzr+ssh://...'` or `'sftp://...,'`), we recommend using the [`require`](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) metaparameter to make sure your SSH keys are present before the `vcsrepo` resource is applied:\r
+
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => latest,\r
+ provider => bzr,\r
+ source => 'bzr+ssh://bzr.example.com/some/path',\r
+ user => 'toto', #uses toto's $HOME/.ssh setup\r
+ require => File['/home/toto/.ssh/id_rsa'],\r
+}\r
+~~~
+\r
+###CVS\r
+\r
+####Create a blank repository\r
+\r
+To create a blank repository, suitable for use as a central repository, define `vcsrepo` without `source` or `revision`:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => cvs,\r
+}\r
+~~~\r
+\r
+####Checkout/update from a repository\r
+\r
+~~~\r
+vcsrepo { '/path/to/workspace':\r
+ ensure => present,\r
+ provider => cvs,\r
+ source => ':pserver:anonymous@example.com:/sources/myproj',\r
+}\r
+~~~\r
+\r
+To get a specific module on the current mainline, supply the `module` parameter:\r
+\r
+~~~\r
+vcsrepo {'/vagrant/lockss-daemon-source':\r
+ ensure => present,\r
+ provider => cvs,\r
+ source => ':pserver:anonymous@lockss.cvs.sourceforge.net:/cvsroot/lockss',\r
+ module => 'lockss-daemon',\r
+}\r
+~~~\r
+\r
+To set the GZIP compression levels for your repository history, use the `compression` parameter:\r
+\r
+~~~\r
+vcsrepo { '/path/to/workspace':\r
+ ensure => present,\r
+ provider => cvs,\r
+ compression => 3,\r
+ source => ':pserver:anonymous@example.com:/sources/myproj',\r
+}\r
+~~~\r
+\r
+To get a specific revision, set `revision` to the revision number.\r
+\r
+~~~\r
+vcsrepo { '/path/to/workspace':\r
+ ensure => present,\r
+ provider => cvs,\r
+ compression => 3,\r
+ source => ':pserver:anonymous@example.com:/sources/myproj',\r
+ revision => '1.2',\r
+}\r
+~~~
+
+You can also set `revision` to a tag:\r
+
+~~~\r
+vcsrepo { '/path/to/workspace':\r
+ ensure => present,\r
+ provider => cvs,\r
+ compression => 3,\r
+ source => ':pserver:anonymous@example.com:/sources/myproj',\r
+ revision => 'SOMETAG',\r
+}\r
+~~~
+\r
+####Connect via SSH\r
+\r
+To connect to your source repository via SSH, we recommend using the [`require`](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) metaparameter to make sure your SSH keys are present before the `vcsrepo` resource is applied:\r
+
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => latest,\r
+ provider => cvs,\r
+ source => ':pserver:anonymous@example.com:/sources/myproj',\r
+ user => 'toto', #uses toto's $HOME/.ssh setup\r
+ require => File['/home/toto/.ssh/id_rsa'],\r
+}\r
+~~~\r
+\r
+###Mercurial\r
+\r
+####Create a blank repository\r
+\r
+To create a blank repository, suitable for use as a central repository, define `vcsrepo` without `source` or `revision`:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => hg,\r
+}\r
+~~~\r
+\r
+####Clone/pull & update a repository\r
+\r
+To get the default branch tip:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => hg,\r
+ source => 'http://hg.example.com/myrepo',\r
+}\r
+~~~\r
+\r
+For a specific changeset, use `revision`:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => hg,\r
+ source => 'http://hg.example.com/myrepo',\r
+ revision => '21ea4598c962',\r
+}\r
+~~~\r
+\r
+You can also set `revision` to a tag:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => hg,\r
+ source => 'http://hg.example.com/myrepo',\r
+ revision => '1.1.2',\r
+}\r
+~~~\r
+\r
+To check out as a specific user:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => hg,\r
+ source => 'http://hg.example.com/myrepo',\r
+ user => 'user',\r
+}\r
+~~~\r
+\r
+To specify an SSH identity key:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => hg,\r
+ source => 'ssh://hg@hg.example.com/myrepo',\r
+ identity => '/home/user/.ssh/id_dsa1,\r
+}\r
+~~~\r
+\r
+To specify a username and password for HTTP Basic authentication:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => latest,\r
+ provider => hg,\r
+ source => 'http://hg.example.com/myrepo',\r
+ basic_auth_username => 'hgusername',\r
+ basic_auth_password => 'hgpassword',\r
+}\r
+~~~\r
+\r
+####Connect via SSH \r
+\r
+To connect to your source repository via SSH (e.g., `'ssh://...'`), we recommend using the [`require` metaparameter](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) to make sure your SSH keys are present before the `vcsrepo` resource is applied:\r
+
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => latest,\r
+ provider => hg,\r
+ source => 'ssh://hg.example.com//path/to/myrepo',\r
+ user => 'toto', #uses toto's $HOME/.ssh setup\r
+ require => File['/home/toto/.ssh/id_rsa'],\r
+}\r
+~~~\r
+\r
+###Perforce\r
+
+####Create an empty workspace
+
+To set up the connection to your Perforce service, set `p4config` to the location of a valid Perforce [config file](http://www.perforce.com/perforce/doc.current/manuals/p4guide/chapter.configuration.html#configuration.settings.configfiles) stored on the node:
+
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => p4,\r
+ p4config => '/root/.p4config'\r
+}\r
+~~~\r
+
+**Note:** If you don't include the `P4CLIENT` setting in your config file, the provider generates a workspace name based on the digest of `path` and the node's hostname (e.g., `puppet-91bc00640c4e5a17787286acbe2c021c`):
+
+####Create/update and sync a Perforce workspace\r
+\r
+To sync a depot path to head, set `ensure` to 'latest':\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => latest,\r
+ provider => p4,\r
+ source => '//depot/branch/...'\r
+}\r
+~~~\r
+\r
+To sync to a specific changelist, specify its revision number with the `revision` parameter:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => p4,\r
+ source => '//depot/branch/...',\r
+ revision => '2341'\r
+}\r
+~~~\r
+\r
+You can also set `revision` to a label:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => p4,\r
+ source => '//depot/branch/...',\r
+ revision => 'my_label'\r
+}\r
+~~~\r
+\r
+###Subversion\r
+\r
+####Create a blank repository\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => svn,\r
+}\r
+~~~\r
+\r
+####Check out from an existing repository\r
+\r
+Provide a `source` pointing to the branch or tag you want to check out:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => svn,\r
+ source => 'svn://svnrepo/hello/branches/foo',\r
+}\r
+~~~\r
+\r
+You can also designate a specific revision:\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => svn,\r
+ source => 'svn://svnrepo/hello/branches/foo',\r
+ revision => '1234',\r
+}\r
+~~~\r
+\r
+####Use a specific Subversion configuration directory \r
+\r
+Use the `configuration` parameter to designate the directory that contains your Subversion configuration files (typically, '/path/to/.subversion'):\r
+\r
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => present,\r
+ provider => svn,\r
+ source => 'svn://svnrepo/hello/branches/foo',\r
+ configuration => '/path/to/.subversion',\r
+}\r
+~~~\r
+\r
+####Connect via SSH \r
+\r
+To connect to your source repository via SSH (e.g., `'svn+ssh://...'`), we recommend using the [`require` metaparameter](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) to make sure your SSH keys are present before the `vcsrepo` resource is applied:\r
+
+~~~\r
+vcsrepo { '/path/to/repo':\r
+ ensure => latest,\r
+ provider => svn,\r
+ source => 'svn+ssh://svnrepo/hello/branches/foo',\r
+ user => 'toto', #uses toto's $HOME/.ssh setup\r
+ require => File['/home/toto/.ssh/id_rsa'],\r
+}\r
+~~~\r
+\r
+##Reference\r
+\r
+###Type: vcsrepo\r
+\r
+The vcsrepo module adds only one type with several providers. Each provider abstracts a different VCS, and each provider includes a set of features according to its needs.\r
+\r
+####Providers\r
+\r
+**Note:** Not all features are available with all providers.\r
+\r
+#####`git` - Supports the Git VCS.\r
+\r
+Features: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `submodules`, `user`
+\r
+Parameters: `depth`, `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `remote`, `revision`, `source`, `user`\r
+\r
+#####`bzr` - Supports the Bazaar VCS.\r
+\r
+Features: `reference_tracking`\r
+\r
+Parameters: `ensure`, `excludes`, `force`, `group`, `owner`, `path`, `provider`, `revision`, `source`
+\r
+#####`cvs` - Supports the CVS VCS.\r
+\r
+Features: `cvs_rsh`, `gzip_compression`, `modules`, `reference_tracking`, `user`\r
+
+Parameters: `compression`, `cvs_rsh`, `ensure`, `excludes`, `force`, `group`, `module`, `owner`, `path`, `provider`
+\r
+#####`hg` - Supports the Mercurial VCS.\r
+\r
+Features: `reference_tracking`, `ssh_identity`, `user`
+\r
+Parameters: `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `revision`, `source`, `user`
+\r
+#####`p4` - Supports the Perforce VCS.\r
+\r
+Features: `p4config`, `reference_tracking`
+\r
+Parameters: `ensure`, `excludes`, `force`, `group`, `owner`, `p4config`, `path`, `provider`, `revision`, `source`
+\r
+#####`svn` - Supports the Subversion VCS.\r
+\r
+Features: `basic_auth`, `configuration`, `conflict`, `filesystem_types`, `reference_tracking`
+
+Parameters: `basic_auth_password`, `basic_auth_username`, `configuration`, `conflict`, `ensure`, `excludes`, `force`, `fstype`, `group`, `owner`, `path`, `provider`, `revision`, `source`\r
+\r
+####Features\r
+\r
+**Note:** Not all features are available with all providers.\r
+\r
+* `bare_repositories` - Differentiates between bare repositories and those with working copies. (Available with `git`.)\r
+* `basic_auth` - Supports HTTP Basic authentication. (Available with `svn`.)
+* `conflict` - Lets you decide how to resolve any conflicts between the source repository and your working copy. (Available with `svn`.)\r
+* `configuration` - Lets you specify the location of your configuration files. (Available with `svn`.)\r
+* `cvs_rsh` - Understands the `CVS_RSH` environment variable. (Available with `cvs`.)\r
+* `depth` - Supports shallow clones. (Available with `git`.)\r
+* `filesystem_types` - Supports multiple types of filesystem. (Available with `svn`.)\r
+* `gzip_compression` - Supports explicit GZip compression levels. (Available with `cvs`.)\r
+* `modules` - Lets you choose a specific repository module. (Available with `cvs`.)\r
+* `multiple_remotes` - Tracks multiple remote repositories. (Available with `git`.)\r
+* `reference_tracking` - Lets you track revision references that can change over time (e.g., some VCS tags and branch names). (Available with all providers)\r
+* `ssh_identity` - Lets you specify an SSH identity file. (Available with `git` and `hg`.)\r
+* `user` - Can run as a different user. (Available with `git`, `hg` and `cvs`.)\r
+* `p4config` - Supports setting the `P4CONFIG` environment. (Available with `p4`.)\r
+* `submodules` - Supports repository submodules which can be optionally initialized. (Available with `git`.)\r
+\r
+####Parameters\r
+\r
+All parameters are optional, except where specified otherwise.
+
+##### `basic_auth_password`
projects / puppet_vcsrepo.git / blobdiff