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:
58 * [Bazaar (bzr)](#bazaar)
60 * [Mercurial (hg)](#mercurial)
61 * [Perforce (p4)](#perforce)
62 * [Subversion (svn)](#subversion)
64 **Note:* Git is the only VCS provider officially [supported](https://forge.puppetlabs.com/supported) by Puppet Labs.
69 #####To create a blank repository
71 To create a blank repository suitable for use as a central repository,
72 define `vcsrepo` without `source` or `revision`.
74 vcsrepo { "/path/to/repo":
79 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'.
81 vcsrepo { "/path/to/repo":
86 #####To clone/pull a repository
88 To get the current HEAD on the master branch,
90 vcsrepo { "/path/to/repo":
93 source => "git://example.com/repo.git",
96 To get a specific revision or branch (can be a commit SHA, tag, or branch name),
100 vcsrepo { "/path/to/repo":
103 source => 'git://example.com/repo.git',
104 revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31',
109 vcsrepo { "/path/to/repo":
112 source => 'git://example.com/repo.git',
113 revision => '1.1.2rc1',
118 vcsrepo { "/path/to/repo":
121 source => 'git://example.com/repo.git',
122 revision => 'development',
125 To check out a branch as a specific user,
127 vcsrepo { "/path/to/repo":
130 source => 'git://example.com/repo.git',
131 revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31',
135 To keep the repository at the latest revision (**WARNING:** this will always overwrite local changes to the repository),
137 vcsrepo { "/path/to/repo":
140 source => 'git://example.com/repo.git',
141 revision => 'master',
144 #####Sources that use SSH
146 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.
148 For SSH keys associated with a user, enter the username in the `user` parameter. Doing so will use that user's keys.
150 user => 'toto' # will use toto's $HOME/.ssh setup
152 #####Further Examples
154 For more examples using Git, see `examples/git/`.
158 #####Create a blank repository
160 To create a blank repository suitable for use as a central repository,
161 define `vcsrepo` without `source` or `revision`.
163 vcsrepo { "/path/to/repo":
168 #####Branch from an existing repository
170 Provide the `source` location to branch from an existing repository.
172 vcsrepo { "/path/to/repo":
175 source => 'lp:myproj',
178 For a specific revision, use `revision` with a valid revisionspec
179 (see `bzr help revisionspec` for more information on formatting a revision).
181 vcsrepo { "/path/to/repo":
184 source => 'lp:myproj',
185 revision => 'menesis@pov.lt-20100309191856-4wmfqzc803fj300x',
188 #####Sources that use SSH
190 When your source uses SSH, for instance 'bzr+ssh://...' or 'sftp://...,'
191 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.
193 #####Further examples
195 For more examples using Bazaar, see `examples/bzr/`.
199 #####To create a blank repository
201 To create a blank repository suitable for use as a central repository,
202 define `vcsrepo` without `source` or `revision`.
204 vcsrepo { "/path/to/repo":
209 #####To checkout/update from a repository
211 To get the current mainline,
213 vcsrepo { "/path/to/workspace":
216 source => ":pserver:anonymous@example.com:/sources/myproj",
219 To get a specific module on the current mainline,
221 vcsrepo {"/vagrant/lockss-daemon-source":
224 source => ":pserver:anonymous@lockss.cvs.sourceforge.net:/cvsroot/lockss",
225 module => "lockss-daemon",
229 You can use the `compression` parameter to set the GZIP compression levels for your repository history.
231 vcsrepo { "/path/to/workspace":
235 source => ":pserver:anonymous@example.com:/sources/myproj",
238 For a specific tag, use `revision`.
240 vcsrepo { "/path/to/workspace":
244 source => ":pserver:anonymous@example.com:/sources/myproj",
245 revision => "SOMETAG",
248 #####Sources that use SSH
250 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.
252 #####Further examples
254 For for more examples using CVS, see `examples/cvs/`.
258 #####To create a blank repository
260 To create a blank repository suitable for use as a central repository,
261 define `vcsrepo` without `source` or `revision`.
263 vcsrepo { "/path/to/repo":
268 #####To clone/pull & update a repository
270 To get the default branch tip,
272 vcsrepo { "/path/to/repo":
275 source => "http://hg.example.com/myrepo",
278 For a specific changeset, use `revision`.
280 vcsrepo { "/path/to/repo":
283 source => "http://hg.example.com/myrepo",
284 revision => '21ea4598c962',
287 You can also set `revision` to a tag.
289 vcsrepo { "/path/to/repo":
292 source => "http://hg.example.com/myrepo",
296 To check out as a specific user,
298 vcsrepo { "/path/to/repo":
301 source => "http://hg.example.com/myrepo",
305 To specify an SSH identity key,
307 vcsrepo { "/path/to/repo":
310 source => "ssh://hg@hg.example.com/myrepo",
311 identity => "/home/user/.ssh/id_dsa,
314 To specify a username and password for HTTP Basic authentication,
316 vcsrepo { "/path/to/repo":
319 source => 'http://hg.example.com/myrepo',
320 basic_auth_username => 'hgusername',
321 basic_auth_password => 'hgpassword',
324 #####Sources that use SSH
326 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.
328 #####Further Examples
330 For more examples using Mercurial, see `examples/hg/`.
334 #####To create an empty Workspace
336 To create an empty Workspace, define a `vcsrepo` without a `source` or `revision`. The
337 Environment variables P4PORT, P4USER, etc... are used to define the Perforce server
340 vcsrepo { "/path/to/repo":
345 If no `P4CLIENT` environment name is provided a workspace generated name is calculated
346 based on the Digest of path and hostname. For example:
348 puppet-91bc00640c4e5a17787286acbe2c021c
350 A Perforce configuration file can be used by setting the `P4CONFIG` environment or
351 defining `p4config`. If a configuration is defined, then the environment variable for
352 `P4CLIENT` is replaced.
354 vcsrepo { "/path/to/repo":
357 p4config => '.p4config'
360 #####To create/update and sync a Perforce workspace
362 To sync a depot path to head, ensure `latest`:
364 vcsrepo { "/path/to/repo":
367 source => '//depot/branch/...'
370 For a specific changelist, ensure `present` and specify a `revision`:
372 vcsrepo { "/path/to/repo":
375 source => '//depot/branch/...',
379 You can also set `revision` to a label:
381 vcsrepo { "/path/to/repo":
384 source => '//depot/branch/...',
385 revision => 'my_label'
388 #####To authenticate against the Perforce server
390 Either set the environment variables `P4USER` and `P4PASSWD` or use a configuration file.
391 For secure servers set the `P4PASSWD` with a valid ticket generated using `p4 login -p`.
393 #####Further Examples
395 For examples you can run, see `examples/p4/`
399 #####To create a blank repository
401 To create a blank repository suitable for use as a central repository,
402 define `vcsrepo` without `source` or `revision`.
404 vcsrepo { "/path/to/repo":
409 #####To check out from a repository
411 Provide a `source` pointing to the branch/tag you want to check out from a repository.
413 vcsrepo { "/path/to/repo":
416 source => "svn://svnrepo/hello/branches/foo",
419 You can also provide a specific revision.
421 vcsrepo { "/path/to/repo":
424 source => "svn://svnrepo/hello/branches/foo",
428 #####Using a specific Subversion configuration directory
430 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'.
432 vcsrepo { "/path/to/repo":
435 source => "svn://svnrepo/hello/branches/foo",
436 configuration => "/path/to/.subversion",
439 #####Sources that use SSH
441 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.
445 For more examples using Subversion, see `examples/svn/`.
451 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.
455 **Note**: Not all features are available with all providers.
457 * `git` - Supports the Git VCS. (Contains features: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `user`.)
458 * `bar` - Supports the Bazaar VCS. (Contains features: `reference_tracking`.)
459 * `cvs` - Supports the CVS VCS. (Contains features: `cvs_rsh`, `gzip_compression`, `modules`,`reference_tracking`.)
461 * `hg` - Supports the Mercurial VCS. (Contains features: `reference_tracking`, `ssh_identity`, `user`.)
462 * `p4` - Supports the Perforce VCS. (Contains features: `reference_tracking`, `filesystem_types`, `p4config`.)
463 * `svn` - Supports the Subversion VCS. (Contains features: `basic_auth`, `configuration`, `filesystem_types`, `reference_tracking`.)
467 **Note**: Not all features are available with all providers.
469 * `bare_repositories` - The provider differentiates between bare repositories and those with working copies. (Available with `git`.)
470 * `basic_auth` - The provider supports HTTP Basic Authentication. (Available with `svn`.)
471 * `configuration` - The provider supports setting the configuration path.(Available with `svn`.)
472 * `cvs_rsh` - The provider understands the CVS_RSH environment variable. (Available with `cvs`.)
473 * `depth` - The provider can do shallow clones. (Available with `git`.)
474 * `filesystem_types` - The provider supports different filesystem types. (Available with `svn`.)
475 * `gzip_compression` - The provider supports explicit GZip compression levels. (Available with `cvs`.)
476 * `modules` - The provider allows specific repository modules to be chosen. (Available with `cvs`.)
477 * `multiple_remotes` - The repository tracks multiple remote repositories. (Available with `git`.)
478 * `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`.)
479 * `ssh_identity` - The provider supports a configurable SSH identity file. (Available with `git` and `hg`.)
480 * `user` - The provider can run as a different user. (Available with `git` and `hg`.)
481 * `p4config` - The provider support setting the P4CONFIG environment. (Available with `p4`.)
485 * `basic_auth_password` - Specifies the HTTP Basic Authentication password. (Requires the `basic_auth` feature.)
486 * `basic_auth_username` - Specifies the HTTP Basic Authentication username. (Requires the `basic_auth` feature.)
487 * `compression` - Set the GZIP compression levels for your repository history. (Requires the `gzip_compression` feature.)
488 * `configuration` - Sets the configuration directory to use. (Requires the `configuration` feature.)
489 * `cvs_rsh` - The value to be used for the CVS_RSH environment variable. (Requires the `cvs_rsh` feature.)
490 * `depth` - The value to be used to do a shallow clone. (Requires the `depth` feature.)
491 * `ensure` - Determines the state of the repository. Valid values are 'present', 'bare', 'absent', 'latest'.
492 * `excludes` - Lists any files to be excluded from the repository.
493 * `force` - Forces repository creation. Valid values are 'true' and 'false'. **WARNING** Forcing will destroy any files in the path.
494 * `fstype` - Sets the filesystem type. (Requires the `filesystem_types` feature.)
495 * `group` - Determines the group/gid that owns the repository files.
496 * `identity` - Specifies the SSH identity file. (Requires the `ssh_identity` feature.)
497 * `module` - Specifies the repository module to manage. (Requires the `modules` feature.)
498 * `owner` - Specifies the user/uid that owns the repository files.
499 * `path` - Specifies the absolute path to the repository. If omitted, the value defaults to the resource's title.
500 * `provider` - Specifies the backend to use for this vcsrepo resource.
501 * `remote` - Specifies the remote repository to track. (Requires the `multiple_remotes` feature.)
502 * `revision` - Sets the revision of the repository. Values can match /^\S+$/.
503 * `source` - Specifies the source URI for the repository.
504 * `user` - Specifies the user to run as for repository operations.
505 * `p4config` - Specifies the P4CONFIG environment used for Perforce connection configuration.
507 ####Features and Parameters by Provider
510 **Features**: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `user`
512 **Parameters**: `depth`, `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `remote`, `revision`, `source`, `user`
515 **Features**: `reference_tracking`
517 **Parameters**: `ensure`, `excludes`, `force`, `group`, `owner`, `path`, `provider`, `revision`, `source`, `user`
520 **Features**: `cvs_rsh`, `gzip_compression`, `modules`, `reference_tracking`, `revision`
522 **Parameters**: `compression`, `cvs_rsh`, `ensure`, `excludes`, `force`, `group`, `module`, `owner`, `path`, `provider`, `revision`, `source`, `user`
525 **Features**: `reference_tracking`, `ssh_identity`, `user`
527 **Parameters**: `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `revision`, `source`, `user`
530 **Features**: `reference_tracking`, `filesystem_types`, `p4config`
532 **Parameters**: `ensure`, `group`, `owner`, `path`, `provider`, `revision`, `source`, `p4config`
535 **Features**: `basic_auth`, `configuration`, `filesystem_types`, `reference_tracking`
537 **Parameters**: `basic_auth_password`, `basic_auth_username`, `configuration`, `ensure`, `excludes`, `force`, `fstype`, `group`, `owner`, `path`, `provider`, `revision`, `source`, `user`
541 Git is the only VCS provider officially [supported](https://forge.puppetlabs.com/supported) by Puppet Labs.
543 This module has been built on and tested against Puppet 2.7 and higher.
545 The module has been tested on:
547 RedHat Enterprise Linux 5/6
555 Testing on other platforms has been light and cannot be guaranteed.
559 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.
561 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.
563 You can read the complete module contribution guide on the Puppet Labs wiki.