Config Curator

by Evan Boyd Sosenko.

Simple and intelligent configuration file management.

📢 Version 1 is the first and last stable release.

🎉 Config Curator has been rewritten from scratch in Node.js: https://github.com/rxrc/curator. Users are encouraged to use the Node.js version which is much faster, has zero dependencies, and provides an improved feature set with a similar manifest format.

Config Curator is a flexible configuration and dotfile manager. Simply define what to manage in manifest.yml, then run curate to install and update your configuration units.

Currently, Config Curator supports installing directories, files, and symbolic links. It also handles setting other properties such as permissions and ownership. Additionally, configuration units can be installed per-host or only if certain packages are installed.

Config Curator is written to be extensible: each type of configuration unit, e.g., file, directory, symbolic link, etc., is actually a subclass of the more generic Unit type. Other types can be added simply by adding more subclasses.

1. Install the config_curator gem (make sure installed gem binaries are in your PATH).

2. Create a manifest.yml file, e.g.,

config_files:
  - src: .config/git/config

3. Add .config/git/config to your project and run

$ curate -v

The manifest.yml file is a YAML file that defines the configuration units to install.

Each key is either a global setting, default, or a unit type: components, config_files, or symlinks.

Optional global Config Curator settings. Defaults listed below.

# All units installed relative to the root.
root: "~/"

# Package tool to use.
# Will automatically detect if not explicitly set.
# Available tools: pacman, dpkg, pkgng, brew.
package_tool:

Optional key that sets the default attribute values for each unit.

Any per-unit attribute will override the value here.

Any attribute not set here will use the Config Curator defined defaults below.

defaults:
  # File and directory permissions.
  # Empty values will not change permissions.
  fmode:
  dmode:

  # File and directory owner and group.
  # Empty values will not change ownership.
  owner:
  group:

  # Hosts to install this unit on.
  # Empty array will install on all hosts.
  hosts: []

  # Only install this unit if packages are present.
  # Empty array will not check for any packages.
  packages: []

  # Default backend to use for filesystem operations.
  # Only affects components.
  # Choices: :stdlib or :rsync.
  # Empty will autoselect rsync if available and fallback to stdlib otherwise.
  backend:

Each unit must have a src which defines the source file or directory.

You may give a dst to override the install location. Otherwise the destination will mimic the source path relative to the root path. This is required for symlinks.

You can define an array of hosts to control what hostnames the unit will install on. Similarly you can give a list of packages that must be present to install the unit. You can also use any other attribute in the defaults key listed in the previous section.

Best to see some examples. Note in the examples below how some units are installed from the bower_components directory: external configuration is thus managed as a Bower dependency and installed using curate. You can always visit my dotfiles for a real-world example.

Components are installed before other units.

The source will be mirrored to the destination. Any existing files in the destination will be lost.

components:
  - src: .config/terminator

  - src: bower_components/tmuxinator-profiles
    dst: .tmuxinator
    fmode: 640
    dmode: 0750
    packages: [ tmux ]

Files are installed after components.

Subdirectories are created as needed.

In this example, the files .tmux.conf and .tmux.baz.conf both exist: the first will be installed on hosts foo and bar, while the second will be installed on host baz.

config_files:
  - src: .gitconfig
  - src: .bundle/config

  - src: bower_components/ssh-config/config
    dst: .ssh/config
    fmode: 600
    dmode: 0700

  - src: .tmux.conf
    hosts: [ foo, bar, baz ]

Symlinks create a symbolic link to the src at the dst.

They are installed last.

symlinks:
  - src: ~/Wallpaper/tux.png
    dst: .config/awesome/wall.png
    packages: [ awesome ]

Once you have prepared your manifest, simply run

$ curate

Or if you prefer more verbose feedback

$ curate -v

You can always get help with

$ curate help

Commands:
  curate help [COMMAND]  # Describe available commands or one specific command
  curate install         # Installs all units in collection.

Options:
  v, [--verbose], [--no-verbose]
  q, [--quiet], [--no-quiet]
      [--debug], [--no-debug]

Config Curator is fully scriptable for easy inclusion into other Ruby programs. The API is well documented for this purpose (see Documentation above).

You can install the gem either with Bundler or directly. Bundler is preferred, however the direct method may be convenient when initially bootstrapping a system with an initial configuration.

The recommend setup is to check your configuration along with manifest.yml into version control.

Add this line to your application's Gemfile:

gem 'config_curator'

And then execute:

$ bundle

Or install it yourself as:

$ gem install config_curator

The primary documentation for Config Curator is this README and the YARD source documentation.

YARD documentation for all gem versions is hosted on the Config Curator gem page. Also checkout Omniref's interactive documentation.

The Config Curator source is hosted on GitHub. To clone the project run

$ git clone https://github.com/razor-x/config_curator.git

Run rake -T to see all Rake tasks.

rake all                   # Run all tasks
rake build                 # Build config_curator-1.0.0.gem into the pkg directory
rake bump:current[tag]     # Show current gem version
rake bump:major[tag]       # Bump major part of gem version
rake bump:minor[tag]       # Bump minor part of gem version
rake bump:patch[tag]       # Bump patch part of gem version
rake bump:pre[tag]         # Bump pre part of gem version
rake bump:set              # Sets the version number using the VERSION environment variable
rake install               # Build and install config_curator-1.0.0.gem into system gems
rake install:local         # Build and install config_curator-1.0.0.gem into system gems without network access
rake release               # Create tag v1.0.0 and build and push config_curator-1.0.0.gem to Rubygems
rake rubocop               # Run RuboCop
rake rubocop:auto_correct  # Auto-correct RuboCop offenses
rake spec                  # Run RSpec code examples
rake yard                  # Generate YARD Documentation

Guard tasks have been separated into the following groups:

• doc
• lint
• unit

By default, Guard will generate documentation, lint, and run unit tests.

Please submit and comment on bug reports and feature requests.

To submit a patch:

1. Fork it (https://github.com/razor-x/config_curator/fork).
2. Create your feature branch (git checkout -b my-new-feature).
3. Make changes. Write and run tests.
4. Commit your changes (git commit -am 'Add some feature').
5. Push to the branch (git push origin my-new-feature).
6. Create a new Pull Request.

Config Curator is licensed under the MIT license.

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holder or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.