Adding documentation

README.md

@@ -56,25 +56,61 @@ bash-it help plugins        # shows help for installed plugins
 ## Search
 
 If you need to quickly find out which of the plugins, aliases or completions
-are available for a specific task or an environment, you can search for 
+are available for a specific framework, programming language, or an environment, you can _search_ for
 multiple terms related to the commands you use frequently.  Search will
-find and output modules with the name or description matching the terms 
+find and print out modules with the name or description matching the terms
 provided.
 
-```
-bash-it search term1 [term2] [term3]....
+#### Syntax
+
+```bash
+  bash-it search term1 [[-]term2] [[-]term3]....
 ```
 
-For example, if you are a ruby developer, you might want to enable everything 
+As an example, a ruby developer might want to enable everything
 related to the commands such as `ruby`, `rake`, `gem`, `bundler` and `rails`.
 Search command helps you find related modules, so that you can decide which
 of them you'd like to use:
 
+```bash
+❯ bash-it search ruby rake gem bundle irb rails
+      aliases:  bundler rails
+      plugins:  chruby chruby-auto ruby
+  completions:  bundler gem rake
 ```
-> bash-it search ruby rake gem bundle irb rails
-aliases     : bundler rails
-plugins     : chruby chruby-auto ruby
-completions : bundler gem rake
+
+Currently enabled modules will be shown in green.
+
+#### Search with Negations
+
+You can prefix a search term with a "-" to exclude it from the results. In the above
+example, if we wanted to hide `chruby` and `chruby-auto`, we could change the command as
+follows:
+
+```bash
+❯ bash-it search ruby rake gem bundle irb rails -chruby
+      aliases:  bundler rails
+      plugins:  ruby
+  completions:  bundler gem rake
+```
+
+#### Using Search to Enable or Disable Components
+
+By adding a `--enable` or `--disable` to the search command, you can automatically
+enable all modules that come up as a result of a search query. This could be quite
+handy if you like to enable a bunch of components related to the same topic.
+
+#### Disabling ASCII Color
+
+To remove non-printing non-ASCII characters responsible for the coloring of the
+search output, you can set environment variable `NO_COLOR`. Enabled components will
+then be shown with a checkmark:
+
+```bash
+❯ NO_COLOR=1 bash-it search ruby rake gem bundle irb rails -chruby
+      aliases  =>   ✓bundler ✓rails
+      plugins  =>   ✓ruby
+  completions  =>   bundler gem rake
 ```
 
 ## Your Custom scripts, aliases, themes, and functions

lib/search.bash

@@ -12,18 +12,28 @@
 #    Double dash indicates a command that is to be applied to the search result.
 #    At the moment only --enable and --disable are supported.
 #
-# Example:
-# ❯ bash-it search ruby rbenv rvm gem rake
-# aliases     :  bundler
-# plugins     :  chruby chruby-auto rbenv ruby rvm
-# completions :  gem rake
+# Examples:
+#    ❯ bash-it search ruby rbenv rvm gem rake
+#    aliases     :  bundler
+#    plugins     :  chruby chruby-auto rbenv ruby rvm
+#    completions :  gem rake
 
-# ❯ bash-it search ruby rbenv rvm gem rake -chruby
-# aliases     :  bundler
-# plugins     :  rbenv ruby rvm
-# completions :  gem rake
+#    ❯ bash-it search ruby rbenv rvm gem rake -chruby
+#    aliases     :  bundler
+#    plugins     :  rbenv ruby rvm
+#    completions :  gem rake
+#
+# Examples of enabling or disabling results of the search:
+#
+#    ❯ bash-it search ruby
+#    aliases  =>   bundler
+#    plugins  =>   chruby chruby-auto ruby
+#
+#    ❯ bash-it search ruby -chruby --enable
+#    aliases  =>   ✓bundler
+#    plugins  =>   ✓ruby
+#
 #
-
 _bash-it-search() {
   _about 'searches for given terms amongst bash-it plugins, aliases and completions'
   _param '1: term1'