Adding documentation

README.md

@@ -56,27 +56,63 @@ 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-it search ruby rake gem bundle irb rails
+```bash
+❯ 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
 
 For custom scripts, and aliases, just create the following files (they'll be ignored by the git repo):

lib/search.bash

@@ -12,7 +12,7 @@
 #    Double dash indicates a command that is to be applied to the search result.
 #    At the moment only --enable and --disable are supported.
 #
-# Example:
+# Examples:
 #    ❯ bash-it search ruby rbenv rvm gem rake
 #    aliases     :  bundler
 #    plugins     :  chruby chruby-auto rbenv ruby rvm
@@ -23,7 +23,17 @@
 #    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'