Merge branch '1.0.x'
authorHunter Haugen <hunter@puppetlabs.com>
Fri, 27 Jun 2014 21:40:33 +0000 (14:40 -0700)
committerHunter Haugen <hunter@puppetlabs.com>
Fri, 27 Jun 2014 21:40:33 +0000 (14:40 -0700)
1  2 
README.markdown

diff --combined README.markdown
@@@ -53,12 -53,104 +53,104 @@@ To get started with the vcsrepo module
  
  The vcsrepo module works with the following VCSs:
  
+ * [Git (git)](#git)*
  * [Bazaar (bzr)](#bazaar)
  * [CVS (cvs)](#cvs)
- * [Git (git)](#git)
  * [Mercurial (hg)](#mercurial)
  * [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
@@@ -159,95 -251,6 +251,6 @@@ When your source uses SSH, you can mana
  
  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
@@@ -306,16 -309,6 +309,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.
@@@ -384,10 -377,10 +387,10 @@@ The vcsrepo module is slightly unusual 
  
  **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`.)
  
  
  ####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`
  
  
  **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`
  
          
  ##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:
@@@ -480,4 -475,4 +485,4 @@@ Puppet Labs modules on the Puppet Forg
  
  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.
 +You can read the complete module contribution guide on the Puppet Labs wiki.