README.md in hieracles-0.0.1 vs README.md in hieracles-0.0.2
- old
+ new
@@ -1,19 +1,104 @@
Hieracles
================
+[](http://rubygems.org/gems/hieracles)
+[](https://rubygems.org/gems/hieracles)
[](https://travis-ci.org/Gandi/hieracles)
[](https://coveralls.io/r/Gandi/hieracles?branch=master)
[](https://gemnasium.com/Gandi/hieracles)
[](https://codeclimate.com/github/Gandi/hieracles)
Hieracles is a command-line tool for analysis and deep examination of [Hiera][hiera] paramaters in a [Puppet][puppet] setup. It's used internally at [Gandi][gandi] and its first incarnation is strongly tied to Gandi puppet architecture. But Hieracles tends to become, in time, a generic Hiera overlay visualisation tool.
+Prerequisite
+---------------
+
+There are many ways to setup puppet and use hiera. This tool is designed to match a certain kind of setup, including:
+
+- an [external node classifier (ENC)][enc]
+- a yaml hiera datastore
+- classes that only contains includes and no code
+- local availability of a hierafile
+
+As the development is going on, more generic options will be provided, but for now, we mainly make it robust to fit the context we have.
+
+
Install
-----------
-At this stage, it's to early to even think about installing anything. The internal code from Gandi is still in progress of transition towards total freedom.
+At this stage, it's to early to even think about installing anything. The internal code from Gandi is still in progress of transition towards total freedom and generic usage.
+Despite this warning, you can
+
+ gem install hieracles
+
+or add in your Gemfile:
+
+ gem 'hieracles'
+
+
+Configuration
+----------------
+At first launch it will create a configuration file in `~/.config/hieracles/config.yml`
+
+Configuration variables are:
+
+- classpath
+- modulepath
+- basepath
+- encpath
+- hierafile
+- format
+
+For an example setup you can check in `spec/files`.
+
+Usage
+-------------
+
+
+ Usage: hc <fqdn> <command> [extra_args]
+
+ Available commands:
+ info provides the farm, datacenter, country
+ associated to the given fqdn
+ files list all files containing params affecting this fqdn
+ (in more than commons)
+ paths list all file paths for files with params
+ modules list modules included in the farm where the node is
+ params list params for the node matching the fqdn
+ An extra filter string can be added to limit the list
+ use ruby regexp without the enclosing slashes
+ eg. hc <fqdn> params postfix.*version
+ eg. hc <fqdn> params '^postfix'
+ eg. hc <fqdn> params 'version$'
+ allparams same as params but including the common.yaml params (huge)
+ Also accepts a search string
+
+ Extra args:
+ -f <plain|console|csv|yaml|rawyaml> default console
+ -p extraparam=what;anotherparam=this
+ -c <configfile>
+ -h <hierafile>
+ -b <basepath> default ./
+ -e <encdir>
+
+Completion
+-------------
+There is a simple zsh completion file in `tools/completion`.
+
+If you use [oh-my-zsh][omz] put it in `~/.oh-my-zsh/completions`
+
+ wget -O ~/.oh-my-zsh/completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/_hc
+ echo 'compdef _hc hc "bundle exec hc"' >> ~/.zshrc
+
+Otherwise
+
+ mkdir ~/.zsh-completions
+ wget -O ~/.zsh-completions/_hc https://raw.githubusercontent.com/Gandi/hieracles/master/tools/completion/_hc
+ echo 'fpath=(~/.zsh-completions $fpath)' >> ~/.zshrc
+ echo 'compdef _hc hc "bundle exec hc"' >> ~/.zshrc
+
Authors
-----------
Hieracles original code is writen by [@mose](https://github.com/mose).
License
@@ -26,5 +111,7 @@
[puppet]: https://github.com/puppetlabs/puppet
[hiera]: https://github.com/puppetlabs/hiera
[gandi]: https://gandi.net
+[enc]: https://docs.puppetlabs.com/guides/external_nodes.html
+[omz]: https://github.com/robbyrussell/oh-my-zsh