@need 3200

@node arch Commands in General
@chapter arch Commands in General

Every command in @code{arch} is accessed via the program @code{arch}, using an
ordinary sub-command syntax:

@example
@group
        % larch <sub-command> <options> <parameters>
@end group
@group
@end group
@end example

A list of all sub-commands can be obtained from:

@example
@group
        % larch --help-commands
@end group
@group
@end group
@end example

The most complete documentation for each command is available via its
help message.  The help messages in @code{arch} are roughly comperable to
traditional unix @code{man} pages.   For example, try:

@example
@group
        % larch make-archive --help
        create a new archive directory
        usage: make-archive [options] (-u | name) directory
@end group
@group
@end group
@end example
@example
@group
         -V --version                  print version info
         -h --help                     display help
@end group
@group
@end group
@end example
@example
@group
         -r --readme file              save FILE as the README
                                       for this archive
@end group
@group
@end group
@end example
@example
@group
         -u --update                   update an existing archive
@end group
@group
@end group
@end example
@example
@group
        NAME is the global name for the archive.  It must be an
        email address with a fully qualified domain name, optionally
        followed by "--" and a string of letters, digits, periods
        and dashes.
@end group
@group
@end group
@end example
@example
@group
        Normally the archive directory must not already exist, but.
        there is an exception:
@end group
@group
@end group
@end example
@example
@group
        If -u or --update is specified, then attempt to bring
        an existing archive up to date with respect to this
        version of arch and update meta-info, such as the README.
        file.
@end group
@group
@end group
@end example
@example
@group
        If -u or --update is specified, the archive name must
        not be specified.
@end group
@group
@end group
@end example

There is a great deal of regularity among commands regarding option
names and parameter syntax.  Hopefully, you'll pick this up as you
learn the various commands.

@need 3200

@section The arch Commands

Here is a synopsis of all @code{arch} commands: the output of @code{larch
--help-commands}:

@example
@group

@end group
@group
                       larch sub-commands
                       -----------------
@end group
@group

@end group
@group
* User Commands
@end group
@group

@end group
@group
                       my-id : print or change your id
          my-default-archive : print or change your default archive
@end group
@group

@end group
@group
            register-archive : record the location of an archive
             whereis-archive : print the registered location of an archive
                    archives : report registered archives and their locations
@end group
@group


@end group
@group
* Project Tree Commands
@end group
@group

@end group
@group
                   init-tree : initialize a new project tree
                   tree-root : find and print the root of a project tree
@end group
@group

@end group
@group
                tree-version : print the default version for a project tree
            set-tree-version : set the default version for a source tree
@end group
@group


@end group
@group
* Project Tree Inventory Commands
@end group
@group

@end group
@group
                   inventory : inventory a source tree
@end group
@group

@end group
@group
              tagging-method : print or change a project tree tagging method
                   tree-lint : audit a source tree
                missing-tags : list files missing inventory tags
                    file-tag : print the tag of a project tree file
@end group
@group

@end group
@group
                         add : add an explicit inventory tag
                      delete : remove an explicit inventory tag
                        move : move an explicit inventory tag
@end group
@group

@end group
@group
            explicit-default : set the default explicit tag for a directory
@end group
@group

@end group
@group
                set-manifest : set the inventory manifest from project tree
                    manifest : print the inventory manifest
              check-manifest : compare the inventory manifest to reality
@end group
@group


@end group
@group
* Patch Set Commands
@end group
@group

@end group
@group
                     mkpatch : compare two source trees and create a patch tree
                     dopatch : apply a patch tree to a source tree
@end group
@group

@end group
@group
                patch-report : generate a report from a patch set
@end group
@group

@end group
@group
                 empty-patch : make a null patch set
@end group
@group


@end group
@group
* Archive Commands
@end group
@group

@end group
@group
                make-archive : create a new archive directory
@end group
@group

@end group
@group
               make-category : create a new category within an archive
                 make-branch : create a new branch within an archive
                make-version : create a new version within an archive
@end group
@group

@end group
@group
                  categories : list the categories in an archive
                    branches : list the branches in an archive category
                    versions : list the versions in an archive branch
                   revisions : list the revisions in an archive version
@end group
@group

@end group
@group
             cat-archive-log : print the contents of an archive log entry
@end group
@group

@end group
@group
      archive-cache-revision : cache a full source tree in an archive
    archive-cached-revisions : list full source trees cached in an archive
    archive-uncache-revision : remove a cached revision from an archive
