Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Update README, no more a work in progress.

Add documentation about polling fallback and also updating LICENSE and
author.
  • Loading branch information...
commit 7328cc69ae5cd189c7add5b83f4647c388e83f91 1 parent 19bf4d3
Thibaud Guillaume-Gentil authored
Showing with 71 additions and 41 deletions.
  1. +1 −1  LICENSE
  2. +67 −37 README.md
  3. +1 −1  lib/listen/adapter.rb
  4. +2 −2 listen.gemspec
View
2  LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2012 The listen team
+Copyright (c) 2012 Thibaud Guillaume-Gentil
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
View
104 README.md
@@ -1,20 +1,15 @@
# Listen [![Build Status](https://secure.travis-ci.org/guard/listen.png?branch=master)](http://travis-ci.org/guard/listen)
-**Work in progress...**
-
The Listen gem listens to file modifications and notifies you about the changes.
-## TODO
+## Features
-- **DONE** Add polling support
-- **DONE** Add `rb-fsevent` support
-- **DONE** Add `rb-inotify` support
-- **DONE** Add `rb-fchange` support
-- **DONE** Add checksum comparaison support for detecting consecutive file modifications made during the same second. (like Guard)
-- **DONE** Add latency option
-- **DONE** Add force-polling option
-- **DONE** Add automatic fallback to polling if system adapter doesn't work (like a DropBox folder).
-- Improve API (if needed)
+* Works everywhere.
+* OS-specific adapters (Mac, Linux and Windows) and polling.
+* Detects files modification, addidation and removal.
+* Checksum comparaison for quick modifications.
+* Threadable.
+* Well tested on all ruby environments via [travis-ci](http://travis-ci.org/guard/listen).
## Install
@@ -27,14 +22,12 @@ gem install listen
There are two ways you can use Listen.
1. call `Listen.to` with a path params, and define callbacks in a block.
-3. create a `listener` object usable in an (ARel style) chainable way.
+2. create a `listener` object usable in an (ARel style) chainable way.
Feel free to give your feeback via [Listen issues](https://github.com/guard/listener/issues)
### Block API
-#### One dir
-
``` ruby
Listen.to('dir/path/to/listen', filter: /.*\.rb/, ignore: '/ignored/path') do |modified, added, removed|
# ...
@@ -79,20 +72,6 @@ Thread.new { styles.start } # enter the run loop
Thread.new { scripts.start } # enter the run loop
```
-### Listen adapters
-
-The Listen gem has a set of adapters to notify it when there are changes.
-There are 3 OS-specific adapters to support Mac, Linux and Windows. These adapters are fast
-as they use some system-calls to implement the notifying function.
-
-There is also a polling adapter which is a cross-platform adapter and it will
-work on any system. This adapter is unfortunately slower than the rest of the adapters.
-
-The Listen gem will choose the best and working adapter for your machine automatically. If you
-want to force the use of the polling adapter, either use the `:force_polling` option
-while initializing the listener or call the `force_polling` method on your listener
-before starting it.
-
### Options
These options can be set through `Listen.to` params or via methods (see the "Object" API)
@@ -100,27 +79,78 @@ These options can be set through `Listen.to` params or via methods (see the "Obj
```ruby
:filter => /.*\.rb/, /.*\.coffee/ # Filter files to listen to via a regexps list.
# default: none
-
+
:ignore => 'path1', 'path2' # Ignore a list of paths (root directory or sub-dir)
# default: '.bundle', '.git', '.DS_Store', 'log', 'tmp', 'vendor'
-
+
:latency => 0.5 # Set the delay (**in seconds**) between checking for changes
# default: 0.1 sec (1.0 sec for polling)
-
+
:force_polling => true # Force the use of the polling adapter
# default: none
-
+
:polling_fallback_message => 'custom message' # Set a custom polling fallback message (or disable it with `false`)
# default: "WARNING: Listen fallen back to polling, learn more at https://github.com/guard/listen."
```
+## Listen adapters
+
+The Listen gem has a set of adapters to notify it when there are changes.
+There are 3 OS-specific adapters to support Mac, Linux and Windows. These adapters are fast
+as they use some system-calls to implement the notifying function.
+
+There is also a polling adapter which is a cross-platform adapter and it will
+work on any system. This adapter is unfortunately slower than the rest of the adapters.
+
+The Listen gem will choose the best and working adapter for your machine automatically. If you
+want to force the use of the polling adapter, either use the `:force_polling` option
+while initializing the listener or call the `force_polling` method on your listener
+before starting it.
+
+### Polling fallback<a id="fallback"/>
+
+When the OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter.
+Here some things to try to avoiding this fallback:
+
+* [Update your Dropbox client](http://www.dropbox.com/downloading) (if used).
+* Move or rename the listened folder.
+* Update/reboot your OS.
+
+If it still falling back, feel free to [open an issue](https://github.com/guard/listen/issues/new) (and be sure to give all details).
+
+## Development [![Dependency Status](https://gemnasium.com/guard/listen.png?branch=master)](https://gemnasium.com/guard/listen)
+
+* Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/listen/master/frames).
+* Source hosted at [GitHub](https://github.com/guard/listen).
+
+Pull requests are very welcome! Please try to follow these simple rules if applicable:
+
+* Please create a topic branch for every separate change you make.
+* Make sure your patches are well tested. All specs run with `rake spec:portability` must pass.
+* Update the [Yard](http://yardoc.org/) documentation.
+* Update the README.
+* Update the CHANGELOG for noteworthy changes.
+* Please **do not change** the version number.
+
+For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
+`#guard` (irc.freenode.net).
+
## Acknowledgment
-- [Travis Tilley (ttilley)][] for this awesome work on [fssm][] & [rb-fsevent][].
-- [Nathan Weizenbaum (nex3)][] for [rb-inotify][], a thorough inotify wrapper.
-- [stereobooster][] for [rb-fchange][], windows support wouldn't exist without him.
-- [Yehuda Katz (wycats)][] for [vigilo][], that has been a great source of inspiration.
+* [Travis Tilley (ttilley)][] for this awesome work on [fssm][] & [rb-fsevent][].
+* [Nathan Weizenbaum (nex3)][] for [rb-inotify][], a thorough inotify wrapper.
+* [stereobooster][] for [rb-fchange][], windows support wouldn't exist without him.
+* [Yehuda Katz (wycats)][] for [vigilo][], that has been a great source of inspiration.
+
+## Author
+
+[Thibaud Guillaume-Gentil][] ([@thibaudgg](http://twitter.com/thibaudgg))
+
+## Contributors
+
+[https://github.com/guard/listen/contributors](https://github.com/guard/listen/contributors)
+[Thibaud Guillaume-Gentil]: https://github.com/thibaudgg
[Travis Tilley (ttilley)]: https://github.com/ttilley
[fssm]: https://github.com/ttilley/fssm
[rb-fsevent]: https://github.com/thibaudgg/rb-fsevent
View
2  lib/listen/adapter.rb
@@ -7,7 +7,7 @@ class Adapter
# The default delay between checking for changes.
DEFAULT_LATENCY = 0.1
# The default warning message when falling back to polling adapter.
- POLLING_FALLBACK_MESSAGE = "WARNING: Listen fallen back to polling, learn more at https://github.com/guard/listen."
+ POLLING_FALLBACK_MESSAGE = "WARNING: Listen fallen back to polling, learn more at https://github.com/guard/listen#fallback."
# Select the appropriate adapter implementation for the
# current OS and initializes it.
View
4 listen.gemspec
@@ -6,8 +6,8 @@ Gem::Specification.new do |s|
s.name = 'listen'
s.version = Listen::VERSION
s.platform = Gem::Platform::RUBY
- s.authors = ['Thibaud Guillaume-Gentil', 'Michael Kessler']
- s.email = ['thibaud@thibaud.me', 'michi@netzpiraten.ch']
+ s.authors = ['Thibaud Guillaume-Gentil']
+ s.email = ['thibaud@thibaud.me']
s.homepage = 'https://github.com/guard/listen'
s.summary = 'Listen to file modifications'
s.description = 'The Listen gem listens to file modifications and notifies you about the changes. Works everywhere!'
Please sign in to comment.
Something went wrong with that request. Please try again.