= Bitsa

http://github.com/colbell/bitsa

{}[http://badge.fury.io/rb/bitsa]
{}[https://codeclimate.com/github/colbell/bitsa]
{}[http://inch-ci.org/github/colbell/bitsa]
{}[https://travis-ci.org/colbell/bitsa]
{}[https://github.com/colbell/bitsa/blob/master/COPYING]
{}[https://gemnasium.com/colbell/bitsa]

A command line tool written in Ruby to access your GMail/Google Apps
contacts. Designed to be used from Mutt but should be able to be used
from any email client that supports calling external programs.


== Installation

Since version 0.20 bitsa should work with both Ruby 1.8.7 and 1.9.x.

Since version 0.30 bitsa should work with Ruby 1.9.x. and above.

    gem install bitsa


== Configuration

Bitsa is configured through the configuration file
~/.bitsa_config.yml. Use your GMail (or Google Apps) email address
for the login.

    ---
    :login: myself@gmail.com
    :password: mypassword
    :cache_file_path: ~/.bitsa_cache.yml
    :auto_check: 1

The configuration file is not mandatory, you can pass in your email address
and password on the command line, see Usage.

If you have no configuration file or if cache_file_path is not specified in the
configuration file it will default to ~/.bitsa_cache.yml

If auto_check: X is greater than 0 then
whenever you run a search it will check if the cache is more than X
days old and if so will first run the update subcommand. Defaults to 1.

If you store your email password in the configuration file you should
ensue that it is only readable by you:

    chmod 0600 .bitsa_config.yml


== Usage


    $ bitsa -h

    Usage: bitsa [global-options] [subcommand] [command-opts]

    Global options are:
      --config-file, -c :   Configuration file (default: ~/.bitsa_config.yml)
       --auto-check, -a :   Autocheck interval in days. 0 to disable (default: 1)
            --login, -l :   Login
         --password, -p :   Password

    bitsa subcommands
       update: get the latest changes from Gmail
       reload: Clear all cached addresses and reload from Gmail
       search: Search for the passed string
       skel:   Write a skeleton configuration file to standard output

    Information about this program
              --version, -v:   Print version and exit
                 --help, -h:   Show this message


    To search for all contacts that contain the string rob:

        $ bitsa search rob

        Rob_Smith@example.com.au    Robert Smith
        Rob_Smith@example.com       Robert Smith
        robert@example.com          Robert Jones
        jeff@example.net            Robert Smith
        bob@robertsystems           Robert Brown

Contacts are returned as email address, the TAB character and then the
contacts name.

You can update your cache with the latest changes at any time by using
the update sub-command:

    $ bitsa update

If you want to clear your local cache and reload from GMail use the
reload sub-command:

    $ bitsa reload

=== Usage - Mutt

To use for address lookup in {Mutt}[http://www.mutt.org] put the following in your
~/.muttrc file:

    set query_command = "bitsa search '%s'"

=== Usage - Sup

To use for address lookup in {Sup}[http://sup.rubyforge.org/] put the following in your
~/.sup/hooks/extra-contact-addresses.rb file:

    require "yaml"
    ignore, contacts = YAML::load_file( ENV['HOME'] + "/.bitsa_cache.yml" )

    contacts.values.flatten.each_slice(2).map do |e,n|
      "#{e}\t#{n}"
    end

== Testing

To run the tests after cloning the repository you first need to
install the required libraries:

    bundle install

And then you can run the tests:

    rake spec

== License

Copyright (c) 2011-2015 {Colin Bell}[mailto:col@baibell.org]

Bitsa is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see {http://www.gnu.org/licenses/}[http://www.gnu.org/licenses/].

-----