README.md in multi_sync-0.0.2 vs README.md in multi_sync-0.0.3
- old
+ new
@@ -1,10 +1,10 @@
# MultiSync
:heavy_exclamation_mark: **currently a functioning WIP thats not quite finished yet but its close!** :heavy_exclamation_mark:
-A flexible synchronisation library for your assets.
+Flexible synchronisation for your assets.
`MultiSync` stands on the shoulders of giants. On one side is [Celluloid](http://celluloid.io) allowing for the synchronisation of assets to be highly parallel. On the other is [Fog::Storage](https://github.com/fog/fog) allowing `MulitSync` to support [various well known storage services](#storage-services).
What that means is when your configuring `MultiSync` your creating various pools of workers which then distrubute the work behind synchronising your assets. Meaning that when your site has thousands of files, you get alot more :boom: for your :dollar: in less :alarm_clock:.
@@ -13,11 +13,11 @@
Listed below are examples of how to get setup and started.
## Installation
```ruby
-gem 'multi_sync', '~> 0.0.1'
+gem 'multi_sync', '~> 0.0.2'
```
```ruby
require 'multi_sync'
@@ -41,107 +41,135 @@
`MultiSync` in its simplist form consists of three objects. `sources`, `resources` and `targets`. A `source` defines how and where a list of files (or `resources`) can be found. A `resource` represents a file from a `source` with additional properties (such as how to compare them). A `target` is destination which `resources` can be synchronised against.
### Source
-A source takes two arguments. The first is a `name` to reference this source by and the second is a `Hash` of configuration detailed below.
+All `source`s takes one argument which is a `Hash` of configuration detailed below. There are currently two type's of `source`s which are
+#### Source Types
+
+- `local_source` - Uses all files within the `source_dir`
+- `manifest_source` - Tries to find a `Sprocket`s `manifest.{yml,json}` file within the `source_dir`
+
| Key | Type | Default | Description |
| :-- | :--- | :------ | :---------- |
-| `type` | `Symbol` | `nil` | The `type` of source this is (`:local`, `:manifest`) |
-| `source_dir` | `Pathname`, `String` | `nil` | The location this source should use |
-| `resource_options` | `Hash` | `nil` | A hash of options for this source`s resources |
-| `targets` | `Symbol`, `Array` | All targets | The target(s) this source should sync against |
+| `source_dir` | `Pathname`, `String` | `nil` | The location this `source` should use |
+| `resource_options` | `Hash` | `{}` | A hash of options for this `source`'s resources |
+| `targets` | `Symbol`, `Array` | All targets | The `target`(s) this `source` should sync against |
| `include` | `String` ([shell glob](http://www.ruby-doc.org/core-2.1.1/Dir.html#method-c-glob)) | `**/*` | A shell globe to use for inclusion |
| `exclude` | `String` ([shell glob](http://www.ruby-doc.org/core-2.1.1/Dir.html#method-c-glob)) | `nil` | A shell globe to use for exclusion |
___
```ruby
-# A source named ':build' which is ':local' and will use all files within '../build'
-source :build, {
- type: :local,
+# A `local` `source` which will use all files within '../build'
+local_source({
source_dir: '../build'
-}
+})
```
___
```ruby
-# A source named ':assets' which will use a Sprockets ':manifest' within '../public/assets'
-source :assets, {
- type: :manifest,
+# A `manifest` `source` which will use a Sprockets ':manifest' within '../public/assets'
+manifest_source({
source_dir: '../public/assets'
-}
+})
```
___
```ruby
-# A source named ':video_assets' which is `:local' and will use all files
-# within '../build' including only 'mp4, mpg, mov'
-source :video_assets, {
- type: :local,
+# A `local` `source` which will use all files
+# within '../build' including only 'mp4, mpg, mov' files
+local_source({
source_dir: '../build',
include: '*.{mp4,mpg,mov}'
-}
+})
```
___
```ruby
-# A source named ':no_images' which is `:local' and will use all files
-# within '../build' excluding any 'jpg, gif, png'
-source :no_images, {
- type: :local,
+# A `local` `source` which will use all files
+# within '../build' excluding any 'jpg, gif, png' files
+local_source({
source_dir: '../build',
exclude: '*.{jpg,gif,png}'
-}
+})
```
___
```ruby
-# A source named ':www' which will use a Sprockets ':manifest'
-# within '../public/assets' excluding any 'jpg, gif, png' files
-# and only synchronising with a target named `:www`
-source :www, {
- type: :manifest,
- source_dir: '../public/assets',
- exclude: '*.{jpg,gif,png}',
- targets: :www
-}
-```
-___
-
-```ruby
-# A source named ':image_assets' which will use a Sprockets ':manifest'
+# A `manifest` `source` which will use use a Sprockets `manifest`
# within '../public/assets' including only 'jpg, gif, png' files
-# which sets `cache_control` and `expires` headers and
-# synchronises with the target `:images`
-source :image_assets, {
- type: :manifest,
+# which sets `cache_control` and `expires` headers
+manifest_source({
source_dir: '../public/assets',
include: '*.{jpg,gif,png}',
resource_options: {
cache_control: 'public, max-age=31557600',
expires: CGI.rfc1123_date(Time.now + 31557600)
- },
- targets: :images
-}
+ }
+})
```
### Target
+All `target`s takes one argument which is a `Hash` of configuration detailed below. There is currently only one `target` type which is:
+
+#### Target Types
+
+- `aws_target` - Synchronises to `aws` (`S3`)
+
+| Key | Type | Default | Description |
+| :-- | :--- | :------ | :---------- |
+| `target_dir` | `Pathname`, `String` | `nil` | the name of the `target`'s directory (eg s3 bucket name) |
+| `destination_dir` | `Pathname`, `String` | `nil` | the name of the `target` destination's directory (eg folder within target) |
+| `credentials` | `Hash` | inherits [Fog Credentials](https://github.com/karlfreeman/multi_sync#fog-credentials-support) | credentionals needed by [Fog](http://fog.io) |
+___
+
```ruby
-...
+# An `aws` `target` which will sync to the root of a bucket named 's3-bucket-name'
+# in region 'us-east-1', with access_key_id 'xxx', and secret_access_key 'xxx'
+aws_target({
+ target_dir: 's3-bucket-name'
+ credentials: {
+ region: 'us-east-1',
+ aws_access_key_id: 'xxx',
+ aws_secret_access_key: 'xxx'
+ }
+})
```
+___
+```ruby
+# An `aws` `target` which will sync to a bucket named 's3-bucket-name'
+# using credentials sourced from Fog's credentials (.fog or FOG_RC)
+aws_target({
+ target_dir: 's3-bucket-name'
+})
+```
+___
+```ruby
+# An `aws` `target` which will sync to a bucket named 's3-bucket-name'
+# within a directory named 'directory-within-s3'
+# in region 'us-east-1', with access_key_id 'xxx', and secret_access_key 'xxx'
+aws_target({
+ target_dir: 's3-bucket-name'
+ destination_dir: 'directory-within-s3'
+ credentials: {
+ region: 'us-east-1',
+ aws_access_key_id: 'xxx',
+ aws_secret_access_key: 'xxx'
+ }
+})
+```
+
## Supported Libraries
-- [Rails](https://github.com/karlfreeman/multi_sync/wiki/rails)
+- [Rails](https://github.com/karlfreeman/multi_sync-rails)
- Sinatra (WIP)
-- Middleman (WIP)
+- [Middleman](https://github.com/karlfreeman/multi_sync-middleman)
- Jekyll (WIP)
- Nanoc (WIP)
-- [POR](https://github.com/karlfreeman/multi_sync/wiki/por)
-- Rake (WIP)
## Badges
[][gem]
[][travis]