From 5318af606e4ebd0906cf3c9cc5745a6dd2b150e3 Mon Sep 17 00:00:00 2001 From: Abdo Roig-Maranges Date: Tue, 10 Feb 2015 11:24:59 +0100 Subject: [PATCH] docs: expand documentation of the gmail labels syncing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Suggest that this works well together with email indexing. - Warn about modifying the labelsheader after a sync. - In the example replace X-Gmail-Keywords by X-Keywords. I think this is misleading, since no email client will pick up X-Gmail-Keywords, while X-Keywords (the default) is recognized by some. - add paragraph explaining special gmail labels. Merge-request-from: Abdó Roig-Maranges Signed-off-by: Nicolas Sebrecht --- docs/MANUAL.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/MANUAL.rst b/docs/MANUAL.rst index 16af514..7fc355a 100644 --- a/docs/MANUAL.rst +++ b/docs/MANUAL.rst @@ -450,11 +450,17 @@ Sync from Gmail to a local Maildir with labels This is an example of a setup where GMail gets synced with a local Maildir. It also keeps track of GMail labels, that get embedded into the messages -under the header configured in labelsheader, and syncs them back and forth -the same way as flags. -The header used for the labels may need to be set according to the email -client used. -Some choices that may be recognized by email clients are `X-Keywords` or `X-Labels`. +under the header configured in the labelsheader setting, and syncs them back +and forth the same way as flags. This is particularly useful with an email +client that indexes your email and recognizes the labels header, so that you +can sync a single "All Mail" folder, and navigate your email via searches. + +The header used to store the labels depends on the email client you plan to use. +Some choices that may be recognized by email clients are X-Keywords +(the default) or X-Labels. Note that if you need to change the label header +after the labels have already been synced, you will have to change the header +manually on all messages, otherwise offlineimap will not pick up the labels under +the old header. The first time OfflineIMAP runs with synclabels enabled on a large repository it may take some time as the labels are read / embedded on every message. @@ -466,9 +472,9 @@ much faster:: remoterepository = Gmailserver-mine synclabels = yes # This header is where labels go. Usually you will be fine - # with default value, but in case you want it different, - # here we go: - labelsheader = X-GMail-Keywords + # with default value (X-Keywords), but in case you want it + # different, here we go: + labelsheader = X-Keywords [Repository Gmailserver-mine] #This is the remote repository @@ -480,6 +486,14 @@ much faster:: #This is the 'local' repository type = GmailMaildir +There are some labels, that gmail treats in a special way. All internal gmail +labels start with "\\". Those labels include: \\Drafts, \\Important, \\Inbox, +\\Sent, \\Junk, \\Flagged, \\Trash. You can add and remove those labels +locally, and when synced, will have special actions on the gmail side. For instance, +adding the label \Trash to an email will move it to the trash, and be permanantly +deleted after some time. This is relevant, since gmail's IMAP prevents from removing +messages from the "All Mail" folder the usual way. + Selecting only a few folders to sync ------------------------------------