NAME

       folder, folders - set/list current nmh folder/message

SYNOPSIS

       folder [-help] [-version] [+folder] [msg] [-all | -noall] [-create | -nocreate] [-fast | -nofast]
            [-header | -noheader] [-recurse | -norecurse] [-total | -nototal] [-list | -nolist] [-push | -pop]
            [-pack | -nopack] [-print | -noprint] [-verbose | -noverbose]

       folders is equivalent to folder -all

DESCRIPTION

       When  folder  is  given  the  -print  switch  (the  default), it lists: the current folder, the number of
       messages in it and their range (low-high), the folder's current  message,  and  an  indication  of  extra
       files, if any.  For example:

            inbox+            has  16 messages (  3- 22); cur=  5.

       If  a  +folder  and/or  msg  are  specified, they will become the current folder and/or message.  (When a
       +folder argument is given, this corresponds to a “cd” operation in the shell; when no +folder argument is
       given, this corresponds roughly to a “pwd” operation in the shell.) If -noprint is specified,  a  +folder
       and/or  msg  may still be specified to set the current folder and/or message, but the folder summary will
       not be printed.

       If the specified (or default) folder doesn't exist, folder will ask the user  if  the  folder  should  be
       created;  when  standard input is not a tty, the answer is assumed to be “yes”.  The -create switch tells
       folder to create new folders without query.  (This is an easy way to create an  empty  folder  for  later
       use.)   Specifying  -nocreate  will  cause  folder  to print an error message and exit without creating a
       folder.

   Multiple Folders
       Specifying -all will produce a summary line for each top-level folder in the user's nmh directory, sorted
       alphabetically.  (If folder is invoked by a name ending with  “s”  (e.g.   folders),  -all  is  assumed.)
       Specifying -recurse with -all will include a line for all sub-folders.  These folders are all preceded by
       any read-only folders, which occur as “atr-cur-” entries in the user's nmh context.  For example:

            FOLDER                  # MESSAGES RANGE      CUR     (OTHERS)
            /var/work/folder  has  35 messages ( 1- 35);  cur=23.
            /usr/bugs/Mail    has  82 messages ( 1-108);  cur=82.
            ff                has  no messages.
            inbox+            has  16 messages ( 3- 22);  cur= 5.
            mh                has  76 messages (15- 76);  cur=70.
            notes             has   2 messages ( 1-  2);  cur= 1.
            ucom              has 124 messages ( 1-124);  cur= 6; (others).
            TOTAL = 339 messages in 7 folders

       The  “+”  after  inbox indicates that it is the current folder.  The “(others)” indicates that the folder
       ucom contains files which aren't messages; these may either be sub-folders, or files  that  don't  belong
       under the nmh file naming scheme.

       The  header  is  output  if  either  the  -all  or  -header  switches are specified.  It is suppressed by
       -noheader.

       The folder and message totals are output if either the -all or -total switches are specified.   They  are
       suppressed by -nototal.

       If  -fast is given, only the folder name (or names, in the case of -all) will be listed.  (This is faster
       because the folders need not be read.)

       If a +folder is given with the -all switch, folder will, in addition to setting the current folder,  list
       the  top-level  sub-folders  for  the  current folder (with -norecurse) or list all sub-folders under the
       current folder recursively (with -recurse).

       If msg is supplied, together with +folder or without -all, it will become the current message of  +folder
       (if it had been supplied) or the current folder.

       The  -recurse  switch lists each folder recursively, so its use effectively defeats the speed enhancement
       of -fast, since each folder must be searched for sub-folders.  Nevertheless,  the  combination  of  these
       options is useful.

   Compacting a Folder
       The  -pack  switch  will  compress the message names in the designated folders, removing holes in message
       numbering.  The -verbose switch directs folder to tell the user the  general  actions  it  is  taking  to
       compress the folder.

   The Folder Stack
       The  -push  switch  directs folder to push the current folder onto the folder-stack, and make the +folder
       argument the current folder.  If +folder is not given, the current folder and the top of the folder-stack
       are exchanged.  This corresponds to the “pushd” operation in the shell.

       The -pop switch directs folder to discard the top of the folder-stack, after setting the  current  folder
       to  that  value.  No +folder argument is allowed.  This corresponds to the “popd” operation in the shell.
       The -push and -pop switches are mutually exclusive: the last  occurrence  of  either  one  overrides  any
       previous occurrence of the other.  The use of either of these switches also sets -list, by default.

       The  -list  switch  directs  folder  to  list the folder-stack.  No +folder argument is allowed.  After a
       successful -push or -pop, the -list action is taken, unless a -nolist switch follows them on the  command
       line.   This  corresponds  to  the  “dirs”  operation  in the shell.  The -push, -pop, and -list switches
       disable the default -print behavior.

FILES

       $HOME/.mh_profile   The user's profile.

PROFILE COMPONENTS

       Path:               To determine the user's nmh directory.
       Current-Folder:     To find the default current folder.
       Folder-Protect:     To set mode when creating a new folder.
       Folder-Stack:       To determine the folder stack.

SEE ALSO

       mhpath(1), refile(1), rmf(1)

DEFAULTS

       +folder             The current folder.
       msg                 “none”
       -nofast
       -noheader
       -nototal
       -nopack
       -norecurse
       -noverbose
       -print              is the default if none of -list, -push, or -pop are specified.
       -list               is the default if -push, or -pop is specified.

CONTEXT

       If +folder and/or msg are given, they will become the current folder and/or message.

BUGS

       There is no way to restore the default behavior (to ask the user whether to create a non-existent folder)
       after -create or -nocreate is given.

nmh-1.8                                            2016-08-29                                        FOLDER(1mh)