#!/bin/cat
$Id: FAQ.Folders_Selection.txt,v 1.12 2022/03/22 11:12:32 gilles Exp gilles $

This documentation is also available online at
https://imapsync.lamiral.info/FAQ.d/
https://imapsync.lamiral.info/FAQ.d/FAQ.Folders_Selection.txt


=======================================================================
               Imapsync tips to select folders.
=======================================================================

Questions answered in this FAQ are:

Q. What is the default imapsync behaviour about folders?

Q. What are the options to select folders?

Q. Is it ok to use --subfolder1 and --subfolder2 to just select folders?

Q. How can I sync only one folder?

Q. What are --subscribe and --subscribed for, and how can they be used?

Q. How to exclude a folder hierarchy like "public"?

Q. How to exclude only the INBOX folder?

Q. How to exclude folders matching SPAM no matter the case, 
   aka, how to be case insensitive?

Q. How to make option --folder "MyFolder" be recursive?

Q. How to change folders names or move them elsewhere?

Now the questions again with their answers.

=======================================================================
Q. What is the default imapsync behaviour about folders?

By default, Imapsync syncs all folders, one by one, in alphanumeric order.

The IMAP protocol has a specific way to code folders names,
especially when these names use non-ascii 7bit characters.
This encoding is called utf7imap. 

Imapsync uses the same encoding as IMAP, utf7imap.

In order to well specify folders names on the command line, imapsync
prints the complete folder list of both sides at the beginning of each run.

The left column is the encoding you have to use, without the first enclosing 
square brackets [], the right column is the human utf8 view.


=======================================================================
Q. What are the options to select folders?

R. From https://imapsync.lamiral.info/README

  OPTIONS/folders

     --folder       str  : Sync this folder.
     --folder       str  : and this one, etc.
     --folderrec    str  : Sync this folder recursively.
     --folderrec    str  : and this one, etc.

     --folderfirst  str  : Sync this folder first. Ex. --folderfirst "INBOX"
     --folderfirst  str  : then this one, etc.
     --folderlast   str  : Sync this folder last. --folderlast "[Gmail]/All Mail"
     --folderlast   str  : then this one, etc.

     --nomixfolders      : Do not merge folders when host1 is case-sensitive
                           while host2 is not (like Exchange). Only the first
                           similar folder is synced. Example: with folders
                           "Sent", "SENT" and "sent" on host1, only "Sent"
                           will be synced to host2.

     --skipemptyfolders  : Empty host1 folders are not created on host2.

     --include      reg  : Sync folders matching this regular expression
     --include      reg  : or this one, etc.
                           If both --include --exclude options are used, then
                           include is done before.
     --exclude      reg  : Skips folders matching this regular expression
                           Several folders to avoid:
                            --exclude 'fold1|fold2|f3' skips fold1, fold2 and f3.
     --exclude      reg  : or this one, etc.


=======================================================================
Q. Is it ok to use --subfolder1 and --subfolder2 to just select folders?

R. No.

  If you do:
  
    imapsync ... --subfolder1 Foo --subfolder2 Foo
  
  then it ends up with all messages from Foo going to Foo/INBOX


=======================================================================
Q. How can I sync only one folder?

R. Use --folder option.

  imapsync ... --folder MyFolder

If you have more specific folders to sync just add several --folder 

  imapsync ... --folder MyFolder --folder ThisFolder --folder ThatFolder


=======================================================================
Q. What are --subscribe and --subscribed for, and how can they be used?

R. In the IMAP protocol each user can subscribe to one or more folders.
   Then one can configure his email software to just see his subscribed
   folders. That's an IMAP feature.

   Imapsync can use this imap feature to select subscribed folders
   and also subscribe to folders on host2. Here are the options:

 --subscribed        : Transfers subscribed folders.
 --subscribe         : Subscribe to the folders transferred on the
                       host2 that are subscribed on host1. On by default.
 --subscribeall      : Subscribe to the folders transferred on the
                       host2 even if they are not subscribed on host1.


=======================================================================
Q. How to exclude a folder hierarchy like "public"?

R. Use:

  --exclude "public"


=======================================================================
Q. How to exclude only the INBOX folder?

R. Use:

  imapsync ... --exclude "^INBOX$" 

A good way to see what will be done is to first use:

  imapsync ...  --exclude "^INBOX$" --justfolders --nofoldersizes --dry

=======================================================================
Q. How to exclude folders matching SPAM no matter the case, 
   aka, how to be case insensitive?

R. Use:

  imapsync ... --exclude "(?i)spam" 

A good way to see what will be done is to first use:

  imapsync ... --exclude "(?i)spam" --justfolders --nofoldersizes --dry


=======================================================================
Q. How to make option --folder "MyFolder" be recursive?

Two solutions:

R1. Use

--folderrec "MyFolder"

R2. Use --include "^MyFolder"
   Then the folder "MyFolder" and all its subfolders will be handled
   and only them.

=======================================================================
Q. How to change folders names or move them elsewhere?

R. Read the document FAQ.Folders_Mapping.txt also available at
   https://imapsync.lamiral.info/FAQ.d/FAQ.Folders_Mapping.txt

=======================================================================
=======================================================================