@need 3200

@node arch Project Trees
@chapter arch Project Trees

One of the central organizing concepts of @code{arch} is the @geindex project
tree
@dfn{project
tree}.  For the most part, a project tree is an ordinary tree of
files, directories and symbolic links -- all files that you create and
maintain as part of your project.


In addition to the tree content you create, @code{arch} itself maintains
some control files in a project tree.  You should regard these extra
control files as part of your project's content.  For example, if you
distribute source for a program managed by @code{arch}, you will
ordinarilly want to @emph{include} the control files: they are useful to
other people.

@menu
* Initializing a Project Tree::
* Finding the Root of a Project Tree::
@end menu

@need 3200

@node Initializing a Project Tree
@section Initializing a Project Tree

@geindex init-tree

@geindex /wd



To initialize a project tree for the first time, from the root of the
tree, use the command:

@example
@group
        % larch init-tree
@end group
@group
@end group
@end example

For example, here is how I initialized the project tree containing the
source for @code{arch} itself:

@example
@group
        % cd ~/wd/arch
        % larch init-tree
@end group
@group
@end group
@end example

That will create a subdirectory, at the root of the tree, called
@code{@{arch@}}.  Most @code{arch} control files are stored in the tree rooted at
@code{@{arch@}}: you should never create, remove, or modify files there by
hand.


When you have multiple project trees for related projects it is good
practice to make them sibling directories.  This is because @code{arch}
sometimes caches information in project trees and those caches can
speed up some operations.  When looking for information in a cache,
@code{arch} looks not only in the current project tree, but in any sibling
project trees.  For example, while working on @code{arch}, I might have
several copies of @code{arch}, each for working on a different set of
features:

@example
@group
        % cd ~/wd
        % ls
        arch    arch-branches   arch-inventory   arch-reporting
@end group
@group
@end group
@end example

In this manual, @code{~/wd} always refers to a "directory of project
trees".  (The convention means the same thing as, but is less
cumbersome than @code{$@{PROJECT_TREES@}} -- there is no requirement that
your directory of project trees be called @code{~/wd}, or that you only
have one such directory.)




@need 3200

@node Finding the Root of a Project Tree
@section Finding the Root of a Project Tree

@geindex tree-root



From any directory within a project tree, the command:

@example
@group
        % larch tree-root
@end group
@group
@end group
@end example

@noindent
prints the full path name of the root of the project tree:

@example
@group
        % cd ~/wd/arch/src
        % larch tree-root
        /home/lord/wd/arch
@end group
@group
@end group
@end example






