Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Simple and intelligent configuration file management.
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib
spec
.editorconfig
.gitignore
.rspec
.rubocop.yml
.travis.yml
.yardopts
CHANGELOG.md
Gemfile
Guardfile
LICENSE.txt
README.md
Rakefile
config_curator.gemspec

README.md

Config Curator

Gem Version MIT License Dependency Status Build Status Coverage Status Code Climate

by Evan Boyd Sosenko.

Simple and intelligent configuration file management.

Description

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.

Usage

The manifest.yml file

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.

Settings

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.
package_tool:

defaults

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: []

Units

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 entire directories

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 ]
Config files are copied individually

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

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 ]

The curate command

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]

Scripting

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

Installation

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

Documentation

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. Documentation for the latest commits is hosted on the RubyDoc.info project page.

Development and Testing

Source Code

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

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

Rake

Run rake -T to see all Rake tasks.

rake all                   # Run all tasks
rake build                 # Build config_curator-0.0.0.gem into the pkg directory
rake bump:current          # Show current gem version
rake bump:major            # Bump major part of gem version
rake bump:minor            # Bump minor part of gem version
rake bump:patch            # Bump patch part of gem version
rake bump:pre              # 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-0.0.0.gem into system gems
rake release               # Create tag v0.0.0 and build and push config_curator-0.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

Guard tasks have been separated into the following groups:

  • doc
  • lint
  • unit

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

Contributing

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.

License

Config Curator is licensed under the MIT license.

Warranty

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.

Something went wrong with that request. Please try again.