Add instructions to run from a specific branch

doc/dev/run-from-branch.md

@@ -0,0 +1,62 @@
+# Running octocatalog-diff from a branch
+
+When we are assisting with troubleshooting, or implementing a feature you've requested, we may ask you to run `octocatalog-diff` from a non-master branch to try it out.
+
+This document is intended for people who may not be familiar with git, GitHub, and/or ruby. If you already know how to do this in another way, feel free!
+
+## Installation
+
+1. Determine the branch name. If there's an open Pull Request, you can see the branch name near the top of the page.
+
+  ![Pull Request branch](/doc/images/pull-request-identify-branch.png)
+
+2. Clone the `octocatalog-diff` repository in your home directory. From the command line:
+
+  ```
+  cd $HOME
+  git clone https://github.com/github/octocatalog-diff.git
+  ```
+
+3. Change into the directory created by your checkout:
+
+  ```
+  cd $HOME/octocatalog-diff
+  ```
+
+4. Check out the branch you wish to use, filling in the branch name you determined in the first step:
+
+  ```
+  git checkout BRANCH_NAME_FROM_STEP_1
+  ```
+
+5. Bootstrap the repository to pull in dependencies:
+
+  ```
+  ./script/bootstrap
+  ```
+
+6. Optional but recommended - run the test suite:
+
+  ```
+  rake
+  ```
+
+## Use
+
+Now that you have `octocatalog-diff` checked out and bootstrapped, it's time to use it.
+
+We've created a wrapper script to make this easier for you.
+
+1. Change directories to the location where you ordinarily run `octocatalog-diff` (for example: in your Puppet repository).
+
+    ```
+    cd /etc/puppetlabs/code
+    ```
+
+2. Run the `script/octocatalog-diff-wrapper` script from *this* checkout. For example, if you checked out `octocatalog-diff` to your home directory, you could use:
+
+    ```
+    $HOME/octocatalog-diff/script/octocatalog-diff-wrapper <options>
+    ```
+
+:warning: Note: If you are requesting our help, please use the debug option (`-d`) to display debugging information.

doc/installation.md

@@ -47,3 +47,9 @@ To install from source, you'll need a git client and internet access.
   Note: If tests fail on your machine with a clean checkout of the master branch, we would definitely appreciate if you would report it. Please [open an issue](https://github.com/github/octocatalog-diff/issues/new) with the output and some information about your system (e.g. OS, ruby version, etc.) to let us know.
 
 Once the code is downloaded and bootstrapped, please proceed to [Configuration](/doc/configuration.md).
+
+## Running from an alternate branch
+
+We have prepared specific instructions for running `octocatalog-diff` from a non-master branch, for testing changes that may be requested by the developers.
+
+- [Running octocatalog-diff from a branch](/doc/dev/run-from-branch.md)

lib/octocatalog-diff/catalog-diff/cli.rb

@@ -166,7 +166,8 @@ def self.setup_logger(logger, options, argv_save)
         logger.level = Logger::ERROR if options[:quiet]
 
         # Some debugging information up front
-        logger.debug "Running octocatalog-diff #{VERSION} with ruby #{RUBY_VERSION}"
+        version_display = ENV['OCTOCATALOG_DIFF_CUSTOM_VERSION'] || VERSION
+        logger.debug "Running octocatalog-diff #{version_display} with ruby #{RUBY_VERSION}"
         logger.debug "Command line arguments: #{argv_save.inspect}"
         logger.debug "Running on host #{Socket.gethostname} (#{RUBY_PLATFORM})"
       end

script/octocatalog-diff-wrapper

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# This script exists to make it easier to test alternate branches of octocatalog-diff.
+# It is intended as a one-for-one replacement of `octocatalog-diff` as installed by the gem.
+
+CURRENT_PWD="$(pwd)"
+CHECKOUT_BASE="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && cd .. && pwd )"
+
+if [ -z "$OCTOCATALOG_DIFF_CONFIG_FILE" ]; then
+  if [ -f "${CURRENT_PWD}/.octocatalog-diff.cfg.rb" ]; then
+    export OCTOCATALOG_DIFF_CONFIG_FILE="${CURRENT_PWD}/.octocatalog-diff.cfg.rb"
+  fi
+fi
+
+cd "$CHECKOUT_BASE"
+export OCTOCATALOG_DIFF_CUSTOM_VERSION="@$(git rev-parse HEAD)"
+bundle exec bin/octocatalog-diff --basedir "$CURRENT_PWD" $*

spec/octocatalog-diff/tests/catalog-diff/cli_spec.rb

@@ -115,6 +115,37 @@
     end
   end
 
+  describe '#setup_logger' do
+    context 'with custom version specified in environment' do
+      before(:each) do
+        ENV['OCTOCATALOG_DIFF_CUSTOM_VERSION'] = '@d05c30152c897219367d586414ccb1f651ab7221'
+      end
+
+      after(:each) do
+        ENV.delete 'OCTOCATALOG_DIFF_CUSTOM_VERSION'
+      end
+
+      it 'should log custom version' do
+        logger, logger_str = OctocatalogDiff::Spec.setup_logger
+        described_class.setup_logger(logger, { debug: true }, nil)
+        expect(logger_str.string).to match(/Running octocatalog-diff @d05c30152c897219367d586414ccb1f651ab7221 with ruby/)
+      end
+    end
+
+    context 'with default version' do
+      before(:each) do
+        ENV.delete 'OCTOCATALOG_DIFF_CUSTOM_VERSION'
+      end
+
+      it 'should log current version' do
+        logger, logger_str = OctocatalogDiff::Spec.setup_logger
+        described_class.setup_logger(logger, { debug: true }, nil)
+        version = described_class::VERSION
+        expect(logger_str.string).to match(/Running octocatalog-diff #{version} with ruby/)
+      end
+    end
+  end
+
   describe '#setup_fact_overrides' do
     it 'should make no adjustments when there are no fact overrides' do
       options = {}