octocatalog-diff 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 884750a5cc423f972506a90a43ea39afde1ec405
+  data.tar.gz: 2374a0483c93b1a65fd94f986819c5564a96dd3c
+SHA512:
+  metadata.gz: 739226ba6430412af00c3fe3ca91cced879a9b3aaa836cea7f418c50eae5f2b740335a3a066bc41b7e034f510021a7bd8f169b0b683d67bbf04f742e8ae5aee3
+  data.tar.gz: 16f3bb672a86f60aa3edb541ae2189fca978b9d9be4b754de48f3ce4b61c441a23baff521561f64fdb883f41848400d84df70bae5b2f83eef5252baf27e6820b

data/.version

@@ -0,0 +1 @@
+0.5.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+# octocatalog-diff
+
+#### Compile Puppet catalogs from 2 branches, versions, etc., and compare them <img src="/doc/images/octocatolog-diff-logo.png" align="right" height=126 width=240>
+
+`octocatalog-diff` is a tool that enables developers to be more efficient when testing changes to Puppet manifests. It is most commonly used to display differences in Puppet catalogs between stable and development branches. It does not require a working Puppet master (or puppetserver), so it is often run by developers on their workstations and in Continuous Integration environments.
+
+At GitHub, we manage thousands of nodes with a Puppet code base containing 500,000+ lines of code from over 200 contributors. We run `octocatalog-diff` thousands of times per day as part of Continuous Integration testing, and developers run it on their workstations as they are working with the code.
+
+`octocatalog-diff` is written in Ruby and is distributed as a gem. It runs on Mac OS and Unix/Linux platforms.
+
+It is under active development at this time. We suspect that with the initial release, some people who try it out could be using configurations of Puppet that we haven't experienced within our environment. We are eager to identify and fix as many of these as we can to expand the compatibility of this tool as much as possible.
+
+## How?
+
+Traditional Puppet development generally takes one of two forms. Frequently, developers will test changes by running a Puppet agent (perhaps in `--noop` mode) to see if the desired change has resulted on an actual system. Others will use formal testing methodologies, such as `rspec-puppet` or the beaker framework to validate Puppet code.
+
+`octocatalog-diff` uses a different pattern. In its most common invocation, it compiles Puppet catalogs for both the stable branch (e.g. master) and the development branch, and then compares them. It filters out attributes or resources that have no effect on ultimate state of the target system (e.g. tags) and displays the remaining differences. Using this strategy, one can get feedback on changes without deploying Puppet code to a server and conducting a full Puppet run, and this tool works even if test coverage is incomplete.
+
+There are some [limitations](doc/limitations.md) to a catalog-based approach, meaning it will never completely replace unit, integration, or deployment testing. However, it does provide substantial time savings in both the development and testing cycle. In this repository, we provide example scripts for using `octocatalog-diff` in development and CI environments.
+
+`octocatalog-diff` is currently able to get catalogs by the following methods:
+- Compile catalog via the command line with a Puppet agent on your machine (as GitHub uses the tool internally)
+- Obtain catalog over the network from PuppetDB
+- Obtain catalog over the network using the API to query a Puppet Master / PuppetServer (Puppet 3.x and 4.x supported)
+- Read catalog from a JSON file
+
+## Example
+
+Here is simulated output from running `octocatalog-diff` to compare the Puppet catalog changes between the master branch and the Puppet code in the current working directory:
+
+<img src="doc/images/screenshot1.png" alt="[octocatalog-diff screenshot]">
+
+The example above reflects the changes in the Puppet catalog from switching an underlying device for a mounted file system.
+
+## Documentation
+
+### Installation and use in a development environment
+
+- [Installation](/doc/installation.md)
+- [Configuration](/doc/configuration.md)
+- [Basic command line usage](/doc/basic.md)
+- [Advanced command line usage](/doc/advanced.md)
+- [Troubleshooting](/doc/troubleshooting.md)
+
+### Installation and use for CI
+
+- [Setting up octocatalog-diff in CI](/doc/advanced-ci.md)
+
+### Technical details
+
+- [Requirements](/doc/requirements.md)
+- [Limitations](/doc/limitations.md)
+- [List of all command line options](/doc/optionsref.md)
+
+### Project
+
+- [Roadmap](/doc/roadmap.md)
+- [Similar tools](/doc/similar.md)
+- [Contributing](/.github/CONTRIBUTING.md)
+- [Developer documentation](/doc/dev)
+
+## What's in a name?
+
+During its original development at GitHub, this tool was simply called `catalog-diff`. However, there is already a [Puppet module with that name](https://forge.puppet.com/zack/catalog_diff) and we didn't want to create any confusion (in fact, a case could be made to use both approaches). So, we named the tool `octocatalog-diff` because who doesn't like the [octocat](https://octodex.github.com/)? Then one day in chat, someone referred to the tool as ":octocat:alog-diff", and that moniker caught on for electronic communication.
+
+## Contributing
+
+Please see our [contributing document](/.github/CONTRIBUTING.md) if you would like to participate!
+
+## Getting help
+
+If you have a problem or suggestion, please [open an issue](https://github.com/github/octocatalog-diff/issues/new) in this repository, and we will do our best to help. Please note that this project adheres to the [Open Code of Conduct](http://todogroup.org/opencodeofconduct/#GitHub%20Octocatalog-Diff/opensource@github.com).
+
+## License
+
+`octocatalog-diff` is licensed under the [MIT license](LICENSE).
+
+It requires 3rd party ruby gems found [here](/vendor/cache). It also includes portions of other open source projects [here](/lib/octocatalog-diff/external/pson), [here](/spec/octocatalog-diff/fixtures/repos/default/modules/stdlib), [here](/spec/octocatalog-diff/support/httparty) and [here](/spec/octocatalog-diff/tests/external/pson). All 3rd party code and required gems are licensed either as MIT or Apache 2.0.
+
+## Authors
+
+`octocatalog-diff` was designed and authored by [Kevin Paulisse](https://github.com/kpaulisse) and is now maintained, reviewed, and tested by the Site Reliability Engineering team at GitHub.

data/bin/octocatalog-diff

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+
+if ENV['OCTOCATALOG_DIFF_DEVELOPER_PATH']
+  # Mostly used for internal testing, to allow pointing of a "real" octocatalog-diff install
+  # at code being developed live.
+  rel = File.expand_path(ENV['OCTOCATALOG_DIFF_DEVELOPER_PATH'], File.dirname(__FILE__))
+  abs = File.expand_path(ENV['OCTOCATALOG_DIFF_DEVELOPER_PATH'])
+  if File.directory?(abs) && File.file?(File.join(abs, 'lib', 'octocatalog-diff.rb'))
+    require File.join(abs, 'lib', 'octocatalog-diff')
+  elsif File.directory?(rel) && File.file?(File.join(rel, 'lib', 'octocatalog-diff.rb'))
+    require File.join(rel, 'lib', 'octocatalog-diff')
+  else
+    raise Errno::ENOENT, "Unable to resolve #{ENV['OCTOCATALOG_DIFF_DEVELOPER_PATH']} (tried #{abs} then #{rel})"
+  end
+elsif File.file?(File.expand_path('../lib/octocatalog-diff.rb', File.dirname(__FILE__)))
+  require_relative '../lib/octocatalog-diff'
+else
+  require 'octocatalog-diff'
+end
+
+config_test = ARGV.include?('--config-test')
+
+paths = [
+  ENV['OCTOCATALOG_DIFF_CONFIG_FILE'],
+  File.join(Dir.pwd, '.octocatalog-diff.cfg.rb'),
+  File.join(ENV['HOME'], '.octocatalog-diff.cfg.rb'),
+  '/opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb',
+  '/usr/local/etc/octocatalog-diff.cfg.rb',
+  '/etc/octocatalog-diff.cfg.rb'
+]
+
+cfgfile = nil
+
+paths.each do |path|
+  next if path.nil?
+  puts "Looking for config in: #{path}" if config_test
+  next unless File.file?(path)
+  begin
+    cfgfile = path
+    puts "Loading config: #{path}" if config_test
+    require path
+  rescue => exc
+    STDERR.puts "#{exc.class} error with #{path}: #{exc.message}\n#{exc.backtrace}"
+    exit 1
+  end
+  break
+end
+
+options = {}
+
+if cfgfile
+  begin
+    options = OctocatalogDiff::Config.config
+  rescue => exc
+    STDERR.puts "#{exc.class} error with #{cfgfile}: #{exc.message}\n#{exc.backtrace}"
+    exit 1
+  end
+  unless options.is_a?(Hash)
+    STDERR.puts "Configuration must be Hash not #{options.class}!"
+    exit 1
+  end
+  if config_test
+    options.each do |key, val|
+      puts ":#{key} => (#{val.class}) #{val.inspect}"
+    end
+    exit 0
+  end
+elsif config_test
+  STDERR.puts 'No configuration files found'
+  exit 1
+end
+
+argv = ARGV.dup
+exit_code = OctocatalogDiff::CatalogDiff::Cli.cli(argv, Logger.new(STDERR), options)
+exit(exit_code)

data/doc/advanced-bootstrap.md

@@ -0,0 +1,33 @@
+# Bootstrapping your Puppet checkout
+
+For many implementations of Puppet, an intermediate step is required between checking out code from a repository and having that code be ready to be served via a Puppet Master server. For example, you may need to run `bundler` to install gems or `librarian-puppet` to download Puppet modules. This document will refer to this process -- whatever it may mean for your particular use case -- as *bootstrapping*.
+
+## Bootstrapping with `octocatalog-diff`
+
+Since `octocatalog-diff` integrates closely with your git repository, we provide a mechanism to allow you to perform your bootstrapping between the checkout of the branch and the build of the catalog.
+
+The `--bootstrap-script` option takes a string parameter consisting of either:
+
+  - An absolute path, starting with `/`
+  - A path relative to your Puppet checkout, not starting with `/`
+
+For example, if you have a script named `script/bootstrap.sh` in a subdirectory of your Puppet repository, you could instruct `octocatalog-diff` to use this script for bootstrap by specifying:
+
+```
+octocatalog-diff --bootstrap-script script/bootstrap.sh ...
+```
+
+If you have your bootstrap script at a known location on the system (not stored in your Puppet repository), you can refer to it with an absolute path.
+
+```
+octocatalog-diff --bootstrap-script /etc/puppetlabs/repo-bootstrap.sh ...
+```
+
+## Configuring bootstrapping via the configuration file
+
+The [example configuration file](/examples/octocatalog-diff.cfg.rb) contains an example setting for the bootstrap script.
+
+```
+# settings[:bootstrap_script] = '/etc/puppetlabs/repo-bootstrap.sh' # Absolute path
+# settings[:bootstrap_script] = 'script/bootstrap' # Relative path
+```

data/doc/advanced-cache-dir.md

@@ -0,0 +1,24 @@
+# Enabling the cache directory
+
+If you are running `octocatalog-diff` on your workstation, enabling the cache directory can support faster runs by:
+
+- Bootstrapping the `master` branch and saving that in a directory, so that you do not need to bootstrap the `master` branch each time you run `octocatalog-diff`.
+- Saving the `master` catalog for each node, so that for the second and subsequent difference calculation, this catalog does not need to be re-computed.
+
+We recommend that you configure these settings in your [configuration file](/doc/configuration.md), although it is possible to specify these settings on the command line as well.
+
+## Cache directory options
+
+There are two options that pertain to the cache directory:
+
+- `--cached-master-dir DIRECTORY_PATH`
+
+  This is the full path to the directory where the bootstrapped master directory will reside. Please note that this directory will be created if it doesn't exist, but for the directory to be created, *its parent directory must already exist*. You will receive an error message if you specify a directory path that is not a directory, or cannot be created as a directory.
+
+  Note that a subdirectory called `.catalogs` will be created within the chosen directory paths, and compiled `master` catalogs for nodes will be stored therein.
+
+- `--safe-to-delete-cached-master-dir DIRECTORY_PATH`
+
+  If you want to allow `octocatalog-diff` to delete the cached master directory when it becomes stale, set this option. If you do not set this option, and the cached master directory becomes stale, an error will be raised.
+
+  Historically, this was separated from `--cached-master-dir` to provide a separation between routine behavior (creating files and catalogs) and destructive behavior (deleting an entire directory).

data/doc/advanced-catalog-only.md

@@ -0,0 +1,37 @@
+# Building catalogs instead of diffing catalogs
+
+`octocatalog-diff` is designed primarily to build two catalogs and compare them. However, it can also simply generate the catalog without performing comparisons.
+
+## Usage
+
+The `--catalog-only` command line flag triggers the following behavior:
+
+  - The compiled catalog (not the difference) is written to the screen or stored in a file
+  - Only the "to" branch is relevant (the "from" branch is not touched)
+  - Options that control [output formats](/doc/advanced-output-formats.md), such as color and JSON format, do not apply
+  - The `-o FILENAME` option will write the catalog to the indicated file rather than displaying it on screen
+
+## Examples
+
+Building a catalog for a node from the current working directory and displaying on screen:
+
+```
+octocatalog-diff -n some-node.example.com --catalog-only
+```
+
+Building a catalog for a node from a specific branch and saving to a file:
+
+```
+octocatalog-diff -n some-node.example.com -t my-branch -o /tmp/some-node.json --catalog-only
+```
+
+As part of a CI job, testing whether a catalog for a particular host compiles:
+
+```
+octocatalog-diff -n some-node.example.com -o /dev/null --catalog-only
+if [ $? -eq 0 ]; then
+  echo "Pass"
+else
+  echo "Fail"
+fi
+```

data/doc/advanced-ci.md

@@ -0,0 +1,13 @@
+# Using `octocatalog-diff` in CI
+
+## Catalog compilation check
+
+Compile the catalog for several important hosts, and ensure that all catalogs successfully compile before permitting the merge. This is a pass/fail check.
+
+- [Sample rspec file for catalog compilation test](/examples/ci/puppet_catalogs_spec.rb)
+
+## Catalog difference analysis
+
+Compute the difference between the proposed code and the base branch across a number of hosts. This is more than just a pass/fail check, as a human should review the results to ensure that the differences are expected.
+
+- [Sample rspec file for catalog difference analysis](/examples/ci/puppet_catalog_diff_spec.rb)

data/doc/advanced-dynamic-ignores.md

@@ -0,0 +1,123 @@
+# Dynamic Ignoring Based On Tags
+
+Using the `--ignore-tags` command line option, it is possible to ignore all resources with particular Puppet tags. This allows dynamic ignoring of wrappers or other resources that are not of interest.
+
+## Getting Started
+
+To use ignored tags, you first need to decide what the name of your tag will be. The standard is `ignored_octocatalog_diff`.
+
+When you are writing Puppet code, you can tag a particular resource as being of no interest to `octocatalog-diff`.
+
+```
+class foo {
+  file { '/etc/foo':
+    ensure => file,
+    source => 'puppet:///modules/foo/etc/foo',
+    tag    => [ 'ignored_octocatalog_diff' ],
+  }
+}
+```
+
+You can also tag a resource that is a custom defined type.
+
+```
+class foo {
+  foo::customfile { '/etc/foo':
+    source => 'puppet:///modules/foo/etc/foo',
+    tag    => [ 'ignored_octocatalog_diff__foo__customfile' ],
+  }
+}
+
+define foo::customfile (
+  String $source,
+) {
+  file { $name:
+    ensure => file,
+    source => $source,
+  }
+}
+```
+
+Finally, you can tag an entire defined type.
+
+```
+class foo {
+  foo::customfile { '/etc/foo':
+    source => 'puppet:///modules/foo/etc/foo',
+  }
+}
+
+define foo::customfile (
+  String $source,
+) {
+  tag 'ignored_octocatalog_diff__foo__customfile'
+
+  file { $name:
+    ensure => file,
+    source => $source,
+  }
+}
+```
+
+When octocatalog-diff processes the ignore-tag, it will ignore a resource if either of the following is true:
+
+- The resource has a tag exactly matching the ignore-tag. For the default tag name, this means a resource has the tag `ignored_octocatalog_diff`.
+
+- The resource has a tag that matches the ignore-tag joined to the type with two underscores (where the type is in lower case and non-alphanumeric characters are replaced with underscores). This means that when the ignore-tag is `ignored_octocatalog_diff`, octocatalog-diff would ignore a file resource with a tag of `ignored_octocatalog_diff__file`, but would not ignore an exec resource with that same tag.
+
+The reasoning for the second syntax is explained in [caveats](#caveats).
+
+## Usage
+
+To ignore one tag:
+
+```
+octocatalog-diff --ignore-tags ignored_octocatalog_diff ...
+```
+
+To ignore multiple tags:
+
+```
+octocatalog-diff --ignore-tags ignored_octocatalog_diff --ignore-tags second_tag ...
+```
+
+To disable all ignoring of tags:
+
+```
+octocatalog-diff --no-ignore-tags ...
+```
+
+## Caveats
+
+When you tag a resource or defined type, Puppet will propagate that tag to *all* descendent resources.
+
+In this example, the tag `ignored_octocatalog_diff__foo__customfile` is propagated to the `foo::customfile` resource and to the file resource. However, octocatalog-diff will ignore only the `foo::customfile`, and will not ignore the file resource.
+
+```
+define foo::customfile (
+  String $source,
+) {
+  tag 'ignored_octocatalog_diff__foo__customfile'
+
+  file { $name:
+    ensure => file,
+    source => $source,
+  }
+}
+```
+
+:warning: If you were to do the following, not only would changes to `foo::customfile` parameters be ignored, but changes to the file resource would be ignored as well! That's because both `foo::customfile` and the file would have the tag `ignored_octocatalog_diff`, because the tag set in the defined type propagates to all descendent resources.
+
+```
+define foo::customfile (
+  String $source,
+) {
+  # DO NOT DO THIS!!!
+  tag 'ignored_octocatalog_diff'
+
+  file { $name:
+    ensure => file,
+    source => $source,
+  }
+}
+```

data/doc/advanced-future-parser.md

@@ -0,0 +1,11 @@
+# Enabling the future parser
+
+The [future parser](https://docs.puppet.com/puppet/3.8/reference/experiments_future.html) is a feature in Puppet 3.8 designed to provide functionally identical to the Puppet language in Puppet 4.0.
+
+You can use these options to enable the future parser for the "from" catalog, the "to" catalog, or both catalogs:
+
+- `--parser-from future` will enable the future parser for the "from" catalog
+- `--parser-to future` will enable the future parser for the "to" catalog
+- `--parser future` will enable the future parser for both the "from" catalog and the "to" catalog
+
+Note that you can also enable the future parser by creating a file named `environment.conf` in the base directory of your Puppet checkout. When `octocatalog-diff` computes the catalog from this directory, Puppet will read this file and act upon it accordingly.

data/doc/advanced-ignores.md

@@ -0,0 +1,224 @@
+# Ignoring certain changes from the command line
+
+`octocatalog-diff` provides a means to ignore certain changes in the displayed output. You may choose to ignore a change because you know it has no effect on the system. Or perhaps you are aware that the change is being made (perhaps in many different places) and you want to suppress it so other changes will not be lost in the noise.
+
+## Built-in ignores
+
+`octocatalog-diff` automatically ignores any changes to the following:
+
+- Classes and class parameters. Classes themselves are structures to contain resources, but do not themselves trigger actions on agents. Resources in classes are reported on, but the actual classes themselves, and parameters associated with the classes, are not.
+- Tags. Tags are useful for classification and collecting resources, but tags themselves do not trigger actions on agents. If you would like to see changes to tags, you can use `--no-ignore-tags`. Please note that tags are sorted alphabetically before comparison, so differences to the order of the tags will not ever show as a difference.
+- Resource attributes: `before` and `require`. These attributes control ordering on the agent, but we have found that displaying them in the diff has little value because the target resources are not often seen. If you are looking to visualize your infrastructure, Puppet Enterprise [now has that feature](https://puppet.com/blog/visualize-your-infrastructure-models). Please note: `octocatalog-diff` does display changes to `subscribe` and `notify` parameters.
+
+## Ignoring via the `--ignore` command line option
+
+If you specify multiple `--ignore` options, they are OR'd. In other words, if a change matches *any* of the ignored conditions, it is ignored.
+
+### Ignoring by type
+
+If you wish to ignore all changes to a certain resource type, use this syntax. For example, if you wanted to ignore all changes to 'exec' you would use:
+
+      --ignore 'Exec[*]'
+
+Or to ignore changes to a custom defined type, you would use:
+
+      --ignore 'Your::Custom::Type[*]'
+
+The matching is case insensitive, so `--ignore Exec[*]` and `--ignore exec[*]` are equivalent.
+
+### Ignoring by type and title
+
+If you wish to ignore all changes to a certain resource identified by its type and title, use this syntax. For example, to ignore all changes to your `/etc/motd` file you would use:
+
+      --ignore 'File[/etc/motd]'
+
+You can use wildcards in the title. Wildcards can be placed at the beginning, in the middle, or at the end of the title. You can also use multiple wildcards. `*` is the only wildcard supported, and it matches 0 or more characters. For example:
+
+      --ignore 'File[*]'             - Ignores all files
+      --ignore 'File[/etc/foo/*]'    - Ignores all files in or under '/etc/foo'
+      --ignore 'File[*/foo]'         - Ignores files named 'foo' anywhere in the file system
+      --ignore 'File[/etc/*/foo]'    - Ignores files named 'foo' in subdirectories of '/etc/'
+      --ignore 'File[/etc/*/foo/*]'  - Ignores all files under subdirectories named 'foo' under '/etc'
+
+Note that unlike on a unix system, `*` here matches any character, including "dot files." Therefore `--ignore File[/home/joe/*]` *would* ignore changes made, for example, to `/home/joe/.bashrc`.
+
+:warning: Do not put quotes of any kind in the ignore (e.g. `File['/etc/passwd']`) as these will be interpreted literally.
+
+### Ignoring by attribute
+
+If you wish to ignore all changes to a particular attribute regardless of the resource with which it is associated, use this syntax. For example, if you wanted to ignore all changes to an attribute called `i_dont_care_about_this` you would use:
+
+      --ignore-attr 'i_dont_care_about_this'
+
+That syntax will ignore a key `i_dont_care_about_this` *anywhere* it appears in the data structure -- top level key, last key, or something in between.
+
+If you want more control over where in the data structure the key appears, you can use '::' to separate multiple layers. For example, if your resource looked like this:
+
+      {
+        "type": "File",
+        "title": "/tmp/foo",
+        "parameters": {
+          "owner": "root",
+          "i_dont_care_about_this": "foo bar"
+        }
+      }
+
+You could use the following syntax to suppress `i_dont_care_about_this` only as it appears in the parameters hash using:
+
+      --ignore-attr 'parameters::i_dont_care_about_this'
+
+If you want to specify that you are starting from the top of the data structure, prepend `::` to the attribute. For example:
+
+      --ignore-attr '::parameters::i_dont_care_about_this'
+
+The difference between this syntax and the one appearing immediately before it is as follows. With the leading `::` it forces the attribute match to start at the top level of the data structure. Without the leading `::`, *any* place in the data structure where a key named `parameters` was a hash containing a key named `i_dont_care_about_this` would be matched. Typically there is not a deep level of nesting in Puppet catalogs so this distinction is minimal. However, multiple levels of nesting can occur when hashes are passed as parameters within Puppet manifests.
+
+TIP: For most attributes you wish to ignore, you should start with `::parameters` which is the standard top-level data structure within each catalog resource. As such, the remaining examples in this section will use this syntax.
+
+Functionally, `--ignore-attr 'FOO'` is equivalent to `--ignore '*[*]FOO'`, but that's less elegant. The prior example *could* be rewritten as:
+
+      --ignore '*[*]::parameters::i_dont_care_about_this'
+
+### Ignoring by type, title, and attribute
+
+`octocatalog-diff` allows you to ignore attributes that belong only to a specified type, or type + title.
+
+For example, maybe you want to ignore ownership changes to your `/tmp/foo` file. You could use the following syntax:
+
+      --ignore 'File[/tmp/foo]::parameters::owner'
+
+You can use wildcards `*` in the resource title as described previously. For example, to ignore owner changes for all files in the `/tmp` directory you could use:
+
+      --ignore 'File[/tmp/*]::parameters::owner'
+
+### Ignoring by type, title, and attribute with conditions
+
+These functions allow you to ignore attributes, but only if the values of the attributes themselves or nature of the changes satisfy certain conditions.
+
+#### Ignoring additions and removals but not changes
+
+You can ignore resources that were added to the catalog. This syntax will *not* display an entry for any file in `/tmp` that was brand new in the new catalog. However, if the file resource existed in the old catalog and something changed, that's a change and not an addition, so it will display. For example:
+
+      --ignore 'File[/tmp/*]+'
+
+The above will suppress this change because it's strictly an addition:
+
+      + File[/tmp/brand-new-file]
+
+The above will NOT suppress this change because the resource existed before and changed:
+
+~~~~~~~~
++ File[/tmp/my-file] =>
+   parameters =>
+     owner =>
+       - root
+       + new-owner
+~~~~~~~~
+
+Similarly, you can ignore resources that were entirely removed from the catalog.
+
+      --ignore 'File[/tmp/*]-'
+
+And, you can ignore resources that were either entirely removed or entirely added:
+
+~~~~~~~~
+--ignore 'File[/tmp/*]+-'
+(or, equivalently)
+--ignore 'File[/tmp/*]+' --ignore 'File[/tmp/*]-'
+~~~~~~~~
+
+#### Ignoring for a specific value of an attribute
+
+You can ignore changes to an attribute when the value of the attribute matches a specific string or pattern.
+
+When you use this syntax, the tool will ignore the change if the specified value applies to the attribute in *either* the old catalog or the new catalog. To ignore all changes to file owners, if the file owner was root before or the file owner is now root, you could use the `=>` matcher:
+
+      --ignore 'File[/tmp/*]::parameters::owner=>root'
+
+You can also use a regular expression. For example, to ignore changes if a file's content change includes "ice cream" you could use the `=~>` regular expression matcher:
+
+      ---ignore 'File[/tmp/*]::parameters::content=~>ice cream'
+
+#### Ignoring attributes that were added or removed
+
+Similar to ignoring resources that were added or removed, you can also ignore attributes that were added or removed by prefixing the attribute name with a `+` or `-`.
+
+To ignore any new parameters named `foo` (i.e., where no attribute named `foo` was defined in the old catalog, but it is defined in the new catalog), you would use:
+
+      --ignore 'My::Custom::Resource[*]+::parameters::foo'
+
+Similarly, to ignore the removal of the parameter named `foo` (i.e., where `foo` was defined in the old catalog, but is not defined in the new catalog), you would use:
+
+      --ignore 'My::Custom::Resource[*]-::parameters::foo'
+
+It is possible to combine this condition with the attribute value check defined above. For example, to ignore a new parameter `foo` with value `bar`:
+
+      --ignore 'My::Custom::Resource[*]+::parameters::foo=>bar'
+
+#### Ignoring attribute values but only in the new catalog or the old catalog
+
+Commonly, you will wish to suppress changes if an attribute is a certain value in the new catalog (or perhaps, a certain value in the old catalog). Say for example that you want to ignore any files that are now owned by root, but you will want to know about files that were owned by root and are now owned by somebody else. `=>root` would match files that were owned by root in the old catalog too but changed to somebody else in the new catalog, so that is too broad.
+
+The `=+>` operator performs a string match only in the new catalog, and `=->` performs a string match only in the new catalog. This will ignore any file resources under `/tmp` where the owner has changed, and the new owner is root:
+
+      --ignore 'File[/tmp/*]::parameters::owner=+>root'
+
+As a similar example, perhaps you have terminated a user joe, and need to reassign ownership of his files to someone else. You want to ignore any files that were previously owned by joe, but you do want to know about files that you've accidentally reassigned *to* joe (because you don't believe there should be any). To ignore files owned by joe in the old catalog, where the new owner is someone other than joe:
+
+      --ignore 'File[/tmp/*]::parameters::owner=->joe'
+
+If you need to use regular expressions, note that *changed lines* are preceded by `+` or `-` due to the `diff` implementation. More complicated, but equally functional, representations of the above commands are, respectively:
+
+      --ignore 'File[/tmp/*]::parameters::owner=~>^\+root$'
+
+      --ignore 'File[/tmp/*]::parameters::owner=~>^-joe$'
+
+:warning: Be sure to escape your literal '+' in the regular expression!
+
+Note that this syntax differs from `--ignore 'File[/tmp/*]+::...'` described in the prior section. The `+` or `-` between the title and the attribute indicates that the attribute must be brand new or completely removed; this will not ignore changes. Whereas using a `+` or `-` in the predicate of a string matcher will match changes between the catalogs.
+
+If you want to ignore changes where the attribute value exactly matches certain value in the old catalog, and exactly matches a certain other value in the new catalog, this is possible using the encompassing regular expressions described in the next section. You cannot combine `=+>` and `=->` in the same ignore condition.
+
+#### Ignoring attributes whose changes are encompassed by a regular expression
+
+It is possible to ignore changes only if *all* changed lines are matched by a regular expression. This is useful to suppress expected changes to an attribute, while still surfacing unexpected changes.
+
+As an example, consider that two catalogs defined the content of a file, which had this difference:
+
+~~~~~~~~
+File[/tmp/foo] =>
+ parameters =>
+   content =>
+    @@ -1,4 +1,4 @@
+     # This file is managed by Puppet. DO NOT EDIT.
+    -This is the line in the old catalog that I do not care about
+    +This is the line in the new catalog that I do not care about
+     This line is very important
+~~~~~~~~
+
+Suppose that you do not care to see this change. You can use the `=&>` operator to specify *one* regular expression that must match *all* lines that are changed. (You do not need to worry about the `@@ -1,4 +1,4 @@` line, as that's an artifact of the `diff` process, and is not considered in the analysis.)
+
+One implementation of ignoring the line in question could be:
+
+      --ignore 'File[/tmp/foo]::parameters::content=&>^(-This is the line in the old catalog that I do not care about)|(\+This is the line in the new catalog that I do not care about)$'
+
+If you aren't concerned about an edge case such as "This is the line in the new catalog that I do not care about" appearing in the old catalog, you could condense this to:
+
+      --ignore 'File[/tmp/foo]::parameters::content=&>^[\-\+]This is the line in the (old|new) catalog that I do not care about$'
+
+Consider now that the change to the file looked like this instead:
+
+~~~~~~~~
+File[/tmp/foo] =>
+ parameters =>
+   content =>
+    @@ -1,4 +1,4 @@
+     # This file is managed by Puppet. DO NOT EDIT.
+    -This is the line in the old catalog that I do not care about
+    +This is the line in the new catalog that I do not care about
+    -This line is very important
+~~~~~~~~
+
+In this case, the very important line was removed from the catalog, and you want to know about this. Ignoring `File[/tmp/foo]::parameters::content` would have suppressed this (because all changes to that attribute are ignored). Also ignoring `File[/tmp/foo]::parameters::content=~>This is the line in the new catalog that I do not care about$` would have also suppressed this (because the regular expression was matched for *one* of the lines). However, the two examples with `=&>` in this section would *not* have suppressed this change, because it is no longer the case that *all* changes in the file matched the regular expression.
+
+:warning: All lines are stripped of leading and trailing spaces before the regular expression match is tried. This stripping of whitespace is done *only* for this comparison stage, and does not affect the display of any results.