← Back to branch summary

~abentley/bzrtools/bzrtools.dev

« back to all changes in this revision

Viewing changes to fai/aba/README

  • Committer: Aaron Bentley
  • Date: 2007-06-11 05:08:34 UTC
  • Revision ID: aaron.bentley@utoronto.ca-20070611050834-wcbta2pfitcuopku
fix long-line detection

Show diffs side-by-side

added added

removed removed

Lines of Context:
fai/aba/README
1
 
aba
2
 
===
3
 
A while back, there was a suggestion that we make arch extendable with
4
 
shell scripts.  I thought the idea was neat, but Tom was having none
5
 
of it.  He felt that we could just write wrappers around tla to achive
6
 
the same effect.
7
 
 
8
 
Well, I think he was right.  aba is a stupid-simple arch wrapper I
9
 
wrote, which I have named, with all due humility, Aaron Bentley's Arch. 
10
 
 
11
 
You can use it to add new commands, set default options for any command, and
12
 
create short aliases for long tla archive/category/version/revision names.
13
 
 
14
 
Installing aba
15
 
==============
16
 
cd to ~/bin or /usr/local/bin
17
 
Create a symlink (ln -s) to the aba script
18
 
 
19
 
Why that works
20
 
==============
21
 
The main script looks for default options in <installdir>/options and
22
 
~/.aba/options.  Then it looks for files in <installdir>/commands and
23
 
~/.aba/commands, and executes them if they exist.  Otherwise, it executes
24
 
tla.  It finds <installdir> by looking at its $0, resolving it if it's
25
 
a symlink.  So it can be installed by just linking somewhere in path.
26
 
 
27
 
Command Scripts
28
 
===============
29
 
To list available scripts, type "aba help".  This lists both tla and aba
30
 
commands.
31
 
 
32
 
Technically, command scripts should support the following arguments:
33
 
exec $* Does whatever the script does
34
 
exec -h Prints brief help
35
 
exec -H Prints detailed help
36
 
desc    one-liner description of the script's function
37
 
 
38
 
Non-interactive commands should normally pipe their output through $ABAFILTER.
39
 
 
40
 
But I find it's easier to just copy aba/skel-command, and follow the comments.
41
 
 
42
 
Default Options
43
 
===============
44
 
Both tla commands and command scripts are executed with the options in the
45
 
appropriate options file prepended.  Options files contain only the default
46
 
options desired.  Aliases are treated as separate commands.  The filename
47
 
should be the same as the command they are for.
48
 
 
49
 
An example is provided that prepends '--diffs' to 'what-changed'.
50
 
 
51
 
Aliases
52
 
=======
53
 
Aliases can be used to reduce the amount of typing required by certain
54
 
commands.  Aliases can be defined in ~/.aliases like so:
55
 
 
56
 
tom=lord@emf.net--2004/tla--devo--1.2
57
 
 
58
 
Or you can use "aba alias" to list or add aliases
59
 
 
60
 
I've just added support for per-tree aliases, like Stefan Monnier wanted for
61
 
tla.  To create them, you'll need to create a file named ++aliases in the tree
62
 
root.  Sorry, "aba alias" doesn't support them yet.
63
 
 
64
 
They can then be used on the command line like this:
65
 
aba get ^tom--patch-35
66
 
(the ^ can be overridden by defining an alias
67
 
aliaschar=<whatever-character-you-want>)
68
 
If you need to inhibit alias processing, prepend the character twice -- ie.
69
 
^^. Aliases are disabled completely when you define aliaschar to empty.
70
 
 
71
 
While the intended use for aliases is to reduce the number of branch names
72
 
typed, alias expansion is applied to all command arguments, so you can get
73
 
creative with them if you like.  Please don't put anything other than simple
74
 
variable assignments in the file.  Pretty please.
75
 
 
76
 
Filtering output
77
 
===============
78
 
aba can optionally pass its output through a filter.  To select this filter,
79
 
export a variable named "ABAFILTER", with the command to be used.  An obvious
80
 
example would be export ABAFILTER="aba colorize", but less, more and other
81
 
output filters can be used.
82
 
 
83
 
Interactive aba commands (e.g. those that may invoke $EDITOR) are not filtered.
84
 
All tla commands are filtered, but $EDITOR is unset before invoking tla with
85
 
a filter.
86
 
 
87
 
aba's web site
88
 
==============
89
 
Check out all the latest info, screenshots and Winamp themes at the web site:
90
 
http://sourcecontrol.net/~abentley/aba.php
91
 
 
92
 
Comments, suggestions, and scripts are welcome.
93
 
 
94
 
Aaron
95
 
 
96
 
Aaron Bentley
97
 
abentley@panoramicfeedback.com