README.md in config_curator-0.2.4 vs README.md in config_curator-0.3.0
- old
+ new
@@ -1,12 +1,12 @@
# Config Curator
[](https://rubygems.org/gems/config_curator)
-[](./LICENSE.txt)
+[](./LICENSE.txt)
[](https://gemnasium.com/razor-x/config_curator)
[](https://travis-ci.org/razor-x/config_curator)
-[](https://coveralls.io/r/razor-x/config_curator)
+[](https://codecov.io/github/razor-x/config_curator)
[](https://codeclimate.com/github/razor-x/config_curator)
by Evan Boyd Sosenko.
_Simple and intelligent configuration file management._
@@ -28,10 +28,28 @@
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.
+## Quick start
+
+1. Install the `config_curator` gem
+ (make sure installed gem binaries are in your PATH).
+
+2. Create a `manifest.yml` file, e.g.,
+
+ ```yaml
+ config_files:
+ - src: .config/git/config
+ ```
+
+3. Add `.config/git/config` to your project and run
+
+ ```bash
+ $ curate -v
+ ```
+
## Usage
### The `manifest.yml` file
The `manifest.yml` file is a YAML file that defines
@@ -43,30 +61,30 @@
#### Settings
Optional global Config Curator settings.
Defaults listed below.
-````yaml
+```yaml
# 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.
-````yaml
+```yaml
defaults:
# File and directory permissions.
# Empty values will not change permissions.
fmode:
dmode:
@@ -81,11 +99,11 @@
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.
@@ -107,20 +125,20 @@
Components are installed before other units.
The source will be mirrored to the destination.
**Any existing files in the destination will be lost.**
-````yaml
+```yaml
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.
@@ -128,11 +146,11 @@
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`.
-````yaml
+```yaml
config_files:
- src: .gitconfig
- src: .bundle/config
- src: bower_components/ssh-config/config
@@ -140,38 +158,38 @@
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.
-````yaml
+```yaml
symlinks:
- src: ~/Wallpaper/tux.png
dst: .config/awesome/wall.png
packages: [ awesome ]
-````
+```
### The `curate` command
Once you have prepared your manifest, simply run
-````bash
+```bash
$ curate
-````
+```
Or if you prefer more verbose feedback
-````bash
+```bash
$ curate -v
-````
+```
You can always get help with
```
$ curate help
@@ -184,16 +202,29 @@
v, [--verbose], [--no-verbose]
q, [--quiet], [--no-quiet]
[--debug], [--no-debug]
```
+#### Uninstalling units
+
+Currently all units have an uninstall method.
+Smart uninstall via `curate uninstall` is planned for an
+[upcoming release](https://github.com/razor-x/config_curator/issues/7).
+
### Scripting
Config Curator is fully scriptable for easy inclusion into other Ruby programs.
The API is well documented for this purpose
(see [Documentation](#documentation) above).
+### Plugins
+
+Plugin support is
+[planned for an upcoming release](https://github.com/razor-x/config_curator/issues/8).
+If you like Config Curator and want to write a plugin,
+please let me know!
+
## 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.
@@ -201,66 +232,67 @@
The recommend setup is to check your configuration
along with `manifest.yml` into version control.
Add this line to your application's Gemfile:
-````ruby
+```ruby
gem 'config_curator'
-````
+```
And then execute:
-````bash
+```bash
$ bundle
-````
+```
Or install it yourself as:
-````bash
+```bash
$ 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](https://rubygems.org/gems/config_curator).
-Documentation for the latest commits is hosted on
-[the RubyDoc.info project page](http://rubydoc.info/github/razor-x/config_curator/frames).
+Also checkout
+[Omniref's interactive documentation](https://www.omniref.com/ruby/gems/config_curator).
## Development and Testing
### Source Code
The [Config Curator source](https://github.com/razor-x/config_curator)
is hosted on GitHub.
To clone the project run
-````bash
+```bash
$ 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 build # Build config_curator-0.3.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-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 install # Build and install config_curator-0.3.0.gem into system gems
+rake install:local # Build and install config_curator-0.3.0.gem into system gems without network access
+rake release # Create tag v0.3.0 and build and push config_curator-0.3.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: