@need 3200

@node Introducing arch
@chapter Introducing arch

@code{arch} is a revision control, source code management, and
configuration management tool.  


This manual is an @code{arch} tutorial: its purpose is to help you get
started using @code{arch} for the first time, and then learn some of the
more advanced features of arch.

@need 3200

@section Who is this Manual For?

In order to use this manual, you should be familiar with the basic
unix command line tools (such as @code{ls}, @code{mv}, and @code{find}).  


In addition, you should be familiar with the programs @code{diff} and
@code{patch} and the concept of a @code{patchset}.


It is very helpful, but not strictly necessary if you have used or are
at least familiar with other revision control systems such as @code{CVS}.




@need 3200

@section Where's the Reference Manual?

@code{arch} is largely a @emph{self documenting} program.   The command:

@example
@group
        % tla help
@end group
@group
@end group
@end example

@noindent
will provide you with a categorized list of all available commands,
and for a given command @code{foo},

@example
@group
        % tla foo -H
@end group
@group
@end group
@end example

@noindent
will provide you with documentation for that command.




@need 3200

@section Another Source of Help -- the Mailing List

Arch is sufficiently different from older and competing systems that
new users are often a bit disoriented for the first few days.  You may
find it helpful to seek help on the @code{gnu-arch-users} mailing list
which you can find via links from:

@example
@group
    http://www.gnu.org/software/gnu-arch
@end group
@group
@end group
@end example



@need 3200

@section What is Revision Control?

A "revision control system" is a librarian and coordination tool for
trees of files and the changes made to them.  For example, a typical
software project uses revision control to keep track of how the
project's source code evolves over time, to keep track of each change
to that code (such as each bug fix or feature addition), to share
those changes among all the programmers working on the project and
help them remain in sync, and to combine changes made at different
times and/or by different programmers into a single source tree.


A "source management tool" is one that helps you to manage large
source trees even if they have many more files that you can keep track
of "by hand".  For example, a source management tool can @emph{inventory}
the source files in a tree, distinguish the source files from scratch
files and and other files that maybe stored there, and inform you when
source files are added and deleted.


"Configuration Management" addresses the needs of projects which
combine multiple, separately maintained source trees into a single
tree.   A configuration management tool helps you to easily construct
the combined project and to keep track of how development on the
component parts is synchronized.




@need 3200

@section Why Use arch?

@code{arch} has a number of advantages compared to competing systems.
Among these are:


@strong{Works on Whole Trees} @code{arch} keeps track of whole trees -- not just
individual files.  For example, if you change many files in a tree,
@code{arch} can record all of those changes as a group rather than
file-by-file; if you rename files or reorganize a tree, @code{arch} can
record those tree arrangements along with your changes to file
contents.


@strong{Changeset Oriented} @code{arch} doesn't simply "snapshot" your project
trees.  Instead, @code{arch} associates each revision with a particular
@emph{changeset}: a description of exactly what has changed.  @code{arch}
provides changeset oriented commands to help you review changesets,
merge trees by applying changesets, examine the history of a tree by
asking what changesets have been applied to it, and so forth.


@strong{Fully Distributed} @code{arch} doesn't rely on a @geindex central repository
@dfn{central repository}.
For example, there is no need to give write access to a project's
archive to all significant contributors, instead, each contributor can
have their own archive for their work.  @code{arch} seamlessly operates
across archive boundaries.







