diff options
Diffstat (limited to 'README.markdown')
| -rw-r--r-- | README.markdown | 209 |
1 files changed, 112 insertions, 97 deletions
diff --git a/README.markdown b/README.markdown index d977886..f83c7fd 100644 --- a/README.markdown +++ b/README.markdown @@ -54,13 +54,105 @@ To get started with the vcsrepo module, you must simply define the type `vcsrepo The vcsrepo module works with the following VCSs: +* [Git (git)](#git)* * [Bazaar (bzr)](#bazaar) * [CVS (cvs)](#cvs) -* [Git (git)](#git) * [Mercurial (hg)](#mercurial) * [Perforce (p4)](#perforce) * [Subversion (svn)](#subversion) +**Note:* Git is the only VCS provider officially [supported](https://forge.puppetlabs.com/supported) by Puppet Labs. + + +###Git + +#####To create a blank repository + +To create a blank repository suitable for use as a central repository, +define `vcsrepo` without `source` or `revision`. + + vcsrepo { "/path/to/repo": + ensure => present, + provider => git, + } + +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'. + + vcsrepo { "/path/to/repo": + ensure => bare, + provider => git, + } + +#####To clone/pull a repository + +To get the current HEAD on the master branch, + + vcsrepo { "/path/to/repo": + ensure => present, + provider => git, + source => "git://example.com/repo.git", + } + +To get a specific revision or branch (can be a commit SHA, tag, or branch name), + + **SHA** + + vcsrepo { "/path/to/repo": + ensure => present, + provider => git, + source => 'git://example.com/repo.git', + revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31', + } + +**Tag** + + vcsrepo { "/path/to/repo": + ensure => present, + provider => git, + source => 'git://example.com/repo.git', + revision => '1.1.2rc1', + } + +**Branch name** + + vcsrepo { "/path/to/repo": + ensure => present, + provider => git, + source => 'git://example.com/repo.git', + revision => 'development', + } + +To check out a branch as a specific user, + + vcsrepo { "/path/to/repo": + ensure => present, + provider => git, + source => 'git://example.com/repo.git', + revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31', + user => 'someUser', + } + +To keep the repository at the latest revision (**WARNING:** this will always overwrite local changes to the repository), + + vcsrepo { "/path/to/repo": + ensure => latest, + provider => git, + source => 'git://example.com/repo.git', + revision => 'master', + } + +#####Sources that use SSH + +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. + +For SSH keys associated with a user, enter the username in the `user` parameter. Doing so will use that user's keys. + + user => 'toto' # will use toto's $HOME/.ssh setup + +#####Further Examples + +For more examples using Git, see `examples/git/`. + ###Bazaar #####Create a blank repository @@ -161,95 +253,6 @@ When your source uses SSH, you can manage your SSH keys with Puppet using the [r For for more examples using CVS, see `examples/cvs/`. -###Git - -#####To create a blank repository - -To create a blank repository suitable for use as a central repository, -define `vcsrepo` without `source` or `revision`. - - vcsrepo { "/path/to/repo": - ensure => present, - provider => git, - } - -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'. - - vcsrepo { "/path/to/repo": - ensure => bare, - provider => git, - } - -#####To clone/pull a repository - -To get the current HEAD on the master branch, - - vcsrepo { "/path/to/repo": - ensure => present, - provider => git, - source => "git://example.com/repo.git", - } - -To get a specific revision or branch (can be a commit SHA, tag, or branch name), - - **SHA** - - vcsrepo { "/path/to/repo": - ensure => present, - provider => git, - source => 'git://example.com/repo.git', - revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31', - } - -**Tag** - - vcsrepo { "/path/to/repo": - ensure => present, - provider => git, - source => 'git://example.com/repo.git', - revision => '1.1.2rc1', - } - -**Branch name** - - vcsrepo { "/path/to/repo": - ensure => present, - provider => git, - source => 'git://example.com/repo.git', - revision => 'development', - } - -To check out a branch as a specific user, - - vcsrepo { "/path/to/repo": - ensure => present, - provider => git, - source => 'git://example.com/repo.git', - revision => '0c466b8a5a45f6cd7de82c08df2fb4ce1e920a31', - user => 'someUser', - } - -To keep the repository at the latest revision (**WARNING:** this will always overwrite local changes to the repository), - - vcsrepo { "/path/to/repo": - ensure => latest, - provider => git, - source => 'git://example.com/repo.git', - revision => 'master', - } - -#####Sources that use SSH - -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. - -For SSH keys associated with a user, enter the username in the `user` parameter. Doing so will use that user's keys. - - user => 'toto' # will use toto's $HOME/.ssh setup - -#####Further Examples - -For more examples using Git, see `examples/git/`. - ###Mercurial #####To create a blank repository @@ -308,6 +311,16 @@ To specify an SSH identity key, identity => "/home/user/.ssh/id_dsa, } +To specify a username and password for HTTP Basic authentication, + + vcsrepo { "/path/to/repo": + ensure => latest, + provider => hg, + source => 'http://hg.example.com/myrepo', + basic_auth_username => 'hgusername', + basic_auth_password => 'hgpassword', + } + #####Sources that use SSH 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. @@ -441,10 +454,10 @@ The vcsrepo module is slightly unusual in that it is simply a type and providers **Note**: Not all features are available with all providers. +* `git` - Supports the Git VCS. (Contains features: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `user`.) * `bar` - Supports the Bazaar VCS. (Contains features: `reference_tracking`.) * `cvs` - Supports the CVS VCS. (Contains features: `cvs_rsh`, `gzip_compression`, `modules`,`reference_tracking`.) * `dummy` - -* `git` - Supports the Git VCS. (Contains features: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `user`.) * `hg` - Supports the Mercurial VCS. (Contains features: `reference_tracking`, `ssh_identity`, `user`.) * `svn` - Supports the Subversion VCS. (Contains features: `basic_auth`, `configuration`, `filesystem_types`, `reference_tracking`.) @@ -490,6 +503,11 @@ The vcsrepo module is slightly unusual in that it is simply a type and providers ####Features and Parameters by Provider +#####`git` +**Features**: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `user` + +**Parameters**: `depth`, `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `remote`, `revision`, `source`, `user` + #####`bzr` **Features**: `reference_tracking` @@ -500,11 +518,6 @@ The vcsrepo module is slightly unusual in that it is simply a type and providers **Parameters**: `compression`, `cvs_rsh`, `ensure`, `excludes`, `force`, `group`, `module`, `owner`, `path`, `provider`, `revision`, `source`, `user` -#####`git` -**Features**: `bare_repositories`, `depth`, `multiple_remotes`, `reference_tracking`, `ssh_identity`, `user` - -**Parameters**: `depth`, `ensure`, `excludes`, `force`, `group`, `identity`, `owner`, `path`, `provider`, `remote`, `revision`, `source`, `user` - #####`hg` **Features**: `reference_tracking`, `ssh_identity`, `user` @@ -517,6 +530,8 @@ The vcsrepo module is slightly unusual in that it is simply a type and providers ##Limitations +Git is the only VCS provider officially [supported](https://forge.puppetlabs.com/supported) by Puppet Labs. + This module has been built on and tested against Puppet 2.7 and higher. The module has been tested on: @@ -537,4 +552,4 @@ Puppet Labs modules on the Puppet Forge are open projects, and community contrib 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. -You can read the complete module contribution guide on the Puppet Labs wiki.
\ No newline at end of file +You can read the complete module contribution guide on the Puppet Labs wiki. |