Provided by: isync_1.1.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 (as opposed to  some  other  mail  synchronizers).   OTOH,  mbsync  is
       susceptible  to UID validity changes (that should never happen, but see "Compatibility" in
       the README).  Synchronization state is kept in one  local  text  file  per  mailbox  pair;
       multiple replicas of a 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.

       -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 the IMAP4 network traffic.

       -D, --debug
              Enable printing debug information.

       -q, --quiet
              Suppress informational messages.  If specified twice, suppress warning messages  as


       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: "")

       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.  (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)

   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.

       Port port
              Specify  the  TCP  port number of the IMAP server.  (Default: 143 for IMAP, 993 for

       User username
              Specify the login name on the IMAP server.  (Default: current local user)

       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.

       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.
              Host and Port are ignored when Tunnel is set.

       RequireCRAM yes|no
              If set to yes, mbsync will abort the connection if no  CRAM-MD5  authentication  is
              possible.  (Default: no)

       UseIMAPS yes|no
              If  set  to  yes,  the default for Port is changed to 993 and mbsync will start SSL
              negotiation immediately after establishing the connection to the server.
              Note that modern servers support SSL on the regular IMAP port 143 via the  STARTTLS
              extension, which will be used automatically by default.

       RequireSSL yes|no
              mbsync  will  abort  the connection if a TLS/SSL session cannot be established with
              the IMAP server.  (Default: yes)

       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 and should not be
              specified here.

       UseSSLv2 yes|no
              Use SSLv2 for communication with the IMAP server over SSL?
              Note that this option is deprecated for security reasons.  (Default: no)

       UseSSLv3 yes|no
              Use SSLv3 for communication with the IMAP server over SSL?  (Default: no)

       UseTLSv1 yes|no
              Use TLSv1 for communication with the IMAP server over SSL?  (Default: yes)

       UseTLSv1.1 yes|no
              Use TLSv1.1 for communication with the IMAP server over SSL?  (Default: no)

       UseTLSv1.2 yes|no
              Use TLSv1.2 for communication with the IMAP server over SSL?  (Default: no)

       PipelineDepth depth
              Maximum number of IMAP commands which can be  simultaneously  in  flight.   Setting
              this  to 1 disables pipelining.  This is mostly a debugging only option.  (Default:

   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 does not exist.  (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, 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-
              (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)


       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


       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


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

                                           2013 Dec 14                                  mbsync(1)