3 [](https://travis-ci.org/puppetlabs/puppetlabs-vcsrepo)
7 1. [Overview](#overview)
8 2. [Module Description - What the module does and why it is useful](#module-description)
9 3. [Setup - The basics of getting started with vcsrepo](#setup)
10 * [Beginning with vcsrepo](#beginning-with-vcsrepo)
11 4. [Usage - Configuration options and additional functionality](#usage)
15 * [Mercurial](#mercurial)
16 * [Perforce](#perforce)
17 * [Subversion](#subversion)
18 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
19 * [Type: vcsrepo](#type-vcsrepo)
20 * [Providers](#providers)
21 * [Features](#features)
22 * [Parameters](#parameters)
23 * [Features and Parameters by Provider](#features-and-parameters-by-provider)
24 5. [Limitations - OS compatibility, etc.](#limitations)
25 6. [Development - Guide for contributing to the module](#development)
29 The vcsrepo module allows you to use Puppet to easily deploy content from your version control system (VCS).
33 This module provides a single type with providers for each VCS, which can be used to describe:
35 * A working copy checked out from a (remote or local) source, at an
37 * A blank working copy not associated with a source (when it makes
38 sense for the VCS being used)
39 * A blank central repository (when the distinction makes sense for the VCS
44 ###Beginning with vcsrepo
46 To get started with the vcsrepo module, you must simply define the type `vcsrepo` with a path to your repository and the [type of VCS](#Usage) you're using in `provider` (in the below example, Git).
48 vcsrepo { "/path/to/repo":
55 The vcsrepo module works with the following VCSs:
57 * [Bazaar (bzr)](#bazaar)
60 * [Mercurial (hg)](#mercurial)
61 * [Perforce (p4)](#perforce)
62 * [Subversion (svn)](#subversion)
66 #####Create a blank repository
68 To create a blank repository suitable for use as a central repository,
69 define `vcsrepo` without `source` or `revision`.
71 vcsrepo { "/path/to/repo":
76 #####Branch from an existing repository
78 Provide the `source` location to branch from an existing repository.
80 vcsrepo { "/path/to/repo":
83 source => 'lp:myproj',
86 For a specific revision, use `revision` with a valid revisionspec
87 (see `bzr help revisionspec` for more information on formatting a revision).
89 vcsrepo { "/path/to/repo":
92 source => 'lp:myproj',
93 revision => 'menesis@pov.lt-20100309191856-4wmfqzc803fj300x',
96 #####Sources that use SSH
98 When your source uses SSH, for instance 'bzr+ssh://...' or 'sftp://...,'
99 you can manage your SSH keys with Puppet using the [require](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) metaparameter in `vcsrepo` to ensure they are present.
101 #####Further examples
103 For more examples using Bazaar, see `examples/bzr/`.
107 #####To create a blank repository
109 To create a blank repository suitable for use as a central repository,
110 define `vcsrepo` without `source` or `revision`.
112 vcsrepo { "/path/to/repo":
117 #####To checkout/update from a repository
119 To get the current mainline,
121 vcsrepo { "/path/to/workspace":
124 source => ":pserver:anonymous@example.com:/sources/myproj",
127 To get a specific module on the current mainline,
129 vcsrepo {"/vagrant/lockss-daemon-source":
132 source => ":pserver:anonymous@lockss.cvs.sourceforge.net:/cvsroot/lockss",
133 module => "lockss-daemon",
137 You can use the `compression` parameter to set the GZIP compression levels for your repository history.
139 vcsrepo { "/path/to/workspace":
143 source => ":pserver:anonymous@example.com:/sources/myproj",
146 For a specific tag, use `revision`.
148 vcsrepo { "/path/to/workspace":
152 source => ":pserver:anonymous@example.com:/sources/myproj",
153 revision => "SOMETAG",
156 #####Sources that use SSH
158 When your source uses SSH, you can manage your SSH keys with Puppet using the [require](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) metaparameter in `vcsrepo` to ensure they are present.
160 #####Further examples
162 For for more examples using CVS, see `examples/cvs/`.
166 #####To create a blank repository
168 To create a blank repository suitable for use as a central repository,
169 define `vcsrepo` without `source` or `revision`.
171 vcsrepo { "/path/to/repo":
176 If you're defining `vcsrepo` for a central or official repository, you may want to make it a bare repository. You do this by setting `ensure` to 'bare' rather than 'present'.
178 vcsrepo { "/path/to/repo":
183 #####To clone/pull a repository
185 To get the current HEAD on the master branch,
187 vcsrepo { "/path/to/repo":
190 source => "git://example.com/repo.git",
193 To get a specific revision or branch (can be a commit SHA, tag, or branch name),
197 vcsrepo { "/path/to/repo":
200 source => 'git://example.com/repo.git',
201 revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31',
206 vcsrepo { "/path/to/repo":
209 source => 'git://example.com/repo.git',
210 revision => '1.1.2rc1',
215 vcsrepo { "/path/to/repo":
218 source => 'git://example.com/repo.git',
219 revision => 'development',
222 To check out a branch as a specific user,
224 vcsrepo { "/path/to/repo":
227 source => 'git://example.com/repo.git',
228 revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31',
232 To keep the repository at the latest revision (**WARNING:** this will always overwrite local changes to the repository),
234 vcsrepo { "/path/to/repo":
237 source => 'git://example.com/repo.git',
238 revision => 'master',
241 #####Sources that use SSH
243 When your source uses SSH, such as 'username@server:…', you can manage your SSH keys with Puppet using the [require](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) metaparameter in `vcsrepo` to ensure they are present.
245 For SSH keys associated with a user, enter the username in the `user` parameter. Doing so will use that user's keys.
247 user => 'toto' # will use toto's $HOME/.ssh setup
249 #####Further Examples
251 For more examples using Git, see `examples/git/`.
255 #####To create a blank repository
257 To create a blank repository suitable for use as a central repository,
258 define `vcsrepo` without `source` or `revision`.
260 vcsrepo { "/path/to/repo":
265 #####To clone/pull & update a repository
267 To get the default branch tip,
269 vcsrepo { "/path/to/repo":
272 source => "http://hg.example.com/myrepo",
275 For a specific changeset, use `revision`.
277 vcsrepo { "/path/to/repo":
280 source => "http://hg.example.com/myrepo",
281 revision => '21ea4598c962',
284 You can also set `revision` to a tag.
286 vcsrepo { "/path/to/repo":
289 source => "http://hg.example.com/myrepo",
293 To check out as a specific user,
295 vcsrepo { "/path/to/repo":
298 source => "http://hg.example.com/myrepo",
302 To specify an SSH identity key,
304 vcsrepo { "/path/to/repo":
307 source => "ssh://hg@hg.example.com/myrepo",
308 identity => "/home/user/.ssh/id_dsa,
311 #####Sources that use SSH
313 When your source uses SSH, such as 'ssh://...', you can manage your SSH keys with Puppet using the [require](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) metaparameter in `vcsrepo` to ensure they are present.
315 #####Further Examples
317 For more examples using Mercurial, see `examples/hg/`.
321 #####To create an empty Workspace
323 To create an empty Workspace, define a `vcsrepo` without a `source` or `revision`. The
324 Environment variables P4PORT, P4USER, etc... are used to define the Perforce server
327 vcsrepo { "/path/to/repo":
332 If no `p4client` name is provided a workspace generated name is calculated based on the
333 Digest of path. For example:
335 puppet-91bc00640c4e5a17787286acbe2c021c
337 Providing a `p4client` name will create/update the client workspace in Perforce. The
338 value replaces the P4CLIENT environment variable.
340 vcsrepo { "/path/to/repo":
343 p4client => "my_client_ws"
346 #####To create/update and sync a Perforce workspace
348 To sync a depot path to head (latest):
350 vcsrepo { "/path/to/repo":
353 source => '//depot/branch/...'
356 For a specific changelist, use `revision`:
358 vcsrepo { "/path/to/repo":
361 source => '//depot/branch/...',
365 You can also set `revision` to a label:
367 vcsrepo { "/path/to/repo":
370 source => '//depot/branch/...',
371 revision => 'my_label'
374 Check out as a user by setting `p4user`:
376 vcsrepo { "/path/to/repo":
379 source => '//depot/branch/...',
383 You can set `p4port` to specify a Perforce server:
385 vcsrepo { "/path/to/repo":
388 source => '//depot/branch/...',
389 p4port => 'ssl:perforce.com:1666'
392 You can set `p4passwd` for authentication :
394 vcsrepo { "/path/to/repo":
397 source => '//depot/branch/...',
398 p4port => 'ssl:perforce.com:1666'
401 If `p4port`, `p4user`, `p4charset`, `p4passwd` or `p4client` are specified they will
402 override the environment variabels P4PORT, P4USER, etc... If a P4CONFIG file is defined,
403 the config file settings will take precedence.
405 #####Further Examples
407 For examples you can run, see `examples/p4/`
411 #####To create a blank repository
413 To create a blank repository suitable for use as a central repository,
414 define `vcsrepo` without `source` or `revision`.
416 vcsrepo { "/path/to/repo":
421 #####To check out from a repository
423 Provide a `source` pointing to the branch/tag you want to check out from a repository.
425 vcsrepo { "/path/to/repo":
428 source => "svn://svnrepo/hello/branches/foo",
431 You can also provide a specific revision.
433 vcsrepo { "/path/to/repo":
436 source => "svn://svnrepo/hello/branches/foo",
440 #####Using a specific Subversion configuration directory
442 To use a specific configuration directory, provide a `configuration` parameter which should be a directory path on the local system where your svn configuration files are. Typically, it is '/path/to/.subversion'.
444 vcsrepo { "/path/to/repo":
447 source => "svn://svnrepo/hello/branches/foo",
448 configuration => "/path/to/.subversion",
451 #####Sources that use SSH
453 When your source uses SSH, such as 'svn+ssh://...', you can manage your SSH keys with Puppet using the [require](http://docs.puppetlabs.com/references/stable/metaparameter.html#require) metaparameter in `vcsrepo` to ensure they are present.
457 For more examples using Subversion, see `examples/svn/`.
463 The vcsrepo module is slightly unusual in that it is simply a type and providers. Each provider abstracts a different VCS, and a series of features are available to each provider based on its specific needs.
467 **Note**: Not all features are available with all providers.
469 * `bar` - Supports the Bazaar VCS. (Contains features: `reference_tracking`.)
470 * `cvs` - Supports the CVS VCS. (Contains features: `cvs_rsh`, `gzip_compression`, `modules`,`reference_tracking`.)
472 * `git` - Supports the Git VCS. (Contains features: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `user`.)
473 * `hg` - Supports the Mercurial VCS. (Contains features: `reference_tracking`, `ssh_identity`, `user`.)
474 * `svn` - Supports the Subversion VCS. (Contains features: `basic_auth`, `configuration`, `filesystem_types`, `reference_tracking`.)
478 **Note**: Not all features are available with all providers.
480 * `bare_repositories` - The provider differentiates between bare repositories and those with working copies. (Available with `git`.)
481 * `basic_auth` - The provider supports HTTP Basic Authentication. (Available with `svn`.)
482 * `configuration` - The provider supports setting the configuration path.(Available with `svn`.)
483 * `cvs_rsh` - The provider understands the CVS_RSH environment variable. (Available with `cvs`.)
484 * `depth` - The provider can do shallow clones. (Available with `git`.)
485 * `filesystem_types` - The provider supports different filesystem types. (Available with `svn`.)
486 * `gzip_compression` - The provider supports explicit GZip compression levels. (Available with `cvs`.)
487 * `modules` - The provider allows specific repository modules to be chosen. (Available with `cvs`.)
488 * `multiple_remotes` - The repository tracks multiple remote repositories. (Available with `git`.)
489 * `reference_tracking` - The provider supports tracking revision references that can change over time (e.g. some VCS tags and branch names). (Available with `bar`, `cvs`, `git`, `hg`, `svn`.)
490 * `ssh_identity` - The provider supports a configurable SSH identity file. (Available with `git` and `hg`.)
491 * `user` - The provider can run as a different user. (Available with `git` and `hg`.)
495 * `basic_auth_password` - Specifies the HTTP Basic Authentication password. (Requires the `basic_auth` feature.)
496 * `basic_auth_username` - Specifies the HTTP Basic Authentication username. (Requires the `basic_auth` feature.)
497 * `compression` - Set the GZIP compression levels for your repository history. (Requires the `gzip_compression` feature.)
498 * `configuration` - Sets the configuration directory to use. (Requires the `configuration` feature.)
499 * `cvs_rsh` - The value to be used for the CVS_RSH environment variable. (Requires the `cvs_rsh` feature.)
500 * `depth` - The value to be used to do a shallow clone. (Requires the `depth` feature.)
501 * `ensure` - Determines the state of the repository. Valid values are 'present', 'bare', 'absent', 'latest'.
502 * `excludes` - Lists any files to be excluded from the repository.
503 * `force` - Forces repository creation. Valid values are 'true' and 'false'. **WARNING** Forcing will destroy any files in the path.
504 * `fstype` - Sets the filesystem type. (Requires the `filesystem_types` feature.)
505 * `group` - Determines the group/gid that owns the repository files.
506 * `identity` - Specifies the SSH identity file. (Requires the `ssh_identity` feature.)
507 * `module` - Specifies the repository module to manage. (Requires the `modules` feature.)
508 * `owner` - Specifies the user/uid that owns the repository files.
509 * `path` - Specifies the absolute path to the repository. If omitted, the value defaults to the resource's title.
510 * `provider` - Specifies the backend to use for this vcsrepo resource.
511 * `remote` - Specifies the remote repository to track. (Requires the `multiple_remotes` feature.)
512 * `revision` - Sets the revision of the repository. Values can match /^\S+$/.
513 * `source` - Specifies the source URI for the repository.
514 * `user` - Specifies the user to run as for repository operations.
516 ####Features and Parameters by Provider
519 **Features**: `reference_tracking`
521 **Parameters**: `ensure`, `excludes`, `force`, `group`, `owner`, `path`, `provider`, `revision`, `source`, `user`
524 **Features**: `cvs_rsh`, `gzip_compression`, `modules`, `reference_tracking`, `revision`
526 **Parameters**: `compression`, `cvs_rsh`, `ensure`, `excludes`, `force`, `group`, `module`, `owner`, `path`, `provider`, `revision`, `source`, `user`
529 **Features**: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `user`
531 **Parameters**: `depth`, `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `remote`, `revision`, `source`, `user`
534 **Features**: `reference_tracking`, `ssh_identity`, `user`
536 **Parameters**: `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `revision`, `source`, `user`
539 **Features**: `basic_auth`, `configuration`, `filesystem_types`, `reference_tracking`
541 **Parameters**: `basic_auth_password`, `basic_auth_username`, `configuration`, `ensure`, `excludes`, `force`, `fstype`, `group`, `owner`, `path`, `provider`, `revision`, `source`, `user`
545 This module has been built on and tested against Puppet 2.7 and higher.
547 The module has been tested on:
549 RedHat Enterprise Linux 5/6
557 Testing on other platforms has been light and cannot be guaranteed.
561 Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
563 We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
565 You can read the complete module contribution guide on the Puppet Labs wiki.