Bitsa¶ ↑

github.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 <s>:   Configuration file (default: ~/.bitsa_config.yml)
   --auto-check, -a <i>:   Autocheck interval in days. 0 to disable (default: 1)
        --login, -l <s>:   Login
     --password, -p <s>:   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 put the following in your ~/.muttrc file:

set query_command = "bitsa search '%s'"

Usage - Sup¶ ↑

To use for address lookup in Sup 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¶ ↑

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 www.gnu.org/licenses/.

bitsa

Development

Runtime