r10k 2.3.1 → 2.4.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (104) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +1 -0
  3. data/CHANGELOG.mkd +40 -13
  4. data/Gemfile +1 -2
  5. data/README.mkd +25 -0
  6. data/Rakefile +3 -0
  7. data/doc/dynamic-environments/configuration.mkd +91 -14
  8. data/doc/dynamic-environments/workflow-guide.mkd +3 -3
  9. data/doc/puppetfile.mkd +89 -40
  10. data/integration/Gemfile +2 -0
  11. data/integration/Rakefile +41 -0
  12. data/integration/tests/purging/content_not_purged_at_root.rb +89 -0
  13. data/integration/tests/purging/default_purging.rb +125 -0
  14. data/integration/tests/user_scenario/basic_workflow/negative/neg_bad_git_module_ref.rb +1 -1
  15. data/lib/r10k.rb +8 -1
  16. data/lib/r10k/action/deploy/deploy_helpers.rb +3 -3
  17. data/lib/r10k/action/deploy/environment.rb +35 -14
  18. data/lib/r10k/action/deploy/module.rb +4 -4
  19. data/lib/r10k/action/puppetfile/check.rb +1 -1
  20. data/lib/r10k/action/puppetfile/install.rb +1 -1
  21. data/lib/r10k/action/runner.rb +3 -3
  22. data/lib/r10k/deployment.rb +8 -4
  23. data/lib/r10k/deployment/config.rb +1 -1
  24. data/lib/r10k/environment/base.rb +32 -3
  25. data/lib/r10k/environment/git.rb +19 -6
  26. data/lib/r10k/feature.rb +6 -6
  27. data/lib/r10k/forge/module_release.rb +4 -6
  28. data/lib/r10k/git.rb +7 -7
  29. data/lib/r10k/git/alternates.rb +1 -1
  30. data/lib/r10k/git/cache.rb +2 -2
  31. data/lib/r10k/git/rugged/bare_repository.rb +29 -9
  32. data/lib/r10k/git/rugged/credentials.rb +8 -8
  33. data/lib/r10k/git/rugged/thin_repository.rb +17 -3
  34. data/lib/r10k/git/rugged/working_repository.rb +12 -5
  35. data/lib/r10k/git/shellgit/thin_repository.rb +5 -1
  36. data/lib/r10k/git/shellgit/working_repository.rb +16 -2
  37. data/lib/r10k/git/stateful_repository.rb +33 -23
  38. data/lib/r10k/initializers.rb +1 -1
  39. data/lib/r10k/keyed_factory.rb +2 -2
  40. data/lib/r10k/logging.rb +1 -1
  41. data/lib/r10k/module.rb +4 -3
  42. data/lib/r10k/module/base.rb +3 -2
  43. data/lib/r10k/module/forge.rb +9 -4
  44. data/lib/r10k/module/git.rb +39 -22
  45. data/lib/r10k/module/local.rb +1 -1
  46. data/lib/r10k/module/metadata_file.rb +1 -1
  47. data/lib/r10k/module/svn.rb +3 -1
  48. data/lib/r10k/puppetfile.rb +72 -11
  49. data/lib/r10k/settings.rb +20 -0
  50. data/lib/r10k/settings/collection.rb +2 -2
  51. data/lib/r10k/settings/container.rb +1 -1
  52. data/lib/r10k/settings/enum_definition.rb +11 -3
  53. data/lib/r10k/settings/helpers.rb +2 -2
  54. data/lib/r10k/settings/list.rb +1 -1
  55. data/lib/r10k/settings/loader.rb +6 -6
  56. data/lib/r10k/settings/uri_definition.rb +1 -1
  57. data/lib/r10k/source/base.rb +2 -2
  58. data/lib/r10k/source/git.rb +4 -4
  59. data/lib/r10k/svn/working_dir.rb +1 -1
  60. data/lib/r10k/util/basedir.rb +9 -9
  61. data/lib/r10k/util/license.rb +3 -3
  62. data/lib/r10k/util/purgeable.rb +50 -24
  63. data/lib/r10k/util/setopts.rb +1 -1
  64. data/lib/r10k/util/subprocess.rb +3 -3
  65. data/lib/r10k/util/symbolize_keys.rb +1 -1
  66. data/lib/r10k/version.rb +1 -1
  67. data/locales/config.yaml +21 -0
  68. data/r10k.gemspec +3 -0
  69. data/spec/fixtures/unit/puppetfile/valid-forge-with-version/Puppetfile +1 -0
  70. data/spec/fixtures/unit/puppetfile/valid-forge-without-version/Puppetfile +1 -0
  71. data/spec/fixtures/unit/util/purgeable/managed_one/expected_1 +0 -0
  72. data/spec/fixtures/unit/util/purgeable/managed_one/managed_subdir_1/subdir_expected_1 +0 -0
  73. data/spec/fixtures/unit/util/purgeable/managed_one/managed_subdir_1/subdir_unmanaged_1 +0 -0
  74. data/spec/fixtures/unit/util/purgeable/managed_one/unmanaged_1 +0 -0
  75. data/spec/fixtures/unit/util/purgeable/managed_two/expected_2 +0 -0
  76. data/spec/fixtures/unit/util/purgeable/managed_two/unmanaged_2 +0 -0
  77. data/spec/integration/git/stateful_repository_spec.rb +39 -21
  78. data/spec/r10k-mocks/mock_config.rb +4 -0
  79. data/spec/spec_helper.rb +3 -0
  80. data/spec/unit/action/deploy/environment_spec.rb +71 -13
  81. data/spec/unit/environment/base_spec.rb +71 -0
  82. data/spec/unit/forge/module_release_spec.rb +7 -10
  83. data/spec/unit/git/stateful_repository_spec.rb +6 -6
  84. data/spec/unit/module/git_spec.rb +156 -5
  85. data/spec/unit/module_spec.rb +3 -3
  86. data/spec/unit/puppetfile_spec.rb +115 -0
  87. data/spec/unit/util/purgeable_spec.rb +230 -0
  88. metadata +45 -18
  89. data/integration/test_run_scripts/README.mkd +0 -5
  90. data/integration/test_run_scripts/all_tests-rugged-pe-centos6.sh +0 -20
  91. data/integration/test_run_scripts/all_tests-rugged-pe-rhel7.sh +0 -20
  92. data/integration/test_run_scripts/all_tests-rugged-pe-sles11.sh +0 -20
  93. data/integration/test_run_scripts/all_tests-rugged-pe-ubuntu1204.sh +0 -20
  94. data/integration/test_run_scripts/all_tests-rugged-pe-ubuntu1404.sh +0 -20
  95. data/integration/test_run_scripts/all_tests-shellgit-pe-centos6.sh +0 -20
  96. data/integration/test_run_scripts/all_tests-shellgit-pe-rhel7.sh +0 -20
  97. data/integration/test_run_scripts/all_tests-shellgit-pe-sles11.sh +0 -20
  98. data/integration/test_run_scripts/all_tests-shellgit-pe-ubuntu1204.sh +0 -20
  99. data/integration/test_run_scripts/all_tests-shellgit-pe-ubuntu1404.sh +0 -20
  100. data/integration/test_run_scripts/basic_functionality/all_tests-pe-centos6.sh +0 -20
  101. data/integration/test_run_scripts/command_line/all_tests-pe-centos6.sh +0 -20
  102. data/integration/test_run_scripts/git_source/all_tests-pe-centos6.sh +0 -20
  103. data/integration/test_run_scripts/user_scenario/basic_workflow/all_tests-pe-centos6.sh +0 -20
  104. data/integration/test_run_scripts/user_scenario/complex_workflow/all_tests-pe-centos6.sh +0 -20
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: e63992636be8dd543768f160bad72b447b3fd892
4
- data.tar.gz: 8929577087203a2d4a72a63b0ff6d5da96ff1312
3
+ metadata.gz: 6a09bf6960068b3be8375f1f66009b753ef64644
4
+ data.tar.gz: b9ed03e076ea4e74cbc77e25d913dfc9765f7877
5
5
  SHA512:
