Update documentation

doc/advanced-environments.md

@@ -0,0 +1,93 @@
+# Environment setup
+
+When building a catalog, the default behavior of `octocatalog-diff` is to:
+
+1. Create a temporary directory
+2. Create a symlink from `<temporary directory>/environments/production` to the checkout of your code
+3. Run Puppet using `environment=production`
+
+If you are using environment names to control the behavior of Puppet, this default behavior may not be suitable. In that case you can invoke the alternate behavior: preserving environments.
+
+## Command line options
+
+### Preserving the environments
+
+When you supply the command line argument `--preserve-environments` (or set `settings[:preserve_environments] = true` in your [configuration file](/doc/configuration.md)), `octocatalog-diff` will instead do the following:
+
+1. Create a temporary directory
+2. Create the following symlinks from `<temporary directory>` to the corresponding directories in the checkout of your code:
+
+  - `environments`
+  - `manifests`
+  - `modules`
+
+3. Run Puppet using an environment you specify via the command line
+
+Note that you must have set `--preserve-environments` in order for the `--environment` and/or `--create-symlinks` options (described below) to have any effect.
+
+### Changing the environment
+
+If you wish to use an environment name other than `production` you can use the `--environment <environment_name>` command line option. This will set the environment for both the `to` and `from` compiles.
+
+```
+octocatalog-diff ... --preserve-environments --environment some-env-name
+```
+
+If you need to specify different environments for the `to` and `from` compiles, you can use `--to-environment <environment_name>` and `--from-environment <environment_name>`.
+
+```
+octocatalog-diff ... --preserve-environments --to-environment first-environment --from-environment second-environment
+```
+
+### Controlling symlinks that are created
+
+Within the temporary directory, the `environments` symlink will always be created.
+
+By default, `manifests` and `modules` will also be created from the temporary directory to the corresponding directories in your Puppet code base. If you need to customize the symlinks that are created, you can use the `--create-symlinks <dir1>,<dir2>,...` to list the symlinks that you need.
+
+For example, if you have some code stored in a directory called `modules` and more code stored in a directory called `site`, you could do the following to create the symlinks as desired:
+
+```
+octocatalog-diff ... --preserve-environments --create-symlinks manifests,modules,site
+```
+
+## Examples
+
+Consider that your Puppet code base is organized as follows:
+
+```
+- /opt/puppet
+  - environments
+    - old
+      - environment.conf
+      - manifests
+        - site.pp
+      - modules
+        - module_zero
+    - new
+      - environment.conf
+      - manifests
+        - site.pp
+      - modules
+        - module_zero
+  - modules
+    - module_one
+    - module_two
+  - site
+    - module_three
+    - module_four
+```
+
+To calculate the difference between the "old" and "new" environment, you could use:
+
+```
+octocatalog-diff \
+  --bootstrapped-from-dir /opt/puppet \
+  --bootstrapped-to-dir /opt/puppet \
+  --preserve-environments \
+  --from-environment old \
+  --to-environment new \
+  --create-symlinks modules,site
+```
+
+(Note that `--bootstrapped-from-dir` and `--bootstrapped-to-dir` are used to specify the directory path to your code, and `-t` and `-f` are not used. That's because the difference in the catalog is derived from the environment used, and not the branch from a git repository.)

doc/advanced.md

@@ -22,6 +22,7 @@ See also:
 - [Puppet Enterprise node classification service](/doc/advanced-pe-enc.md)
 - [Using `octocatalog-diff` without git](/doc/advanced-using-without-git.md)
 - [Catalog validation](/doc/advanced-catalog-validation.md)
+- [Environment setup](/doc/advanced-environment.md)
 
 ### Controlling output