@end group
@group

@end group
@group
             category-readme : print the =README of a category
               branch-readme : print the =README of a branch
              version-readme : print the =README of a version
@end group
@group


@end group
@group
* Patch Log Commands
@end group
@group

@end group
@group
                    make-log : initialize a new log file entry
@end group
@group

@end group
@group
                        logs : list patch logs in a project tree
                     add-log : add a version patch log to a project tree
@end group
@group

@end group
@group
                      log-ls : print version patches in a project tree
                     cat-log : print the contents of a project tree log entry
            log-header-field : filter a header field from a log entry
@end group
@group

@end group
@group
                   changelog : generate a change log from a patch log
               log-for-merge : generate a log entry bodyfor a merge
@end group
@group

@end group
@group
                merge-points : report where two branches have been merged
               new-on-branch : list tree patches new to a branch
@end group
@group


@end group
@group
* Archive Transaction Commands
@end group
@group

@end group
@group
                      import : archive a from-scratch base revision
                      commit : archive a revision
                         get : construct a project tree for a revision
@end group
@group

@end group
@group
                   get-patch : retrieve a patch set from an archive
@end group
@group

@end group
@group
                 lock-branch : lock a branch
               lock-revision : acquire the lock for the next revision
@end group
@group

@end group
@group
                 push-mirror : update a read-only repository mirror
@end group
@group


@end group
@group
* Multi-project Configuration Commands
@end group
@group


@end group
@group
                build-config : instantiate a multi-project tree
               update-config : update a multi-project tree
               replay-config : replay a multi-project tree
@end group
@group

@end group
@group
               record-config : record a revision-specific configuration
                 show-config : show the revision frontier of a configuration
@end group
@group

@end group
@group
              config-history : report the history of a configuration
@end group
@group


@end group
@group
* Commands for Branching and Merging
@end group
@group


@end group
@group
                      update : merge local changes with the latest revision
                      replay : merge the latest revsion with local changes
                 delta-patch : compute and apply an arbitrary patch
                  star-merge : merge of mutually merged branches
@end group
@group

@end group
@group
                         tag : create a continuation revision (tag or branch)
@end group
@group

@end group
@group
              prepare-branch : create a project tree for a new branch
               finish-branch : commit project tree as a new branch
@end group
@group

@end group
@group
                        join : join a sibling branch
@end group
@group

@end group
@group
               whats-missing : print patches missing from a project tree
@end group
@group


@end group
@group
* Local Cache Commands
@end group
@group

@end group
@group
                what-changed : compare project tree to cached pristine
                  file-diffs : compare file with cached pristine revision
@end group
@group

@end group
@group
                   pristines : list the pristine trees in a project tree
               lock-pristine : lock a pristine revision locking
@end group
@group


@end group
@group
* Revision Library Commands
@end group
@group

@end group
@group
         my-revision-library : print or set your revision library path
@end group
@group

@end group
@group
                library-find : find a revision in a revision library
                 library-add : add a revision to a revision library
              library-remove : remove a revision from a revision library
@end group
@group

@end group
@group
            library-archives : list the archives in the revision library
          library-categories : list categories in the revision library
            library-branches : list branches in the revision library
            library-versions : list versions in the revision library
           library-revisions : list revisions in the revision library
@end group
@group

@end group
@group
                 library-log : print a log message from the library
                library-file : find a file in a revision library
@end group
@group


@end group
@group
* Web Related Commands
@end group
@group

@end group
@group
               patch-set-web : create or update a patch-set web
        update-distributions : build or update an FTP area
@end group
@group

@end group
@group
           distribution-name : revision name -> distribution name
@end group
@group


@end group
@group
* Notification Commands
@end group
@group

@end group
@group
                      notify : trigger actions for changes to an archive
                 my-notifier : print or set your default notify directory
@end group
@group

@end group
@group
         mail-new-categories : send email notices about new categories
           mail-new-branches : send email notices about new branches
           mail-new-versions : send email notices about new versions
          mail-new-revisions : send email notices about new revisions
@end group
@group

@end group
@group
              notify-library : add new revisions to the library
@end group
@group

@end group
@group
          push-new-revisions : send email notices about new revisions
@end group
@group

@end group
@group
              sendmail-mailx : send email with sendmail ala POSIX mailx
@end group
@group


@end group
@group
For help with a command, try: larch command --help
@end group
@group


@end group
@end example