6
- metadata.gz: 32f6becccbae5df50626fd9133cb6f210a2d95fffce5ad69a5d534c19eceb59bee6b936f4783f4be0c3451adf3613557a4eca608255f5bff61e2c55f34282817
7
- data.tar.gz: 67885326574423b9d78386e4f3045f87ba922efcf284bd2959d49a4c89ae01ba3d884055fdcbd0b121c14f1f387d2b53b49899c7ff7a609ec8206b5a47a64de7
6
+ metadata.gz: 88988343617f2f811b66dd58b4580d3e05c8167545635d6ba78ccfbc965d70a64a736485f75380e2f8e0bb0d1f63fcff5a72a3b3dec55e78786fe60d4e52062a
7
+ data.tar.gz: c8363914b46a62567f1571c6575ab2094664c849787f57ece270083f8729babda5422fcc614fc02b497f1d0c45a56505df54373f64b4c1f426549b26db5e83e7
data/.gitignore CHANGED
@@ -4,3 +4,4 @@ Gemfile.lock
4
4
  .bundle
5
5
  bundle
6
6
  coverage
7
+ locales/r10k.pot
@@ -1,24 +1,51 @@
1
1
  CHANGELOG
2
2
  =========
3
3
 
4
- 2.3.1
4
+ 2.4.0
5
5
  -----
