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] [-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 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 all disable -print.

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 no -list, -push, or -pop is 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.