Add examples to git, subversion, and systemd_unit

Signed-off-by: Tim Smith <tsmith@chef.io>

4 files changed, 137 insertions, 2 deletions

diff --git a/lib/chef/resource/scm/_scm.rb b/lib/chef/resource/scm/_scm.rb
index c939246ba1..bb134424d5 100644
--- a/lib/chef/resource/scm/_scm.rb
+++ b/lib/chef/resource/scm/_scm.rb
@@ -33,7 +33,8 @@ property :revision, String,
   default: "HEAD"
 
 property :user, [String, Integer],
-  description: "The system user that will own the checked-out code."
+  description: "The system user that will own the checked-out code.",
+  default_description: "`HOME` environment variable of the current user"
 
 property :group, [String, Integer],
   description: "The system group that will own the checked-out code."
diff --git a/lib/chef/resource/scm/git.rb b/lib/chef/resource/scm/git.rb
index b8c8f06347..6d96d556eb 100644
--- a/lib/chef/resource/scm/git.rb
+++ b/lib/chef/resource/scm/git.rb
@@ -28,6 +28,87 @@ class Chef
       provides :git
 
       description "Use the **git** resource to manage source control resources that exist in a git repository. git version 1.6.5 (or higher) is required to use all of the functionality in the git resource."
+      examples <<~DOC
+      **Use the git mirror**
+
+      ```ruby
+      git '/opt/mysources/couch' do
+        repository 'git://git.apache.org/couchdb.git'
+        revision 'master'
+        action :sync
+      end
+      ```
+
+      **Use different branches**
+
+      To use different branches, depending on the environment of the node:
+
+      ```ruby
+      branch_name = if node.chef_environment == 'QA'
+                      'staging'
+                    else
+                      'master'
+                    end
+
+      git '/home/user/deployment' do
+         repository 'git@github.com:gitsite/deployment.git'
+         revision branch_name
+         action :sync
+         user 'user'
+         group 'test'
+      end
+      ```
+
+      Where the branch_name variable is set to staging or master, depending on the environment of the node. Once this is determined, the branch_name variable is used to set the revision for the repository. If the git status command is used after running the example above, it will return the branch name as deploy, as this is the default value. Run Chef Infra Client in debug mode to verify that the correct branches are being checked out:
+
+      ```
+      sudo chef-client -l debug
+      ```
+
+      **Install an application from git using bash**
+
+      The following example shows how Bash can be used to install a plug-in for rbenv named ruby-build, which is located in git version source control. First, the application is synchronized, and then Bash changes its working directory to the location in which ruby-build is located, and then runs a command.
+
+      ```ruby
+      git "#{Chef::Config[:file_cache_path]}/ruby-build" do
+        repository 'git://github.com/sstephenson/ruby-build.git'
+        revision 'master'
+        action :sync
+      end
+
+      bash 'install_ruby_build' do
+        cwd "#{Chef::Config[:file_cache_path]}/ruby-build"
+        user 'rbenv'
+        group 'rbenv'
+        code <<-EOH
+          ./install.sh
+          EOH
+        environment 'PREFIX' => '/usr/local'
+      end
+      ```
+
+      **Notify a resource post-checkout**
+
+      ```ruby
+      git "#{Chef::Config[:file_cache_path]}/libvpx" do
+        repository node[:libvpx][:git_repository]
+        revision node[:libvpx][:git_revision]
+        action :sync
+        notifies :run, 'bash[compile_libvpx]', :immediately
+      end
+      ```
+
+      **Pass in environment variables**
+
+      ```ruby
+      git '/opt/mysources/couch' do
+        repository 'git://git.apache.org/couchdb.git'
+        revision 'master'
+        environment 'VAR' => 'whatever'
+        action :sync
+      end
+      ```
+      DOC
 
       property :additional_remotes, Hash,
         description: "A Hash of additional remotes that are added to the git repository configuration.",
@@ -41,7 +122,7 @@ class Chef
         default: false
 
       property :enable_checkout, [TrueClass, FalseClass],
-        description: "Check out a repo from master. Set to false when using the checkout_branch attribute to prevent the git resource from attempting to check out master from master.",
+        description: "Check out a repo from master. Set to `false` when using the `checkout_branch` attribute to prevent the git resource from attempting to check out `master` from `master`.",
         default: true
 
       property :remote, String,
diff --git a/lib/chef/resource/scm/subversion.rb b/lib/chef/resource/scm/subversion.rb
index f5637b04ad..8399225fdf 100644
--- a/lib/chef/resource/scm/subversion.rb
+++ b/lib/chef/resource/scm/subversion.rb
@@ -29,6 +29,18 @@ class Chef
       provides :subversion
 
       description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository."
+      examples <<~DOC
+      **Get the latest version of an application**
+
+      ```ruby
+      subversion 'CouchDB Edge' do
+        repository 'http://svn.apache.org/repos/asf/couchdb/trunk'
+        revision 'HEAD'
+        destination '/opt/mysources/couch'
+        action :sync
+      end
+      ```
+      DOC
 
       allowed_actions :force_export
 
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index fc9aa4d40f..f5bd0c5643 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -29,6 +29,47 @@ class Chef
 
       description "Use the **systemd_unit** resource to create, manage, and run [systemd units](https://www.freedesktop.org/software/systemd/man/systemd.html#Concepts)."
       introduced "12.11"
+      examples <<~DOC
+      **Create systemd service unit file from a Hash**
+
+      ```ruby
+      systemd_unit 'etcd.service' do
+        content({Unit: {
+                  Description: 'Etcd',
+                  Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'],
+                  After: 'network.target',
+                },
+                Service: {
+                  Type: 'notify',
+                  ExecStart: '/usr/local/etcd',
+                  Restart: 'always',
+                },
+                Install: {
+                  WantedBy: 'multi-user.target',
+                }})
+        action [:create, :enable]
+      end
+      ```
+
+      **Create systemd service unit file from a String**
+
+      ```ruby
+      systemd_unit 'sysstat-collect.timer' do
+        content <<-EOU.gsub(/^\s+/, '')
+        [Unit]
+        Description=Run system activity accounting tool every 10 minutes
+
+        [Timer]
+        OnCalendar=*:00/10
+
+        [Install]
+        WantedBy=sysstat.service
+        EOU
+
+        action [:create, :enable]
+      end
+      ```
+      DOC
 
       default_action :nothing
       allowed_actions :create, :delete,