6
6
 
7
- 2016/11/30
7
+ 2016/08/10
8
8
 
9
- (RK-78) Use :prune option for #fetch in Rugged::BareRepository
9
+ ### New Features
10
+
11
+ (RK-222) New "install\_path" option for Git/SVN content.
12
+
13
+ This feature allows you to specify where inside an environment each item from the
14
+ Puppetfile should be installed to. See the [Puppetfile documentation](https://github.com/puppetlabs/r10k/blob/master/doc/puppetfile.mkd#per-item-install-path) for details.
15
+
16
+ (RK-246) New "environment" level purging and configurable purge levels.
17
+
18
+ You can now configure how r10k purges unmanaged content after a deployment. The
19
+ default behavior should be unchanged but there is a new "purge\_levels" configuration
20
+ option that can be used to enable new behavior or de-activate certain existing
21
+ behaviors. See the relevant [configration documentation](https://github.com/puppetlabs/r10k/blob/master/doc/dynamic-environments/configuration.mkd#purge_levels) for more details.
22
+
23
+ (RK-223) Ability to track control repo branch from content declarations.
24
+
25
+ Puppetfile content sourced from Git can now be configured to attempt to track the branch
26
+ name of the control repo branch being deployed. For example, if r10k is deploying
27
+ the 'production' branch of your control repo, it will try to also deploy the
28
+ 'production' branch of a given Puppetfile content repo. See the [documentation](https://github.com/puppetlabs/r10k/blob/master/doc/puppetfile.mkd#control-repo-branch-tracking)
29
+ for more details.
30
+
31
+ ### Internationalization
32
+
33
+ All user-facing strings generated by r10k have been externalized to enable future
34
+ iternationalization (i18n) and localization work.
35
+
36
+ ### Changed
37
+
38
+ (RK-258) Symlinks inside of Forge modules will no longer cause r10k to exit non-zero.
39
+ This situation used to raise an error but will now generate a WARN level log message
40
+ instead.
41
+
42
+ ### Bug Fixes
10
43
 
11
- Versions of the "rugged" gem prior to 0.24.0 lacked the ability to automatically
12
- "prune" branches from a local repo that no longer existed in the matching remote
13
- repo after a fetch. To work around this issue, r10k included code that would
14
- manually remove/recreate branches during a fetch. Since "rugged" 0.24.0 is now
15
- widely available, r10k has been updated to use the built-in "prune" option
16
- during a fetch and the workaround code has been removed.
44
+ (#616) Ensure that Forge module version strings are valid semantic versions. (Special
45
+ thanks to Patrick Robinson (patrobinson) for the fix.)
17
46
 
18
- NOTE: If you use the "rugged" gem with r10k, you will need to manually upgrade
19
- it to a version >= 0.24.0 to take advantage of the new functionality. If you
20
- are using a "rugged" version less than 0.24.0, r10k will now issue a warning
21
- every time it fetches from a remote git repository.
47
+ (#622) Fix typos in workflow docs. (Special thanks to Yury Frolov (mrdracon) for the
48
+ fix.)
22
49
 
23
50
  2.3.0
24
51
  -----
data/Gemfile CHANGED
@@ -1,5 +1,4 @@
1
- source 'https://rubygems.org'
2
-
1
+ source ENV['GEM_SOURCE'] || 'https://rubygems.org'
3
2
  gemspec
4
3
 
5
4
  group :extra do
data/README.mkd CHANGED
@@ -85,6 +85,22 @@ information see the topic specific documentation:
85
85
 
86
86
  For more general questions, see the [FAQ](doc/faq.mkd).
87
87
 
88
+ Development
89
+ -----------
90
+
91
+ ### i18n
92
+
93
+ R10k has now had all user-facing strings in error messages and log messages
94
+ externalized. When adding new error or log messages please follow the
95
+ instructions for [writing translatable code](https://github.com/puppetlabs/gettext-setup-gem#writing-translatable-code).
96
+
97
+ ### l10n
98
+
99
+ When localizing the strings found in R10k, follow the prescribed
100
+ [translation workflow](https://github.com/puppetlabs/gettext-setup-gem#translation-workflow).
101
+ The workflow describes the rake tasks provided to generate the .po files for
102
+ each locale.
103
+
88
104
  Getting help
89
105
  ------------
90
106
 
@@ -103,3 +119,12 @@ Contributors
103
119
  ------------
104
120
 
105
121
  Please see the CHANGELOG for a listing of the (very awesome) contributors.
122
+
123
+ ## Maintenance
124
+
125
+ Maintainers:
126
+
127
+ * Jesse Scott, jesse@puppet.com
128
+ * Anderson Mills, anderson@puppet.com
129
+
130
+ Tickets: File at https://tickets.puppet.com/browse/RK
@@ -0,0 +1,3 @@
1
+ spec = Gem::Specification.find_by_name 'gettext-setup'
2
+ load "#{spec.gem_dir}/lib/tasks/gettext.rake"
3
+ GettextSetup.initialize(File.absolute_path('locales', File.dirname(__FILE__)))
@@ -200,12 +200,92 @@ sources:
200
200
 
201
201
  ### deploy
202
202
 
203
- The `deploy` setting is a new top level setting for controlling how r10k deploys
203
+ The `deploy` setting is a top level setting for controlling how r10k deploys
204
204
  behave. At this point only new settings are included under this setting, but in
205
205
  the long term the current top level deploy settings will be moved under
206
206
  `deploy`.
207
207
 
208
- #### write_lock
208
+ #### purge\_levels
209
+
210
+ The `purge_levels` setting controls how aggressively r10k will purge unmanaged
211
+ content during a deployment. Given value must be a list of strings indicating at
212
+ what levels unmanaged content should be purged. The valid string options for the
213
+ list are 'deployment', 'environment', and 'puppetfile'.
214
+
215
+ ```yaml
216
+ ---
217
+ deploy:
218
+ purge_levels: [ 'deployment', 'environment', 'puppetfile' ]
219
+ ```
220
+
221
+ This setting currently only impacts the "deploy environment" action.
222
+
223
+ The default value is `['deployment', 'puppetfile']` to maintain parity with
224
+ existing behavior before this setting was added.
225
+
226
+ The effect of enabling the various purge levels is as follows:
227
+
228
+ ##### deployment
229
+
230
+ After each deploy, in the configured basedir, r10k will recursively remove any
231
+ content found which is not managed by one of the sources declared in the r10k.yaml
232
+ configuration. Note that disabling this level of purging may cause the number of
233
+ deployed environments to grow without bound; deleting branches from a control
234
+ repo would no longer cause the matching environment to be purged.
235
+
236
+ ##### environment
237
+
238
+ After a given environment is deployed, r10k will recursively remove any content
239
+ found which is neither committed to the control repo branch that maps to that
240
+ environment, nor declared in a Puppetfile committed to that branch.
241
+
242
+ Enabling this purge level will cause r10k to load and parse the Puppetfile for
243
+ the environment even without the `--puppetfile` flag being set. However,
244
+ Puppetfile content will still only be deployed if the environment is new or
245
+ the `--puppetfile` flag is set. Additionally, no environment-level content
246
+ will be purged if a Puppetfile content deploy was triggered but an error was
247
+ encountered.
248
+
249
+ Note that the .r10k-deploy.json file is exempt from this purging.
250
+
251
+ ##### puppetfile
252
+
253
+ After Puppetfile content for a given environment is deployed, r10k will
254
+ recursively remove any content found in a directory managed by the Puppetfile
255
+ which is not also declared in that Puppetfile. Directories considered to be
256
+ managed by a Puppetfile include the configured `moduledir` (which defaults to
257
+ "modules") as well as alternate directories specified as an `install\_path`
258
+ option to any Puppetfile content declarations.
259
+
260
+ #### purge\_whitelist
261
+
262
+ The `purge_whitelist` setting exempts the specified filename patterns from
263
+ being purged. This setting is currently only considered during `environment`
264
+ level purging. (See above.) Given value must be a list of shell style filename
265
+ patterns in string format.
266
+
267
+ See the Ruby [documentation for the `fnmatch` method](http://ruby-doc.org/core-2.2.0/File.html#method-c-fnmatch)
268
+ for more details on valid patterns. Note that the `FNM_PATHNAME` and
269
+ `FNM_DOTMATCH` flags are in effect when r10k considers the whitelist.
270
+
271
+ Patterns are relative to the root of the environment being purged and *do
272
+ not match recursively* by default. For example, a whitelist value of
273
+ `*myfile*` would only preserve a matching file at the root of the
274
+ environment. To preserve the file throughout the deployed environment,
275
+ a recursive pattern such as `**/*myfile*` would be required.
276
+
277
+ Files matching a whitelist pattern may still be removed if they exist in
278
+ a folder that is otherwise subject to purging. In this case, an additional
279
+ whitelist rule to preserve the containing folder is required.
280
+
281
+ ```yaml
282
+ ---
283
+ deploy:
284
+ purge_whitelist: [ 'custom.json', '**/*.xpp' ]
285
+ ```
286
+
287
+
288
+ #### write\_lock
209
289
 
210
290
  The `write_lock` setting allows administrators to temporarily disallow r10k code
211
291
  deploys without having to remove the r10k configuration entirely. This can be
@@ -214,10 +294,8 @@ with a common set of code that may be touched by multiple r10k configurations.
214
294
 
215
295
  ```yaml
216
296
  ---
217
-
218
297
  deploy:
219
298
  write_lock: "Deploying code is disallowed until the next maintenance window (2038-01-19)"
220
-
221
299
  ```
222
300
 
223
301
  Source options
@@ -353,16 +431,15 @@ must override the `prefix` so environment folders line up in both directories:
353
431
 
354
432
  ```yaml
355
433
  ---
356
- sources:
357
- main:
358
- app1_data:
359
- remote: 'git://git-server.site/my-org/app1-hieradata'
360
- basedir: '/etc/puppet/hieradata'
361
- prefix: "app1"
362
- app1_modules:
363
- remote: 'git://git-server.site/my-org/app1-puppet-modules'
364
- basedir: '/etc/puppet/environments'
365
- prefix: "app1"
434
+ sources:
435
+ app1_data:
436
+ remote: 'git://git-server.site/my-org/app1-hieradata'
437
+ basedir: '/etc/puppet/hieradata'
438
+ prefix: "app1"
439
+ app1_modules:
440
+ remote: 'git://git-server.site/my-org/app1-puppet-modules'
441
+ basedir: '/etc/puppet/environments'
442
+ prefix: "app1"
366
443
  ```
367
444
 
368
445
 
@@ -213,13 +213,13 @@ git merge feature
213
213
  git push origin master
214
214
  ```
215
215
 
216
- In the Control repo, check out master. Do NOT merge the feature branch as it
216
+ In the Control repo, check out production. Do NOT merge the feature branch as it
217
217
  now references the incorrect branch for each git repo, and no other changes
218
218
  were made (unlike a new module, where a new repo is referenced).
219
219
 
220
220
  ```
221
221
  # Control repo
222
- git checkout master
222
+ git checkout production
223
223
  ```
224
224
 
225
225
  ### Cleanup feature branches
@@ -234,7 +234,7 @@ git branch -D repo
234
234
  git push origin :repo
235
235
  ```
236
236
 
237
- Redeploy with r10k on the master and ensure there are no errors. The *feature*
237
+ Redeploy with r10k on your Puppet Master and ensure there are no errors. The *feature*
238
238
  dynamic environment should no longer exist at `$environmentpath/feature`.
239
239
 
240
240
  ```r10k deploy environment -p```
@@ -52,8 +52,7 @@ handles modules.
52
52
 
53
53
  The `forge` setting specifies which server that Forge based modules are fetched
54
54
  from. This is currently a noop and is provided for compatibility with
55
- librarian-puppet, but will be made functional in a future version. See
56
- [GH-106](https://github.com/adrienthebo/r10k/issues/106) for more information.
55
+ librarian-puppet.
57
56
 
58
57
  ### moduledir
59
58
 
@@ -88,7 +87,25 @@ Module types
88
87
  ------------
89
88
 
90
89
  r10k can install Puppet modules from a number of different sources. Right now
91
- modules can be installed via Git, SVN, and from the Puppet Forge.
90
+ modules can be installed from the Puppet Forge, Git, or SVN.
91
+
92
+ ### Puppet Forge
93
+
94
+ Modules can be installed from the Puppet Forge.
95
+
96
+ If no version is specified the latest version available at the time will be
97
+ installed, and will be kept at that version.
98
+
99
+ mod 'puppetlabs/apache'
100
+
101
+ If a version is specified then that version will be installed.
102
+
103
+ mod 'puppetlabs/apache', '0.10.0'
104
+
105
+ If the version is set to :latest then the module will be always updated to the
106
+ latest version available.
107
+
108
+ mod 'puppetlabs/apache', :latest
92
109
 
93
110
  ### Git
94
111
 
@@ -105,52 +122,68 @@ given object is a tag or commit and can do some optimizations around fetching
105
122
  the object. If the tag or commit is already available r10k will skip network
106
123
  operations when updating the repo, which can speed up install times.
107
124
 
108
- Module versions can also be specified using `:branch`. This behaves similarly to
109
- `:ref`, and is mainly useful for clarity.
125
+ Module versions can also be specified using `:branch` to track a specific
126
+ branch reference.
110
127
 
111
128
  #### Examples
112
129
 
113
- # Install puppetlabs/apache and keep it up to date with 'master'
114
- mod 'apache',
115
- :git => 'https://github.com/puppetlabs/puppetlabs-apache'
116
-
117
- # Install puppetlabs/apache and track the 'docs_experiment' branch
118
- mod 'apache',
119
- :git => 'https://github.com/puppetlabs/puppetlabs-apache',
120
- :ref => 'docs_experiment'
121
-
122
- # Install puppetlabs/apache and pin to the '0.9.0' tag
123
- mod 'apache',
124
- :git => 'https://github.com/puppetlabs/puppetlabs-apache',
125
- :tag => '0.9.0'
126
-
127
- # Install puppetlabs/apache and pin to the '83401079' commit
128
- mod 'apache',
129
- :git => 'https://github.com/puppetlabs/puppetlabs-apache',
130
- :commit => '83401079053dca11d61945bd9beef9ecf7576cbf'
131
-
132
- # Install puppetlabs/apache and track the 'docs_experiment' branch
133
- mod 'apache',
134
- :git => 'https://github.com/puppetlabs/puppetlabs-apache',
135
- :branch => 'docs_experiment'
130
+ ```ruby
131
+ # Install puppetlabs/apache and keep it up to date with 'master'
132
+ mod 'apache',
133
+ :git => 'https://github.com/puppetlabs/puppetlabs-apache'
134
+
135
+ # Install puppetlabs/apache and track the 'docs_experiment' branch
136
+ mod 'apache',
137
+ :git => 'https://github.com/puppetlabs/puppetlabs-apache',
138
+ :ref => 'docs_experiment'
139
+
140
+ # Install puppetlabs/apache and pin to the '0.9.0' tag
141
+ mod 'apache',
142
+ :git => 'https://github.com/puppetlabs/puppetlabs-apache',
143
+ :tag => '0.9.0'
144
+
145
+ # Install puppetlabs/apache and pin to the '83401079' commit
146
+ mod 'apache',
147
+ :git => 'https://github.com/puppetlabs/puppetlabs-apache',
148
+ :commit => '83401079053dca11d61945bd9beef9ecf7576cbf'
149
+
150
+ # Install puppetlabs/apache and track the 'docs_experiment' branch
151
+ mod 'apache',
152
+ :git => 'https://github.com/puppetlabs/puppetlabs-apache',
153
+ :branch => 'docs_experiment'
154
+ ```
136
155
 
137
- ### Forge
156
+ #### Control Repo Branch Tracking
138
157
 
139
- Modules can be installed using the Puppet module tool.
158
+ Since r10k 2.4.0, the `:branch` option can be set to the special value
159
+ `:control_branch` to indicate that the content should track a branch
160
+ reference matching the containing control repo branch. For example, if a
161
+ Puppetfile containing a Git content declaration is in the "testing" branch
162
+ of a control repo, a setting of `:control_branch` will attempt to deploy that
163
+ content from a "testing" branch of the content repo.
140
164
 
141
- If no version is specified the latest version available at the time will be
142
- installed, and will be kept at that version.
165
+ Additionally, you can specify a `:default_branch` option which is the branch
166
+ reference that content will be deployed from if the the given `:ref`, `:tag`,
167
+ `:commit`, or `:branch` option cannot be resolved and deployed. If the desired
168
+ content cannot be resolved and no default branch is given, or if the default
169
+ branch can also not be resolved, an error will be logged and the content will
170
+ not be deployed or updated.
143
171
 
144
- mod 'puppetlabs/apache'
145
-
146
- If a version is specified then that version will be installed.
147
-
148
- mod 'puppetlabs/apache', '0.10.0'
172
+ #### :control\_branch Examples
149
173
 
150
- If the version is set to :latest then the module will be always updated to the
151
- latest version available.
174
+ ```ruby
175
+ # Deploy content from branch matching control repo branch.
176
+ mod 'hieradata',
177
+ :git => 'git@git.example.com:organization/hieradata.git',
178
+ :branch => :control_branch
179
+
180
+ # Track control branch and fall-back to master if no matching branch.
181
+ mod 'hieradata',
182
+ :git => 'git@git.example.com:organization/hieradata.git',
183
+ :branch => :control_branch,
184
+ :default_branch => 'master'
185
+ ```
152
186
 
153
- mod 'puppetlabs/apache', :latest
154
187
 
155
188
  ### SVN
156
189
 
@@ -257,6 +290,22 @@ module.
257
290
  For more information see the [FAQ entry](faq.mkd#how-do-i-prevent-r10k-from-removing-modules-in-the-modules-directory-of-my-git-repository)
258
291
  on managing internal and external modules in the same directory.
259
292
 
293
+ ### Per-Item Install Path
294
+
295
+ Git and SVN content types support installing into an alternate path without changing
296
+ the value of moduledir by specifying an 'install\_path' option:
297
+
298
+ ```
299
+ # This will install the 'apache' module into 'external/apache'.
300
+ mod 'apache',
301
+ :git => 'git@github.com:puppetlabs/puppetlabs-apache.git',
302
+ :install_path => 'external'
303
+ ```
304
+
305
+ The given 'install\_path' can be an absolute path or a path relative to the base of
306
+ the environment. Note that r10k will exit with an error if you attempt to set the
307
+ 'path' option to a directory outside of the environment.
308
+
260
309
  ## Environment variables
261
310
 
262
311
  It is possible to set an alternate name/location for your `Puppetfile` and