~abentley/bzrtools/bzrtools.dev

FAI (The Friendly Arch Interface) 0.2 (aka pyaba)

Fai is a commandline-based Arch tool with interactive prompting.  It aims to be

a better commandline user interface than tla.  By combining functionality

that is handled as separate commands in tla, it aims to have smaller command

set than tla.

Quick Start (or "Where's the documentation?")

  Most of the documentation currently available for fai is accessed through

  inline documentation.

  To see all the available commands:

	$ fai help

  To get help on a specific command you, use either of these:

    $ fai help COMMAND

	$ fai COMMAND --help

  Also, see the HANDY HINTS below.

  There's also a web site: http://sourcecontrol.net/~abentley/fai/

  But it's focused more on programming Fai than on using it.

What's there now?

  * Compatibility with aba commands

  * Alias expansion (no prefix required for native commands)

  * Automatic aliases; these determine the revision by performing functions

  * tla fallthrough (to be removed when redundant)

  * smart colorizing (which can be turned off)

  * prompts that can be configured to take defaults

  Commands: ('fai help -n' for a full list)

  * get: an improved get that can use URLs and automatically create local 

         mirrors.

  * revisions: a combination of logs, missing, revisions, cachedrevs, etc.

               also provides:

	         --missing-from (which of my revisions are missing from the 

		 target?)

		 --modified (which revisions modified this file?)

		 --ancestry (iterates through the tree's patchlog ancestry)

  * commit: prompts on empty commits, missing log messages

  * update: updates to the requested revision, while retaining local changes.

            prompts to change tree version.

  * revert: undo command that can undo specific types of changes

  * changes: can take two arguments, making delta redundant

What's coming soon?

  More native implementations of the common commands.

  An init command that will do my-id, make-archive, archive-setup, init-tree

  Option defaults are high on the list, too.

Aren't you that guy who wrote that aba thing?

  Yeah.  aba's nice and all, but POSIX shell isn't my favourite language.  It's

  not geared at producing reliable, unambiguous programs.  I won't say 

  "impossible", since the original Arch implementation was in shell.  Python

  (like many other languages) has facilities that make it *easy* to write

  dependable programs.  Things like variable scope, string manipulation and

  exceptions are not to be sneezed at.

But I wrote an aba command!

  Fai supports aba's external commands, which make up 78% of the aba tree

  anyway.  So Fai (like aba) is extensible in any language, but Python commands

  have full access to Fai's tools.

What about pyaba?

  Fai is just a new name for pyaba.  I hate programs that are named for their

  programming language.  The language is a tool, not your program's 

  raison d'etre.  (If the language *is* your program's reason for being, don't

  write it!)  On the other hand, PyArch makes sense, because it's Python-

  specific.

HANDY HINTS

Working around Fai's limitations as a shell:

When using Fai in shell mode, you'll find it's not as powerful as, say, Bash.

This is because I don't really want to rewrite Bash.  It's hard to find the

right balance.  So you'll occasionally want to force Fai to pass commands

through the system shell.  You can do this by writing the commmands as Fai

invocations.

Normally, you'd do

> alias foo bar@baz--2004/meep--mope--0

But if you want to use the tree-version, you can do:

> fai alias foo $(tla tree-version)

Also, Fai commands mask real system utilities, notably diff and mv.  To invoke

diff from Fai, just quote it:

> "diff" file.old file.new

You can also use pathnames:

> /usr/bin/diff file.old file.new

To import the latest vendor changes from a tarball:

  1. untar the tarball and cd to the directory

  2. $ fai init-tree VENDOR-VERSION

  3. $ fai revert --control-files --revision acur

  4. $ fai add-ids --untagged

This will update the control files.  You may also want to branch at this point.

LIMITATIONS

the tdate alias behaves strangely if no day is specified.