.. -*- coding: utf-8 -*-
.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project

======
README
======

Description
===========

OfflineIMAP is a tool to simplify your e-mail reading. With OfflineIMAP, you can
read the same mailbox from multiple computers. You get a current copy of your
messages on each computer, and changes you make one place will be visible on all
other systems. For instance, you can delete a message on your home computer, and
it will appear deleted on your work computer as well. OfflineIMAP is also useful
if you want to use a mail reader that does not have IMAP support, has poor IMAP
support, or does not provide disconnected operation.

OfflineIMAP does not require additional python dependencies (although python-sqlite is strongly recommended)

OfflineIMAP is a Free Software project licensed under the GNU General Public
License. You can download it for free, and you can modify it. In fact, you are
encouraged to contribute to OfflineIMAP, and doing so is fast and easy.

Documentation
=============

The documentation (in .rst format) is included in the `docs`
directory. Read it directly or generate nicer html (python-sphinx
needed) or the man page (python-docutils needed) via::

    'make doc' (user docs), 'make man' (man page only) or 'make' (both)

    (`make html` will simply create html versions of all *.rst files in /docs)

The resulting user documentation will be in `docs/html`. The full user
docs are also at: `<http://docs.offlineimap.org>`_. Please see there for
detailed information on how to install and configure OfflineImap.

Quick Start
===========

First, install OfflineIMAP. See docs/INSTALL.rst or read
`<http://docs.offlineimap.org/en/latest/INSTALL.html>`_. 
(hint: `sudo python setup.py install`)

Second, set up your configuration file and run it! The distribution
includes offlineimap.conf.minimal (Debian users may find this at
``/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal``) that
provides you with the bare minimum of setting up OfflineIMAP.  You can
simply copy this file into your home directory and name it
``.offlineimaprc``.  A command such as ``cp offlineimap.conf.minimal
~/.offlineimaprc`` will do it.  Or, if you prefer, you can just copy
this text to ``~/.offlineimaprc``::

  [general]
  accounts = Test

  [Account Test]
  localrepository = Local
  remoterepository = Remote

  [Repository Local]
  type = Maildir
  localfolders = ~/Test

  [Repository Remote]
  type = IMAP
  remotehost = examplehost
  remoteuser = jgoerzen


Now, edit the ``~/.offlineimaprc`` file with your favorite editor.  All you have
to do is specify a directory for your folders to be in (on the localfolders
line), the host name of your IMAP server (on the remotehost line), and your
login name on the remote (on the remoteuser line).  That's it!

To run OfflineIMAP, you just have to say `offlineimap` ― it will fire
up, ask you for a login password if necessary, synchronize your
folders, and exit.  See?

You can just throw away the rest of the finely-crafted,
perfectly-honed user manual!  Of course, if you want to see how you can
make OfflineIMAP FIVE TIMES FASTER FOR JUST $19.95 (err, well, $0),
you have to read on our full user documentation and peruse the sample
offlineimap.conf (which includes all available options) for further
tweaks!


Mailing list
============

The user discussion, development and all exciting stuff take place in the
`mailing list`_. You do *NOT* need to subscribe to send emails.


Reporting bugs and contributions
================================

Bugs
----

Bugs, issues and contributions should be reported to the `mailing list`_.

========
Examples
========

Here are some example configurations for various situations.  Please e-mail any
other examples you have that may be useful to me.


Multiple Accounts with Mutt
===========================

This example shows you how to set up OfflineIMAP to synchronize multiple
accounts with the mutt mail reader.

Start by creating a directory to hold your folders by running ``mkdir ~/Mail``.
Then, in your ``~/.offlineimaprc``, specify::

  accounts = Personal, Work


Make sure that you have both an [Account Personal] and an [Account Work]
section.  The local repository for each account must have different localfolder
path names.  Also, make sure to enable [mbnames].

In each local repository section, write something like this::

	localfolders = ~/Mail/Personal


Finally, add these lines to your ``~/.muttrc``::

  source ~/path-to-mbnames-muttrc-mailboxes
  folder-hook Personal set from="youremail@personal.com"
  folder-hook Work set from="youremail@work.com"
  set mbox_type=Maildir
  set folder=$HOME/Mail
  spoolfile=+Personal/INBOX


That's it!


UW-IMAPD and References
=======================

Some users with a UW-IMAPD server need to use OfflineIMAP's "reference" feature
to get at their mailboxes, specifying a reference of ``~/Mail`` or ``#mh/``
depending on the configuration.  The below configuration from (originally from
docwhat@gerf.org) shows using a reference of Mail, a nametrans that strips the
leading Mail/ off incoming folder names, and a folderfilter that limits the
folders synced to just three::

  [Account Gerf]
  localrepository = GerfLocal
  remoterepository = GerfRemote

  [Repository GerfLocal]
  type = Maildir
  localfolders = ~/Mail

  [Repository GerfRemote]
  type = IMAP
  remotehost = gerf.org
  ssl = yes
  remoteuser = docwhat
  reference = Mail
  # Trims off the preceeding Mail on all the folder names.
  nametrans = lambda foldername: \
    re.sub('^Mail/', '', foldername)
  # Yeah, you have to mention the Mail dir, even though it
  # would seem intuitive that reference would trim it.
  folderfilter = lambda foldername: foldername in [
    'Mail/INBOX',
    'Mail/list/zaurus-general',
    'Mail/list/zaurus-dev',
  ]
  maxconnections = 1
  holdconnectionopen = no


pythonfile Configuration File Option
====================================

You can have OfflineIMAP load up a Python file before evaluating the
configuration file options that are Python expressions.  This example is based
on one supplied by Tommi Virtanen for this feature.


In ~/.offlineimaprc, he adds these options::

  [general]
  pythonfile=~/.offlineimap.py
  [Repository foo]
  foldersort=mycmp

Then, the ~/.offlineimap.py file will contain::

  prioritized = ['INBOX', 'personal', 'announce', 'list']

  def mycmp(x, y):
    for prefix in prioritized:
      xsw = x.startswith(prefix)
      ysw = y.startswith(prefix)
      if xsw and ysw:
        return cmp(x, y)
      elif xsw:
        return -1
      elif ysw:
        return +1
    return cmp(x, y)

  def test_mycmp():
    import os, os.path
    folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))
    folders.sort(mycmp)
    print folders


This code snippet illustrates how the foldersort option can be customized with a
Python function from the pythonfile to always synchronize certain folders first.


Signals
=======

OfflineIMAP writes its current PID into ``~/.offlineimap/pid`` when it is
running.  It is not guaranteed that this file will not exist when OfflineIMAP is
not running.

<!-- not done yet

  You can send SIGINT to OfflineIMAP using this file to kill it.  SIGUSR1 will
  force an immediate resync of all accounts.  This will be ignored for all
  accounts for which a resync is already in progress.

-->