
	     The arch World Wide Revision Control System

				 FAQ

The questions in this FAQ are paraphrased or abstracted from questions
I've received in email.  The most interesting questions and the most
often asked are included.

The questions are grouped by category, the categories being:

  A. NEW USER QUESTIONS
  B. PORTABILITY QUESTIONS
  C. EASE OF USE QUESTIONS
  D. SCALABILITY/ROBUSTNESS


			  NEW USER QUESTIONS

A1. The first time I try to create a branch, the mangled log message
  contains lines like:

	New-Patches: New-Patches: New-Patches: ....

  What gives?

  The answer is most likely that "awk" on your system is "mawk", which
  fails to be a Posix awk in its regexp syntax.  You can fix this by
  using GNU awk, or another more-Posixish awk instead.  See also the
  question, elswere in this FAQ, "Do I have to replace my system's
  native shell utilities to use arch?"



A2. The first time I try to import software, I get the error message:

  	>valid-log-file: invalid log file
	>    missing (or empty) body

  What's wrong?

  The command `larch make-log' creates an *empty* log message, which
  you should edit before invoking `larch import'.



A3. vi doesn't like the filename of log messages ("++log...").

  You can always use `vi ./++log...' or, at least with all vi
  implementations we've heard of, `vi -- ++log...'.



A4. How do I change the naming conventions by which source files are
  recognized?

  In version 1.0, you can not (except by making changes to your local
  copy of arch -- but be aware that that can cause your archives to be
  incompatible with other copies of arch).  Support for parameterized 
  naming conventions is planned for 1.1.




			PORTABILITY QUESTIONS


B1. Will arch run on my favorite system, _____?

  If _____ is reasonably close to being a Posix environment, 
  arch either runs there already, or can be easily ported.


B2. Can I arch from the walled-off side of a firewall?

  As of release 1.0pre3, you can.  All network traffic generated
  by arch uses the FTP protocol, with all data transferred in passive
  mode.


B3. Do I have to replace my system's native shell utilities to use arch?

  With a very small number of exceptions (documented in the user's
  guide) arch relies only on the features mandated by Posix.2.  If
  your system's utilities conform to that standard, arch can use them.

  Not every system conforms to Posix.2, and not every system that
  claims to conform to Posix.2 really does.  The GNU implementations
  of the standard shell, file, and text utilities are close enough
  to Posix.2 that arch can use them.

  You do not need to replace your system's installed utilities just
  to use arch: You can set a path just for arch, using a colon separated list
  of directory names, in ~/.arch-params/path.  The shell used by arch
  (the program named in "#!" lines of shell scripts) is selectable at
  configuration time (try "./configure --help" in the "src"
  directory).





			EASE OF USE QUESTIONS

C1. The arch user's guide is interesting and seems exciting, but after
  reading it, I'm at a loss for how to get started using arch.  What
  do I do?

  There's a new appendix (as of 1.0pre3) in the manual that guides you
  through the process of setting up and running a repository and
  projects.  It puts together many of the pieces introduced earlier in
  the manual.  Read that.

  The user's guide is organized as a progression, roughly from low
  level functionality to the high level functionality built on top of
  it.  The idea is that you should learn the low level parts well
  enough to understand what's really going on -- rather than just
  accepting commands like "commit" or "star-merge" as vague revision
  control magic.  Once you've started to become familiar with that
  material, the new appendix will help you apply it in practice.



C2. arch seems to have a large number of commands.

  It sure does.

  Seriously, though, there is a sense in which arch has even more
  commands than you think.  arch can be configured to make every
  revision of selected branches available to you as ordinary project
  trees.  That means that, in addition to the arch commands for
  manipulating past revisions, you also have available every generic
  unix shell command, every generic directory browser, every
  generic diff/merge tool, etc.  Yes, there's a lot to learn in the
  world.



C3. arch uses funny filenames, with names like "{arch}".  These confuse
  my shell

  Peculiar filenames are used primarily for files that: (1) you won't
  have to type the name of very often; (2) you probably don't want
  mixed into a long directory listing; (3) you wouldn't want to
  confuse with "regular files".  The funny filenames sort to
  the beginning or end of directory lists.  In just about every shell,
  you can use these names by surrounding them with quotes.  In really
  nice shells, you don't need quotes and interactive filename
  completion works just fine.  You are using a really nice shell,
  aren't you? :-)

  I recommend using a really nice directory editor: one that (at
  least) displays file trees as indented outlines (letting you expand
  or hide subdirectories), load selected files into an editor, search
  for files by typing a few characters of their name, and select files
  to invoke shell commands on them.





		   SCALABILITY/ROBUSTNESS QUESTIONS


D1. Will arch scale to projects involving many programmers?

  arch will scale to projects involving many programmers 
  better than most systems.  In particular, the branches
  for such projects can be hosted in multiple, independently
  administered repositories -- which means that the administration
  costs can be distributed and that no server is likely to become
  bogged down with arch traffic.

  Additionally, arch has several advanced features for developing on
  branches, making carefully controlled merges to the main
  "trunk(s)".   That's an ideal strategy for projects with many
  programmers. 


D1. Will arch scale to projects with huge source trees?

  arch has features for multi-tree configuration: you can divide a
  huge source tree into manageable pieces; create separate archive
  categories for each of those pieces; then use arch's configuration
  management features to put the pieces together and keep them in
  sync.

  There is certainly room to improve the performance of arch in ways
  that makes the largest practical project tree size larger for the
  case where the entire tree is stored as one piece.


D1. Is arch reliable enough to start using today?

  That depends on your situation.  I use arch quite a bit -- it is
  self-hosting.  On the other hand, arch is still new, so it seems
  likely there are still bugs.

  See the file src/arch/=TODO.  It documents a few known, non-critical
  bugs.  It also has a rough testing plan for arch.  It contains a
  partial list of additional features that are desirable.  What arch
  really needs, at this point in its development, is sponsorhip or
  investment in a full-time testing team and a full-time development
  team.




# tag: Tom Lord Wed Jan 30 20:14:52 2002 (=FAQS/general)
#
