Add mirror option for git cloning
[puppet_vcsrepo.git] / README.markdown
1 #vcsrepo
2
3 ####Table of Contents
4
5 1. [Overview](#overview)
6 2. [Module Description - What the module does and why it is useful](#module-description)
7 3. [Setup - The basics of getting started with vcsrepo](#setup)
8     * [Setup requirements](#setup-requirements)
9     * [Beginning with vcsrepo](#beginning-with-vcsrepo)
10 4. [Usage - Configuration options and additional functionality](#usage)
11     * [Git](#git)
12     * [Bazaar](#bazaar)
13     * [CVS](#cvs)
14     * [Mercurial](#mercurial)
15     * [Perforce](#perforce)
16     * [Subversion](#subversion)  
17 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
18     * [Type: vcsrepo](#type-vcsrepo)
19         * [Providers](#providers)
20         * [Features](#features)
21         * [Parameters](#parameters)
22 5. [Limitations - OS compatibility, etc.](#limitations)
23 6. [Development - Guide for contributing to the module](#development)
24
25 ##Overview
26
27 The vcsrepo module lets you use Puppet to easily deploy content from your version control system (VCS).
28
29 ##Module Description
30
31 The vcsrepo module provides a single type with providers to support the following version control systems:
32
33 * [Git](#git)
34 * [Bazaar](#bazaar)
35 * [CVS](#cvs)
36 * [Mercurial](#mercurial)
37 * [Perforce](#perforce)
38 * [Subversion](#subversion)
39
40 **Note:** `git` is the only vcs provider officially [supported by Puppet Labs](https://forge.puppetlabs.com/supported).
41
42 ##Setup
43
44 ###Setup Requirements
45
46 The `vcsrepo` module does not install any VCS software for you. You must install a VCS before you can use this module.
47
48 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.
49
50 ###Beginning with vcsrepo
51
52 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).
53
54 ~~~
55 vcsrepo { '/path/to/repo':
56   ensure   => present,
57   provider => git,
58 }
59 ~~~
60
61 ##Usage
62
63 **Note:** `git` is the only vcsrepo provider officially [supported by Puppet Labs](https://forge.puppetlabs.com/supported).
64
65 ###Git
66
67 ####Create a blank repository
68
69 To create a blank repository, suitable for use as a central repository, define `vcsrepo` without `source` or `revision`:
70
71 ~~~
72 vcsrepo { '/path/to/repo':
73   ensure   => present,
74   provider => git,
75 }
76 ~~~
77
78 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':
79
80 ~~~
81 vcsrepo { '/path/to/repo':
82   ensure   => bare,
83   provider => git,
84 }
85 ~~~
86
87 ####Clone/pull a repository
88
89 ~~~
90 vcsrepo { '/path/to/repo':
91   ensure   => present,
92   provider => git,
93   source   => 'git://example.com/repo.git',
94 }
95 ~~~
96
97 If you want to clone your repository as bare or mirror, you can set `ensure` to 'bare' or 'mirror':
98
99 ~~~
100 vcsrepo { '/path/to/repo':
101   ensure   => mirror,
102   provider => git,
103   source   => 'git://example.com/repo.git',
104 }
105 ~~~
106
107 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.
108
109 Branch name:
110
111 ~~~
112 vcsrepo { '/path/to/repo':
113   ensure   => present,
114   provider => git,
115   source   => 'git://example.com/repo.git',
116   revision => 'development',
117 }
118 ~~~
119
120 SHA:
121
122 ~~~
123 vcsrepo { '/path/to/repo':
124   ensure   => present,
125   provider => git,
126   source   => 'git://example.com/repo.git',
127   revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31',
128 }
129 ~~~
130
131 Tag:
132
133 ~~~
134 vcsrepo { '/path/to/repo':
135   ensure   => present,
136   provider => git,
137   source   => 'git://example.com/repo.git',
138   revision => '1.1.2rc1',
139 }
140 ~~~
141
142 To check out a branch as a specific user, supply the `user` parameter:
143
144 ~~~
145 vcsrepo { '/path/to/repo':
146   ensure   => present,
147   provider => git,
148   source   => 'git://example.com/repo.git',
149   revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31',
150   user     => 'someUser',
151 }
152 ~~~
153
154 To keep the repository at the latest revision, set `ensure` to 'latest'.
155
156 **WARNING:** this overwrites any local changes to the repository:
157
158 ~~~
159 vcsrepo { '/path/to/repo':
160   ensure   => latest,
161   provider => git,
162   source   => 'git://example.com/repo.git',
163   revision => 'master',
164 }
165 ~~~
166
167 To clone the repository but skip initializing submodules, set `submodules` to 'false':
168
169 ~~~
170 vcsrepo { '/path/to/repo':
171   ensure     => latest,
172   provider   => git,
173   source     => 'git://example.com/repo.git',
174   submodules => false,
175 }
176 ~~~
177
178 ####Use multiple remotes with a repository
179 In place of a single string, you can set `source` to a hash of one or more name => URL pairs:
180
181 ~~~
182 vcsrepo { '/path/to/repo':
183   ensure   => present,
184   provider => git,
185   remote   => 'origin'
186   source   => {
187     'origin'       => 'https://github.com/puppetlabs/puppetlabs-vcsrepo.git', 
188     'other_remote' => 'https://github.com/other_user/puppetlabs-vcsrepo.git'
189   },
190 }
191 ~~~
192
193 **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.
194
195 ####Connect via SSH
196
197 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.
198
199 To use SSH keys associated with a user, specify the username in the `user` parameter:
200
201 ~~~
202 vcsrepo { '/path/to/repo':
203   ensure     => latest,
204   provider   => git,
205   source     => 'git://username@example.com/repo.git',
206   user       => 'toto', #uses toto's $HOME/.ssh setup
207   require    => File['/home/toto/.ssh/id_rsa'],
208 }
209 ~~~
210
211 ###Bazaar
212
213 ####Create a blank repository
214
215 To create a blank repository, suitable for use as a central repository, define `vcsrepo` without `source` or `revision`:
216
217 ~~~
218 vcsrepo { '/path/to/repo':
219   ensure   => present,
220   provider => bzr,
221 }
222 ~~~
223
224 ####Branch from an existing repository
225
226 ~~~
227 vcsrepo { '/path/to/repo':
228   ensure   => present,
229   provider => bzr,
230   source   => '/some/path',
231 }
232 ~~~
233
234 To branch from a specific revision, set `revision` to a valid [Bazaar revision spec](http://wiki.bazaar.canonical.com/BzrRevisionSpec):
235
236 ~~~
237 vcsrepo { '/path/to/repo':
238   ensure   => present,
239   provider => bzr,
240   source   => '/some/path',
241   revision => 'menesis@pov.lt-20100309191856-4wmfqzc803fj300x',
242 }
243 ~~~
244
245 ####Connect via SSH
246
247 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:
248
249 ~~~
250 vcsrepo { '/path/to/repo':
251   ensure     => latest,
252   provider   => bzr,
253   source     => 'bzr+ssh://bzr.example.com/some/path',
254   user       => 'toto', #uses toto's $HOME/.ssh setup
255   require    => File['/home/toto/.ssh/id_rsa'],
256 }
257 ~~~
258
259 ###CVS
260
261 ####Create a blank repository
262
263 To create a blank repository, suitable for use as a central repository, define `vcsrepo` without `source` or `revision`:
264
265 ~~~
266 vcsrepo { '/path/to/repo':
267   ensure   => present,
268   provider => cvs,
269 }
270 ~~~
271
272 ####Checkout/update from a repository
273
274 ~~~
275 vcsrepo { '/path/to/workspace':
276   ensure   => present,
277   provider => cvs,
278   source   => ':pserver:anonymous@example.com:/sources/myproj',
279 }
280 ~~~
281
282 To get a specific module on the current mainline, supply the `module` parameter:
283
284 ~~~
285 vcsrepo {'/vagrant/lockss-daemon-source':
286   ensure   => present,
287   provider => cvs,
288   source   => ':pserver:anonymous@lockss.cvs.sourceforge.net:/cvsroot/lockss',
289   module   => 'lockss-daemon',
290 }
291 ~~~
292
293 To set the GZIP compression levels for your repository history, use the `compression` parameter:
294
295 ~~~
296 vcsrepo { '/path/to/workspace':
297   ensure      => present,
298   provider    => cvs,
299   compression => 3,
300   source      => ':pserver:anonymous@example.com:/sources/myproj',
301 }
302 ~~~
303
304 To get a specific revision, set `revision` to the revision number.
305
306 ~~~
307 vcsrepo { '/path/to/workspace':
308   ensure      => present,
309   provider    => cvs,
310   compression => 3,
311   source      => ':pserver:anonymous@example.com:/sources/myproj',
312   revision    => '1.2',
313 }
314 ~~~
315
316 You can also set `revision` to a tag:
317
318 ~~~
319 vcsrepo { '/path/to/workspace':
320   ensure      => present,
321   provider    => cvs,
322   compression => 3,
323   source      => ':pserver:anonymous@example.com:/sources/myproj',
324   revision    => 'SOMETAG',
325 }
326 ~~~
327
328 ####Connect via SSH
329
330 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:
331
332 ~~~
333 vcsrepo { '/path/to/repo':
334   ensure     => latest,
335   provider   => cvs,
336   source     => ':pserver:anonymous@example.com:/sources/myproj',
337   user       => 'toto', #uses toto's $HOME/.ssh setup
338   require    => File['/home/toto/.ssh/id_rsa'],
339 }
340 ~~~
341
342 ###Mercurial
343
344 ####Create a blank repository
345
346 To create a blank repository, suitable for use as a central repository, define `vcsrepo` without `source` or `revision`:
347
348 ~~~
349 vcsrepo { '/path/to/repo':
350   ensure   => present,
351   provider => hg,
352 }
353 ~~~
354
355 ####Clone/pull & update a repository
356
357 To get the default branch tip:
358
359 ~~~
360 vcsrepo { '/path/to/repo':
361   ensure   => present,
362   provider => hg,
363   source   => 'http://hg.example.com/myrepo',
364 }
365 ~~~
366
367 For a specific changeset, use `revision`:
368
369 ~~~
370 vcsrepo { '/path/to/repo':
371   ensure   => present,
372   provider => hg,
373   source   => 'http://hg.example.com/myrepo',
374   revision => '21ea4598c962',
375 }
376 ~~~
377
378 You can also set `revision` to a tag:
379
380 ~~~
381 vcsrepo { '/path/to/repo':
382   ensure   => present,
383   provider => hg,
384   source   => 'http://hg.example.com/myrepo',
385   revision => '1.1.2',
386 }
387 ~~~
388
389 To check out as a specific user:
390
391 ~~~
392 vcsrepo { '/path/to/repo':
393   ensure   => present,
394   provider => hg,
395   source   => 'http://hg.example.com/myrepo',
396   user     => 'user',
397 }
398 ~~~
399
400 To specify an SSH identity key:
401
402 ~~~
403 vcsrepo { '/path/to/repo':
404   ensure   => present,
405   provider => hg,
406   source   => 'ssh://hg@hg.example.com/myrepo',
407   identity => '/home/user/.ssh/id_dsa1,
408 }
409 ~~~
410
411 To specify a username and password for HTTP Basic authentication:
412
413 ~~~
414 vcsrepo { '/path/to/repo':
415   ensure   => latest,
416   provider => hg,
417   source   => 'http://hg.example.com/myrepo',
418   basic_auth_username => 'hgusername',
419   basic_auth_password => 'hgpassword',
420 }
421 ~~~
422
423 ####Connect via SSH 
424
425 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:
426
427 ~~~
428 vcsrepo { '/path/to/repo':
429   ensure     => latest,
430   provider   => hg,
431   source     => 'ssh://hg.example.com//path/to/myrepo',
432   user       => 'toto', #uses toto's $HOME/.ssh setup
433   require    => File['/home/toto/.ssh/id_rsa'],
434 }
435 ~~~
436
437 ###Perforce
438
439 ####Create an empty workspace
440
441 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: 
442
443 ~~~
444 vcsrepo { '/path/to/repo':
445   ensure     => present,
446   provider   => p4,
447   p4config   => '/root/.p4config'
448 }
449 ~~~
450
451 **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`):
452
453 ####Create/update and sync a Perforce workspace
454
455 To sync a depot path to head, set `ensure` to 'latest':
456
457 ~~~
458 vcsrepo { '/path/to/repo':
459   ensure   => latest,
460   provider => p4,
461   source   => '//depot/branch/...'
462 }
463 ~~~
464
465 To sync to a specific changelist, specify its revision number with the `revision` parameter:
466
467 ~~~
468 vcsrepo { '/path/to/repo':
469   ensure   => present,
470   provider => p4,
471   source   => '//depot/branch/...',
472   revision => '2341'
473 }
474 ~~~
475
476 You can also set `revision` to a label:
477
478 ~~~
479 vcsrepo { '/path/to/repo':
480   ensure   => present,
481   provider => p4,
482   source   => '//depot/branch/...',
483   revision => 'my_label'
484 }
485 ~~~
486
487 ###Subversion
488
489 ####Create a blank repository
490
491 ~~~
492 vcsrepo { '/path/to/repo':
493   ensure   => present,
494   provider => svn,
495 }
496 ~~~
497
498 ####Check out from an existing repository
499
500 Provide a `source` pointing to the branch or tag you want to check out:
501
502 ~~~
503 vcsrepo { '/path/to/repo':
504   ensure   => present,
505   provider => svn,
506   source   => 'svn://svnrepo/hello/branches/foo',
507 }
508 ~~~
509
510 You can also designate a specific revision:
511
512 ~~~
513 vcsrepo { '/path/to/repo':
514   ensure   => present,
515   provider => svn,
516   source   => 'svn://svnrepo/hello/branches/foo',
517   revision => '1234',
518 }
519 ~~~
520
521 ####Use a specific Subversion configuration directory 
522
523 Use the `configuration` parameter to designate the directory that contains your Subversion configuration files (typically, '/path/to/.subversion'):
524
525 ~~~
526 vcsrepo { '/path/to/repo':
527   ensure        => present,
528   provider      => svn,
529   source        => 'svn://svnrepo/hello/branches/foo',
530   configuration => '/path/to/.subversion',
531 }
532 ~~~
533
534 ####Connect via SSH 
535
536 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:
537
538 ~~~
539 vcsrepo { '/path/to/repo':
540   ensure     => latest,
541   provider   => svn,
542   source     => 'svn+ssh://svnrepo/hello/branches/foo',
543   user       => 'toto', #uses toto's $HOME/.ssh setup
544   require    => File['/home/toto/.ssh/id_rsa'],
545 }
546 ~~~
547
548 ##Reference
549
550 ###Type: vcsrepo
551
552 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.
553
554 ####Providers
555
556 **Note:** Not all features are available with all providers.
557
558 #####`git` - Supports the Git VCS.
559
560 Features: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `submodules`, `user`
561
562 Parameters: `depth`, `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `remote`, `revision`, `source`, `user`
563
564 #####`bzr` - Supports the Bazaar VCS.
565
566 Features: `reference_tracking`
567
568 Parameters: `ensure`, `excludes`, `force`, `group`, `owner`, `path`, `provider`, `revision`, `source`
569
570 #####`cvs` - Supports the CVS VCS.
571
572 Features: `cvs_rsh`, `gzip_compression`, `modules`, `reference_tracking`, `user`
573
574 Parameters: `compression`, `cvs_rsh`, `ensure`, `excludes`, `force`, `group`, `module`, `owner`, `path`, `provider`
575
576 #####`hg` - Supports the Mercurial VCS.
577
578 Features: `reference_tracking`, `ssh_identity`, `user`
579
580 Parameters: `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `revision`, `source`, `user`
581
582 #####`p4` - Supports the Perforce VCS.
583
584 Features: `p4config`, `reference_tracking`
585
586 Parameters: `ensure`, `excludes`, `force`, `group`, `owner`, `p4config`, `path`, `provider`, `revision`, `source`
587
588 #####`svn` - Supports the Subversion VCS.
589
590 Features: `basic_auth`, `configuration`, `conflict`, `depth`, `filesystem_types`, `reference_tracking`
591
592 Parameters: `basic_auth_password`, `basic_auth_username`, `configuration`, `conflict`, `ensure`, `excludes`, `force`, `fstype`, `group`, `owner`, `path`, `provider`, `revision`, `source`, `trust_server_cert`
593
594 ####Features
595
596 **Note:** Not all features are available with all providers.
597
598 * `bare_repositories` - Differentiates between bare repositories and those with working copies. (Available with `git`.)
599 * `basic_auth` -  Supports HTTP Basic authentication. (Available with `svn`.)
600 * `conflict` - Lets you decide how to resolve any conflicts between the source repository and your working copy. (Available with `svn`.)
601 * `configuration` - Lets you specify the location of your configuration files. (Available with `svn`.)
602 * `cvs_rsh` - Understands the `CVS_RSH` environment variable. (Available with `cvs`.)
603 * `depth` - Supports shallow clones in `git` or sets scope limit in `svn`. (Available with `git` and `svn`.)
604 * `filesystem_types` - Supports multiple types of filesystem. (Available with `svn`.)
605 * `gzip_compression` - Supports explicit GZip compression levels. (Available with `cvs`.)
606 * `modules` - Lets you choose a specific repository module. (Available with `cvs`.)
607 * `multiple_remotes` - Tracks multiple remote repositories. (Available with `git`.)
608 * `reference_tracking` - Lets you track revision references that can change over time (e.g., some VCS tags and branch names). (Available with all providers)
609 * `ssh_identity` - Lets you specify an SSH identity file. (Available with `git` and `hg`.)
610 * `user` - Can run as a different user. (Available with `git`, `hg` and `cvs`.)
611 * `p4config` - Supports setting the `P4CONFIG` environment. (Available with `p4`.)
612 * `submodules` - Supports repository submodules which can be optionally initialized. (Available with `git`.)
613
614 ####Parameters
615
616 All parameters are optional, except where specified otherwise.
617
618 ##### `basic_auth_password`
619
620 Specifies the password for HTTP Basic authentication. (Requires the `basic_auth` feature.) Valid options: a string. Default: none. 
621
622 ##### `basic_auth_username`
623
624 Specifies the username for HTTP Basic authentication. (Requires the `basic_auth` feature.) Valid options: a string. Default: none. 
625
626 ##### `compression`
627
628 Sets the GZIP compression level for the repository history. (Requires the `gzip_compression` feature.) Valid options: an integer between 0 and 6. Default: none. 
629
630 ##### `configuration`
631
632 Sets the configuration directory to use. (Requires the `configuration` feature.) Valid options: a string containing an absolute path. Default: none. 
633
634 ##### `conflict`
635
636 Tells Subversion how to resolve any conflicts between the source repository and your working copy. (Requires the `conflict` feature.) Valid options: 'base', 'mine-full', 'theirs-full', and 'working'. Default: none. 
637
638 ##### `cvs_rsh`
639
640 Provides a value for the `CVS_RSH` environment variable. (Requires the `cvs_rsh` feature.) Valid options: a string. Default: none. 
641
642 ##### `depth`
643
644 In `git` sets the number of commits to include when creating a shallow clone. (Requires the `depth` feature.) Valid options: an integer. Default: none. 
645
646 In `svn` instructs Subversion to limit the scope of an operation to a particular tree depth. (Requires the `depth` feature.) Valid options: 'empty', 'files', 'immediates', 'infinity'. Default: none. 
647
648 ##### `ensure`
649
650 Specifies whether the repository should exist. Valid options: 'present', 'bare', 'absent', and 'latest'. Default: 'present'. 
651
652 ##### `excludes`
653
654 Lists any files the repository shouldn't track (similar to .gitignore). Valid options: a string (separate multiple values with the newline character). Default: none. 
655
656 ##### `force`
657
658 Specifies whether to delete any existing files in the repository path if creating a new repository. **Use with care.** Valid options: 'true' and 'false'. Default: 'false'. 
659
660 ##### `fstype`
661
662 Sets the filesystem type. (Requires the `filesystem_types` feature.) Valid options: 'fsfs' or 'bdb'. Default: none. 
663
664 ##### `group`
665
666 Specifies a group to own the repository files. Valid options: a string containing a group name or GID. Default: none. 
667
668 ##### `identity`
669
670 Specifies an identity file to use for SSH authentication. (Requires the `ssh_identity` feature.) Valid options: a string containing an absolute path. Default: none. 
671
672 ##### `module`
673
674 Specifies the repository module to manage. (Requires the `modules` feature.) Valid options: a string containing the name of a CVS module. Default: none. 
675
676 ##### `owner`
677
678 Specifies a user to own the repository files. Valid options: a string containing a username or UID. Default: none. 
679
680 ##### `p4config`
681
682 Specifies a config file that contains settings for connecting to the Perforce service. (Requires the `p4config` feature.) Valid options: a string containing the absolute path to a valid [Perforce config file](http://www.perforce.com/perforce/doc.current/manuals/p4guide/chapter.configuration.html#configuration.settings.configfiles). Default: none. 
683
684 ##### `path`
685
686 Specifies a location for the managed repository. Valid options: a string containing an absolute path. Default: the title of your declared resource. 
687
688 ##### `provider`
689
690 *Required.* Specifies the backend to use for this vcsrepo resource. Valid options: 'bzr', 'cvs', 'git', 'hg', 'p4', and 'svn'. 
691
692 ##### `remote`
693
694 Specifies the remote repository to track. (Requires the `multiple_remotes` feature.) Valid options: a string containing one of the remote names specified in `source`. Default: 'origin'. 
695
696 ##### `revision`
697
698 Sets the revision of the repository. Valid options vary by provider:
699
700 * `git` - a string containing a Git branch name, or a commit SHA or tag
701 * `bzr` - a string containing a Bazaar [revision spec](http://wiki.bazaar.canonical.com/BzrRevisionSpec)
702 * `cvs` - a string containing a CVS [tag or revision number](http://www.thathost.com/wincvs-howto/cvsdoc/cvs_4.html)
703 * `hg` - a string containing a Mercurial [changeset ID](http://mercurial.selenic.com/wiki/ChangeSetID) or [tag](http://mercurial.selenic.com/wiki/Tag)
704 * `p4` - a string containing a Perforce [change number, label name, client name, or date spec](http://www.perforce.com/perforce/r12.1/manuals/cmdref/o.fspecs.html)
705 * `svn` - a string containing a Subversion [revision number](http://svnbook.red-bean.com/en/1.7/svn.basic.in-action.html#svn.basic.in-action.revs), [revision keyword, or revision date](http://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html)
706
707 Default: none. 
708
709 ##### `source`
710
711 Specifies a source repository to serve as the upstream for your managed repository. Default: none. Valid options vary by provider:
712
713 * `git` - a string containing a [Git repository URL](https://www.kernel.org/pub/software/scm/git/docs/git-clone.html#_git_urls_a_id_urls_a) or a hash of name => URL mappings. See also [`remote`](#remote).
714 * `bzr` - a string containing a Bazaar branch location
715 * `cvs` - a string containing a CVS root
716 * `hg` - a string containing the local path or URL of a Mercurial repository
717 * `p4` - a string containing a Perforce depot path
718 * `svn` - a string containing a Subversion repository URL
719
720 Default: none. 
721
722 ##### `submodules`
723
724 Specifies whether to initialize and update each submodule in the repository. (Requires the `submodules` feature.) Valid options: 'true' and 'false'. Default: 'true'. 
725
726 ##### `trust_server_cert`
727
728 Instructs Subversion to accept SSL server certificates issued by unknown certificate authorities. Valid options: 'true' and 'false'. Default: 'false'. 
729
730 ##### `user`
731
732 Specifies the user to run as for repository operations. (Requires the `user` feature.) Valid options: a string containing a username or UID. Default: none.
733
734 ##Limitations
735
736 Git is the only VCS provider officially [supported](https://forge.puppetlabs.com/supported) by Puppet Labs.
737
738 This module has been tested with Puppet 2.7 and higher.
739
740 The module has been tested on:
741
742 * CentOS 5/6/7
743 * Debian 6/7
744 * Oracle 5/6/7
745 * Red Hat Enterprise Linux 5/6/7
746 * Scientific Linux 5/6/7
747 * SLES 10/11/12
748 * Ubuntu 10.04/12.04/14.04
749
750 Testing on other platforms has been light and cannot be guaranteed.
751
752 ##Development
753
754 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.
755
756 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.
757
758 You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)