← Back to branch summary

~abentley/bzrtools/bzrtools.dev

« back to all changes in this revision

Viewing changes to fai/README

  • Committer: Robert Collins
  • Date: 2005-09-13 10:46:27 UTC
  • mto: (147.2.6) (364.1.3 bzrtools)
  • mto: This revision was merged to the branch mainline in revision 324.
  • Revision ID: robertc@robertcollins.net-20050913104627-51f938950a907475
handle inaccessible sibling archives somewhat - note version-0 is still not handled

Show diffs side-by-side

added added

removed removed

Lines of Context:
fai/README
 
1
FAI (The Friendly Arch Interface) 0.2 (aka pyaba)
 
2
 
 
3
Fai is a commandline-based Arch tool with interactive prompting.  It aims to be
 
4
a better commandline user interface than tla.  By combining functionality
 
5
that is handled as separate commands in tla, it aims to have smaller command
 
6
set than tla.
 
7
 
 
8
Quick Start (or "Where's the documentation?")
 
9
  Most of the documentation currently available for fai is accessed through
 
10
  inline documentation.
 
11
 
 
12
  To see all the available commands:
 
13
    
 
14
        $ fai help
 
15
 
 
16
  To get help on a specific command you, use either of these:
 
17
 
 
18
    $ fai help COMMAND
 
19
        $ fai COMMAND --help
 
20
  
 
21
  Also, see the HANDY HINTS below.
 
22
 
 
23
  There's also a web site: http://sourcecontrol.net/~abentley/fai/
 
24
  But it's focused more on programming Fai than on using it.
 
25
 
 
26
What's there now?
 
27
  * Compatibility with aba commands
 
28
  * Alias expansion (no prefix required for native commands)
 
29
  * Automatic aliases; these determine the revision by performing functions
 
30
  * tla fallthrough (to be removed when redundant)
 
31
  * smart colorizing (which can be turned off)
 
32
  * prompts that can be configured to take defaults
 
33
 
 
34
  Commands: ('fai help -n' for a full list)
 
35
  * get: an improved get that can use URLs and automatically create local 
 
36
         mirrors.
 
37
  * revisions: a combination of logs, missing, revisions, cachedrevs, etc.
 
38
               also provides:
 
39
                 --missing-from (which of my revisions are missing from the 
 
40
                 target?)
 
41
 
 
42
                 --modified (which revisions modified this file?)
 
43
                 --ancestry (iterates through the tree's patchlog ancestry)
 
44
  * commit: prompts on empty commits, missing log messages
 
45
  * update: updates to the requested revision, while retaining local changes.
 
46
            prompts to change tree version.
 
47
  * revert: undo command that can undo specific types of changes
 
48
  * changes: can take two arguments, making delta redundant
 
49
 
 
50
What's coming soon?
 
51
  More native implementations of the common commands.
 
52
  An init command that will do my-id, make-archive, archive-setup, init-tree
 
53
  Option defaults are high on the list, too.
 
54
 
 
55
Aren't you that guy who wrote that aba thing?
 
56
  Yeah.  aba's nice and all, but POSIX shell isn't my favourite language.  It's
 
57
  not geared at producing reliable, unambiguous programs.  I won't say 
 
58
  "impossible", since the original Arch implementation was in shell.  Python
 
59
  (like many other languages) has facilities that make it *easy* to write
 
60
  dependable programs.  Things like variable scope, string manipulation and
 
61
  exceptions are not to be sneezed at.
 
62
  
 
63
But I wrote an aba command!
 
64
  Fai supports aba's external commands, which make up 78% of the aba tree
 
65
  anyway.  So Fai (like aba) is extensible in any language, but Python commands
 
66
  have full access to Fai's tools.
 
67
 
 
68
What about pyaba?
 
69
  Fai is just a new name for pyaba.  I hate programs that are named for their
 
70
  programming language.  The language is a tool, not your program's 
 
71
  raison d'etre.  (If the language *is* your program's reason for being, don't
 
72
  write it!)  On the other hand, PyArch makes sense, because it's Python-
 
73
  specific.
 
74
 
 
75
HANDY HINTS
 
76
 
 
77
Working around Fai's limitations as a shell:
 
78
 
 
79
When using Fai in shell mode, you'll find it's not as powerful as, say, Bash.
 
80
This is because I don't really want to rewrite Bash.  It's hard to find the
 
81
right balance.  So you'll occasionally want to force Fai to pass commands
 
82
through the system shell.  You can do this by writing the commmands as Fai
 
83
invocations.
 
84
 
 
85
Normally, you'd do
 
86
> alias foo bar@baz--2004/meep--mope--0
 
87
 
 
88
But if you want to use the tree-version, you can do:
 
89
> fai alias foo $(tla tree-version)
 
90
 
 
91
Also, Fai commands mask real system utilities, notably diff and mv.  To invoke
 
92
diff from Fai, just quote it:
 
93
> "diff" file.old file.new
 
94
 
 
95
You can also use pathnames:
 
96
> /usr/bin/diff file.old file.new
 
97
 
 
98
To import the latest vendor changes from a tarball:
 
99
 
 
100
  1. untar the tarball and cd to the directory
 
101
  2. $ fai init-tree VENDOR-VERSION
 
102
  3. $ fai revert --control-files --revision acur
 
103
  4. $ fai add-ids --untagged
 
104
This will update the control files.  You may also want to branch at this point.
 
105
 
 
106
 
 
107
LIMITATIONS
 
108
the tdate alias behaves strangely if no day is specified.