Provided by: isync_1.3.0-2_amd64 bug


       mbsync - synchronize IMAP4 and Maildir mailboxes


       mbsync [options ...] {{channel[:box[{,|\n}...]]|group} ...|-a}


       mbsync  is  a command line application which synchronizes mailboxes; currently Maildir and
       IMAP4 mailboxes are supported.  New messages, message deletions and flag  changes  can  be
       propagated both ways; the operation set can be selected in a fine-grained manner.
       Synchronization  is  based  on  unique  message  identifiers  (UIDs), so no identification
       conflicts can occur  (unlike  with  some  other  mail  synchronizers).   OTOH,  mbsync  is
       susceptible  to  UID  validity  changes  (but  will  recover  just  fine  if the change is
       unfounded).  Synchronization state is kept in one local text file per mailbox pair;  these
       files are protected against concurrent mbsync processes.  Mailboxes can be safely modified
       while mbsync operates (see INHERENT PROBLEMS  below  for  a  minor  exception).   Multiple
       replicas of each mailbox can be maintained.


       -c, --config file
              Read  configuration  from  file.   By  default,  the  configuration  is  read  from

       -a, --all
              Select all configured channels. Any channel/group  specifications  on  the  command
              line are ignored.

       -l, --list
              Don't  synchronize  anything,  but  list all mailboxes in the selected channels and

       -C[m][s], --create[-master|-slave]
              Override any Create options from the config file. See below.

       -R[m][s], --remove[-master|-slave]
              Override any Remove options from the config file. See below.

       -X[m][s], --expunge[-master|-slave]
              Override any Expunge options from the config file. See below.

       {-n|-N|-d|-f|-0|-F}, {--new|--renew|--delete|--flags|--noop|--full}
       {-L|-H}[n][N][d][f], {--pull|--push}[-new|-renew|-delete|-flags]

              Override any Sync options from the config file. See below.

       -h, --help
              Display a summary of command line options.

       -v, --version
              Display version information.

       -V, --verbose
              Enable verbose mode, which displays what is currently happening.

       -D[C][d|D][m][M][n|N][s]],    --debug[-crash|-driver|-driver-all|-maildir|-main|-net|-net-
              Enable debugging categories:
                  C, crash - use built-in crash handler
                  d, driver - print driver calls (metadata only)
                  D, driver-all - print driver calls (including messages)
                  m, maildir - print maildir debug info
                  M, main - print main debug info
                  n, net - print network traffic (protocol only)
                  N, net-all - print network traffic (including payloads)
                  s, sync - print synchronization debug info
              All  categories  except  crash  implictly  enable  verbose  mode.  Without category
              specification, all categories except net-all are enabled.

       -q, --quiet
              Suppress progress counters (this is implicit if stdout is no TTY, or any  debugging
              categories are enabled) and notices.  If specified twice, suppress warning messages
              as well.


       The configuration file is mandatory; mbsync will not run without it.  Lines starting  with
       a  hash  mark (#) are comments and are ignored entirely.  Configuration items are keywords
       followed by one or more arguments; arguments containing spaces must be enclosed in  double
       quotes  ("), and literal double quotes and backslashes (\) must be backslash-escaped.  All
       keywords (including  those  used  as  arguments)  are  case-insensitive.   Bash-like  home
       directory  expansion using the tilde (~) is supported in all options which represent local
       paths.  There are a few global options, the rest applies to particular sections.  Sections
       are  started  by  a  section  keyword  and are terminated by an empty line or end of file.
       Every section defines an object with an identifier unique within that object class.

       There are two basic object classes: Stores and Channels. A Store defines a  collection  of
       mailboxes;  basically  a  folder,  either local or remote.  A Channel connects two Stores,
       describing the way the two are synchronized.
       There are two auxiliary object classes: Accounts and  Groups.  An  Account  describes  the
       connection  part  of  remote Stores, so a server connection can be shared between multiple
       Stores. A Group aggregates multiple Channels to save typing on the command line.

       File system locations (in particular, Path  and  Inbox)  use  the  Store's  internal  path
       separators, which may be slashes, periods, etc., or even combinations thereof.
       Mailbox  names,  OTOH,  always  use canonical path separators, which are Unix-like forward

   All Stores
       These options can be used in all supported Store types.
       In this context, the term "remote" describes the second Store within a  Channel,  and  not
       necessarily a remote server.
       The  special mailbox INBOX exists in every Store; its physical location in the file system
       is Store type specific.

       Path path
              The location of the Store in the (server's) file system.  If this  is  no  absolute
              path,  the reference point is Store type specific.  This string is prepended to the
              mailbox names addressed in this Store, but is not considered part of them; this  is
              important  for Patterns in the Channels section.  Note that you must append a slash
              if you want to specify an entire directory.  (Default: none)

       MaxSize size[k|m][b]
              Messages larger than that will not be propagated into this Store.  This  is  useful
              for  weeding  out  messages with large attachments.  K and M can be appended to the
              size to specify KiBytes  resp.   MeBytes  instead  of  bytes.  B  is  accepted  but
              superfluous.  If size is 0, the maximum message size is unlimited.  (Default: 0)

       MapInbox mailbox
              Create a virtual mailbox (relative to Path) which aliases the INBOX. Makes sense in
              conjunction with Patterns in the Channels section, though with a Maildir slave, you
              probably  want  to  place  Inbox under Path instead.  This virtual mailbox does not
              support subfolders.

       Flatten delim
              Flatten the hierarchy within this Store by  substituting  the  canonical  hierarchy
              delimiter  /  with delim.  This can be useful when the MUA used to access the Store
              provides suboptimal handling of hierarchical mailboxes, as is the case  with  Mutt.
              A common choice for the delimiter is ..
              Note  that  flattened  sub-folders of the INBOX always end up under Path, including
              the "INBOXdelim" prefix.

       Trash mailbox
              Specifies a mailbox (relative to  Path)  to  copy  deleted  messages  to  prior  to
              expunging.  See RECOMMENDATIONS and INHERENT PROBLEMS below.  (Default: none)

       TrashNewOnly yes|no
              When  trashing,  copy  only  not  yet  propagated messages. This makes sense if the
              remote Store has a Trash as well (with TrashNewOnly no).  (Default: no)

       TrashRemoteNew yes|no
              When expunging the remote Store, copy not yet propagated messages to  this  Store's
              Trash. When using this, the remote Store does not need an own Trash at all, yet all
              messages are archived.  (Default: no)

   Maildir Stores
       The reference point for relative Paths is the current working directory.

       As mbsync needs UIDs, but no standardized UID storage scheme exists  for  Maildir,  mbsync
       supports two schemes, each with its pros and cons.
       The  native  scheme is stolen from the latest Maildir patches to c-client and is therefore
       compatible with pine. The UID validity is stored in a file named  .uidvalidity;  the  UIDs
       are encoded in the file names of the messages.
       The  alternative  scheme is based on the UID mapping used by isync versions 0.8 and 0.9.x.
       The invariant parts of the file names of the messages are used as  keys  into  a  Berkeley
       database named .isyncuidmap.db, which holds the UID validity as well.
       The  native  scheme  is  faster,  more  space efficient, endianness independent and "human
       readable", but will be disrupted if a message  is  copied  from  another  mailbox  without
       getting  a  new  file name; this would result in duplicated UIDs sooner or later, which in
       turn results in a UID validity  change,  making  synchronization  fail.   The  alternative
       scheme  would  fail  if  a  MUA  changed  a message's file name in a part mbsync considers
       invariant; this would be interpreted as a message deletion and a new message, resulting in
       unnecessary traffic.
       Mutt is known to work fine with both schemes.
       Use mdconvert to convert mailboxes from one scheme to the other.

       MaildirStore name
              Define the Maildir Store name, opening a section for its parameters.

       AltMap yes|no
              Use  the alternative UID storage scheme for mailboxes in this Store.  This does not
              affect mailboxes that do already have a UID storage scheme; use mdconvert to change
              it.  See RECOMMENDATIONS below.  (Default: no)

       Inbox path
              The location of the INBOX. This is not relative to Path, but it is allowed to place
              the INBOX inside the Path.  (Default: ~/Maildir)

       InfoDelimiter delim
              The character used to delimit the  info  field  from  a  message's  basename.   The
              Maildir  standard  defines  this  to  be  the  colon, but this is incompatible with
              DOS/Windows file systems.  (Default: the value of FieldDelimiter)

       SubFolders Verbatim|Maildir++|Legacy
              The on-disk folder naming style used for hierarchical mailboxes.  This  has  option
              has no effect when Flatten is used.
              Suppose mailboxes with the canonical paths top/sub/subsub and INBOX/sub/subsub, the
              styles will yield the following on-disk paths:
              Verbatim - Path/top/sub/subsub and Inbox/sub/subsub (this is the style you probably
              want to use)
              Maildir++  - Inbox/.top.sub.subsub and Inbox/..sub.subsub (this style is compatible
              with Courier and Dovecot - but  note  that  the  mailbox  metadata  format  is  not
              compatible).  Note that attempts to set Path are rejected in this mode.
              Legacy  - Path/top/.sub/.subsub and Inbox/.sub/.subsub (this is mbsync's historical
              (Default: unset; will error out when sub-folders are encountered)

   IMAP4 Accounts
       IMAPAccount name
              Define the IMAP4 Account name, opening a section for its parameters.

       Host host
              Specify the DNS name or IP address of the IMAP server.
              If Tunnel is used, this  setting  is  needed  only  if  SSLType  is  not  None  and
              CertificateFile  is  not  used, in which case the host name is used for certificate
              subject verification.

       Port port
              Specify the TCP port number of the IMAP server.  (Default: 143 for  IMAP,  993  for
              If Tunnel is used, this setting is ignored.

       Timeout timeout
              Specify  the  connect  and data timeout for the IMAP server in seconds.  Zero means
              unlimited.  (Default: 20)

       User username
              Specify the login name on the IMAP server.

       Pass password
              Specify the password for username on the IMAP server.  Note that this option is not
              required.   If  neither  a  password  nor  a  password  command is specified in the
              configuration file, mbsync will prompt you for a password.

       PassCmd [+]command
              Specify a shell command to obtain a password  rather  than  specifying  a  password
              directly.  This  allows  you  to  use  password files and agents.  The command must
              produce exactly one line on stdout; the trailing newline is optional.  Prepend + to
              the  command  to  indicate that it produces TTY output (e.g., a decryption password
              prompt); failure to do so will merely produce messier output.

       Tunnel command
              Specify a command to run to establish  a  connection  rather  than  opening  a  TCP
              socket.  This allows you to run an IMAP session over an SSH tunnel, for example.

       AuthMechs type ...
              The  list  of  acceptable authentication mechanisms.  In addition to the mechanisms
              listed in the SASL registry (link below), the legacy IMAP LOGIN mechanism is known.
              The  wildcard  *  represents  all  mechanisms that are deemed secure enough for the
              current SSLType setting.  The actually used mechanism is  the  most  secure  choice
              from  the  intersection  of  this  list,  the  list supplied by the server, and the
              installed SASL modules.  (Default: *)

       SSLType {None|STARTTLS|IMAPS}
              Select the connection security/encryption method:
              None - no security.  This is the default when Tunnel is set, as tunnels are usually
              STARTTLS  - security is established via the STARTTLS extension after connecting the
              regular IMAP port 143. Most servers support this, so it is the  default  (unless  a
              tunnel is used).
              IMAPS  -  security  is  established  by  starting  SSL/TLS  negotiation right after
              connecting the secure IMAP port 993.

       SSLVersions [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]
              Select the acceptable SSL/TLS versions.  Use old versions only when the server  has
              problems with newer ones.  (Default: [TLSv1] [TLSv1.1] [TLSv1.2]).

       SystemCertificates yes|no
              Whether  the  system's  default  root cerificate store should be loaded.  (Default:

       CertificateFile path
              File containing additional X.509 certificates used  to  verify  server  identities.
              Directly matched peer certificates are always trusted, regardless of validity.
              Note   that   the  system's  default  certificate  store  is  always  used  (unless
              SystemCertificates is disabled) and should not be specified here.

       ClientCertificate path
              File containing a client certificate to send to the server.  ClientKey should  also
              be specified.
              Note  that  client  certificate  verification  is  usually  not  required, so it is
              unlikely that you need this option.

       ClientKey path
              File containing the private key corresponding to ClientCertificate.

       PipelineDepth depth
              Maximum number of IMAP commands which can be  simultaneously  in  flight.   Setting
              this  to 1 disables pipelining.  This is mostly a debugging option, but may also be
              used to limit average bandwidth consumption (GMail may require this if you  have  a
              very  fast  connection),  or  to  spare  flaky servers like M$ Exchange.  (Default:

       DisableExtension[s] extension ...
              Disable the use of specific IMAP extensions.  This can be used to work around  bugs
              in servers (and possibly mbsync itself).  (Default: empty)

   IMAP Stores
       The reference point for relative Paths is whatever the server likes it to be; probably the
       user's $HOME or $HOME/Mail on that server. The location of INBOX is up to  the  server  as
       well and is usually irrelevant.

       IMAPStore name
              Define the IMAP4 Store name, opening a section for its parameters.

       Account account
              Specify  which IMAP4 Account to use. Instead of defining an Account and referencing
              it here, it is also possible to specify all the Account  options  directly  in  the
              Store's section - this makes sense if an Account is used for one Store only anyway.

       UseNamespace yes|no
              Selects  whether  the  server's  first  "personal"  NAMESPACE should be prefixed to
              mailbox names. Disabling this makes sense  for  some  broken  IMAP  servers.   This
              option is meaningless if a Path was specified.  (Default: yes)

       PathDelimiter delim
              Specify  the server's hierarchy delimiter.  (Default: taken from the server's first
              "personal" NAMESPACE)
              Do not abuse this to re-interpret the hierarchy.  Use Flatten instead.

       Channel name
              Define the Channel name, opening a section for its parameters.

       {Master|Slave} :store:[mailbox]
              Specify the Master resp. Slave Store to be connected by this Channel.  If  Patterns
              are  specified, mailbox is interpreted as a prefix which is not matched against the
              patterns, and which is not affected  by  mailbox  list  overrides.   Otherwise,  if
              mailbox is omitted, INBOX is assumed.

       Pattern[s] [!]pattern ...
              Instead  of  synchronizing  only  one  mailbox pair, synchronize all mailboxes that
              match the pattern(s). The mailbox names are the same  on  both  Master  and  Slave.
              Patterns  are IMAP4 patterns, i.e., * matches anything and % matches anything up to
              the next hierarchy delimiter. Prepending ! to a  pattern  makes  it  an  exclusion.
              Multiple  patterns  can  be specified (either by supplying multiple arguments or by
              using Pattern multiple times); later matches take precedence.
              Note that INBOX is not matched by wildcards, unless it lives under Path.
              The mailbox list selected by Patterns can be overridden by  a  mailbox  list  in  a
              channel reference (a Group specification or the command line).
              Example: "Patterns % !Trash"

       MaxSize size[k|m][b]
              Analogous  to  the  homonymous option in the Stores section, but applies equally to
              Master and Slave. Note that this actually modifies the Stores, so take care not  to
              provide conflicting settings if you use the Stores in multiple Channels.

       MaxMessages count
              Sets  the maximum number of messages to keep in each Slave mailbox.  This is useful
              for mailboxes where you keep a complete archive on the server, but want  to  mirror
              only  the  last messages (for instance, for mailing lists).  The messages that were
              the first to arrive in the  mailbox  (independently  of  the  actual  date  of  the
              message)  will  be  deleted first.  Messages that are flagged (marked as important)
              and (by default) unread messages will not be automatically deleted.  If count is 0,
              the maximum number of messages is unlimited (Default: 0).

       ExpireUnread yes|no
              Selects  whether  unread  messages  should  be  affected by MaxMessages.  Normally,
              unread messages are considered important and thus never expired.  This ensures that
              you  never  miss  new  messages  even  after an extended absence.  However, if your
              archive contains large amounts of unread  messages  by  design,  treating  them  as
              important  would  practically  defeat  MaxMessages. In this case you need to enable
              this option.  (Default: no).

       Sync {None|[Pull] [Push] [New] [ReNew] [Delete] [Flags]|All}
              Select the synchronization operation(s) to perform:
              Pull - propagate changes from Master to Slave.
              Push - propagate changes from Slave to Master.
              New - propagate newly appeared messages.
              ReNew - previously refused messages are re-evaluated for propagation.  Useful after
              flagging  affected  messages  in  the  source  Store  or  enlarging  MaxSize in the
              destination Store.
              Delete - propagate message deletions.  This  applies  only  to  messages  that  are
              actually  gone,  i.e., were expunged. The affected messages in the remote Store are
              marked as deleted only, i.e., they won't be really  deleted  until  that  Store  is
              Flags  -  propagate flag changes. Note that Deleted/Trashed is a flag as well; this
              is particularly interesting if you use mutt with the maildir_trash option.
              All (--full on the command line) - all of the above.  This is the global default.
              None (--noop on the command line) - don't propagate anything.  Useful if  you  want
              to expunge only.

              Pull  and  Push  are  direction  flags, while New, ReNew, Delete and Flags are type
              flags. The two flag classes make up a two-dimensional matrix (a table).  Its  cells
              are the individual actions to perform. There are two styles of asserting the cells:
              In  the  first  style,  the flags select entire rows/colums in the matrix. Only the
              cells which are selected both horizontally and vertically are asserted.  Specifying
              no  flags  from a class is like specifying all flags from this class.  For example,
              "Sync Pull New Flags" will propagate new messages and flag changes from the  Master
              to  the Slave, "Sync New Delete" will propagate message arrivals and deletions both
              ways, and "Sync Push" will propagate all changes from the Slave to the Master.
              In the second style, direction  flags  are  concatenated  with  type  flags;  every
              compound flag immediately asserts a cell in the matrix. In addition to at least one
              compound flag, the individual flags can be used as well,  but  as  opposed  to  the
              first  style, they immediately assert all cells in their respective row/column. For
              example,  "Sync PullNew PullDelete Push"  will  propagate  message   arrivals   and
              deletions  from  the  Master  to  the  Slave  and any changes from the Slave to the
              Master.  Note that  it  is  not  allowed  to  assert  a  cell  in  two  ways,  e.g.
              "Sync PullNew Pull" and "Sync PullNew Delete Push" induce error messages.

       Create {None|Master|Slave|Both}
              Automatically  create  missing mailboxes [on the Master/Slave].  Otherwise print an
              error message and skip that mailbox pair if a mailbox and  the  corresponding  sync
              state does not exist.  (Global default: None)

       Remove {None|Master|Slave|Both}
              Propagate  mailbox  deletions  [to  the  Master/Slave].   Otherwise  print an error
              message  and  skip  that  mailbox  pair  if  a  mailbox  does  not  exist  but  the
              corresponding sync state does.
              For MailDir mailboxes it is sufficient to delete the cur/ subdirectory to mark them
              as deleted. This ensures compatibility with SyncState *.
              Note that for safety, non-empty mailboxes are never deleted.
              (Global default: None)

       Expunge {None|Master|Slave|Both}
              Permanently remove all messages [on the Master/Slave]  marked  for  deletion.   See
              RECOMMENDATIONS below.  (Global default: None)

       CopyArrivalDate {yes|no}
              Selects whether their arrival time should be propagated together with the messages.
              Enabling this makes sense in order to keep the time  stamp  based  message  sorting
              intact.   Note  that  IMAP  does not guarantee that the time stamp (termed internal
              date) is actually the arrival time, but it is usually close enough.  (Default: no)

       Sync, Create, Remove, Expunge, MaxMessages, and CopyArrivalDate can  be  used  before  any
       section  for  a  global  effect.   The  global settings are overridden by Channel-specific
       options, which in turn are overridden by command line switches.

       SyncState {*|path}
              Set the location of this Channel's synchronization state files. *  means  that  the
              state  should  be  saved  in a file named .mbsyncstate in the Slave mailbox itself;
              this has the advantage that you needn't to care for the state file  if  you  delete
              the mailbox, but it works only with Maildir mailboxes, obviously. Otherwise this is
              interpreted as a string to prepend to the Slave mailbox name to make up a  complete
              This  option  can be used outside any section for a global effect. In this case the
              appended  string  is   made   up   according   to   the   pattern   :master:master-
              box_:slave:slave-box (see also FieldDelimiter below).
              (Global default: ~/.mbsync/).

       Group name [channel[:box[,...]]] ...
              Define the Group name, opening a section for its parameters.  Note that even though
              Groups have an own namespace, they will "hide" Channels with the same name  on  the
              command line.
              One or more Channels can be specified on the same line.
              If  you supply one or more boxes to a channel, they will be used instead of what is
              specified in the Channel's Patterns.  The same can be done  on  the  command  line,
              except that there newlines can be used as mailbox name separators as well.

       Channel[s] channel[:box[,...]] ...
              Add  the  specified  channels  to  the group. This option can be specified multiple
              times within a Group.

   Global Options
       FSync yes|no
              Selects whether mbsync performs forced flushing, which determines the level of data
              safety after system crashes and power outages.  Disabling it is reasonably safe for
              file systems which are mounted with data=ordered  mode.   Enabling  it  is  a  wise
              choice  for  file systems mounted with data=writeback, in particular modern systems
              like ext4, btrfs and xfs. The performance impact  on  older  file  systems  may  be
              disproportionate.  (Default: yes)

       FieldDelimiter delim
              The  character  to  use  to  delimit  fields  in  the  string  appended to a global
              SyncState.  mbsync prefers  to  use  the  colon,  but  this  is  incompatible  with
              DOS/Windows  file  systems.  This option is meaningless for SyncState if the latter
              is *, obviously. However, it also determines the default of InfoDelimiter.  (Global
              default: ; on Windows, : everywhere else)

       BufferLimit size[k|m][b]
              The  per-Channel,  per-direction instantaneous memory usage above which mbsync will
              refrain from using more memory. Note that this is no  absolute  limit,  as  even  a
              single message can consume more memory than this.  (Default: 10M)


       If  mbsync's output is connected to a console, it will print progress counters by default.
       The output will look like this:

           C: 1/2  B: 3/4  M: +13/13 *23/42 #0/0  S: +0/7 *0/0 #0/0

       This represents the cumulative progress over channels, boxes,  and  messages  affected  on
       master  and  slave,  respectively.   The message counts represent added messages, messages
       with updated flags, and trashed messages, respectively.  No attempt is made  to  calculate
       the totals in advance, so they grow over time as more information is gathered.


       Make  sure  your  IMAP  server  does  not  auto-expunge deleted messages - it is slow, and
       semantically somewhat questionable. Specifically, Gmail needs to be configured not  to  do

       By  default, mbsync will not delete any messages - deletions are propagated by marking the
       messages as deleted on the remote store.  Once you have verified that  your  setup  works,
       you will typically want to set Expunge to Both, so that deletions become effective.

       mbsync's  built-in  trash  functionality  relies  on mbsync doing the expunging of deleted
       messages. This is the case when it propagates deletions of previously propagated messages,
       and the trash is on the target store (typically your IMAP server).
       However,  when  you intend mbsync to trash messages which were not propagated yet, the MUA
       must mark the messages as deleted  without  expunging  them  (e.g.,  Mutt's  maildir_trash
       option).  Note  that  most messages are propagated a long time before they are deleted, so
       this is a corner case you probably do not want to optimize for. This also implies that the
       TrashNewOnly and TrashRemoteNew options are typically not very useful.

       If  your server supports auto-trashing (as Gmail does), it is probably a good idea to rely
       on that instead  of  mbsync's  trash  functionality.   If  you  do  that,  and  intend  to
       synchronize  the  trash  like other mailboxes, you should not use mbsync's Trash option at

       Use of the Trash option with M$ Exchange 2013 requires the use  of  DisableExtension  MOVE
       due to a server bug.

       When  using  the  more  efficient default UID mapping scheme, it is important that the MUA
       renames files when moving them between Maildir folders.  Mutt always does that, while mu4e
       needs to be configured to do it:
           (setq mu4e-change-filenames-when-moving t)


       Changes  done  after  mbsync has retrieved the message list will not be synchronised until
       the next time mbsync is invoked.

       Using Trash on IMAP Stores without the UIDPLUS extension (notably, M$ Exchange  up  to  at
       least  2010)  bears  a race condition: messages will be lost if they are marked as deleted
       after the message list was retrieved but before the mailbox is expunged.  There is no risk
       as long as the IMAP mailbox is accessed by only one client (including mbsync) at a time.


              Default configuration file

              Directory containing synchronization state files


       mdconvert(1), isync(1), mutt(1), maildir(5)

       Up to date information on mbsync can be found at

       SASL   mechanisms   are  listed  at


       Originally written by Michael R. Elkins, rewritten  and  currently  maintained  by  Oswald
       Buddenhagen, contributions by Theodore Y. Ts'o.

                                           2015 Mar 22                                  mbsync(1)