Interrogating a Lineman project's configuration

instructions.md

lineman-config

A little known feature of Lineman is the lineman config command, which lets you interrogate the final resolution of any (or the entire) Lineman grunt configuration.

This is especially helpful when you're (a) curious what property path you need to override and how, or (b) debugging an issue in which a plugin module or file is clobbering your intended config and it's unclear which config will win at task-run-time.

So, as an illustration I just ran into an issue where the "pages" task was conflicting with my markdown task (which also happens to expect files in app/pages).

Because I was surprised the pages task was acting on files with an ".md" extension, I decided to first ask Lineman for the pages configuration:

$ lineman config pages

{ dev: 
   { files: 
      { generated: '<%= files.pages.source %>',
        'generated/index.html': 'app/templates/homepage.*' },
     context: { js: 'js/app.js', css: 'css/app.css' } },
  dist: 
   { files: 
      { dist: '<%= files.pages.source %>',
        'dist/index.html': 'app/templates/homepage.*' },
     context: { js: 'js/app.js', css: 'css/app.css' } } }

Ah, so the issue is probably in the definition of the abstracted file glob files.pages.source. I can ask Lineman what the definition of this is as well:

$ lineman config files.pages.source
app/pages/**/*.*

A-ha! So all I need to do is override this glob (perhaps with an exclusion pattern for *.md files) in my application's configuration.

Use in scripting

I was careful to make sure that unadorned text would be spat out by the lineman-config command, because it can be handy when you're shell-scripting based on a specific value. For example, the Lineman Heroku buildpack will go to the trouble of installing Bundler & Sass before searching for a Gemfile in the event that the user has toggled the enableSass property to true.

The script currently does this by:

if [ `$BUILD_DIR/node_modules/.bin/lineman config enableSass` != "false" ]
then
  echo "-----> Installing bundler and sass gems"
  export GEM_HOME="$BUILD_DIR/gems"
  export GEM_PATH=$GEM_HOME
  mkdir -p $GEM_HOME
  LANG="en_US.UTF-8" gem install bundler sass
  export PATH="/app/bin:$PATH:$GEM_PATH/bin"
fi

Which is pretty neat.