# Tom Lord's (temporary) GNU Arch Page

Yes, it's the dreaded under construction page. If you're here to find some information about GNU Arch that is customarily found on this page, here are some links to popular pages. Below that, a brief note about what's going on behind this site (why it's under construction and what it will be like shortly).

Note:Most of these links take you to mirrors of the old site that used to be here.

- The old top-level page -- if you are looking for an old link not listed below, try looking here.
  http://regexps.srparish.net/www
- "What is Revision Control" -- a neutral description of what revision control is (not Arch specific although, obviously, reflective of the perspective of Arch's designer).
  http://regexps.srparish.net/www/revctl-intro.html
- "An Overview of GNU Arch" -- a brief list of (some of) the features that most distinguish Gnu Arch from competing systems.
  http://regexps.srparish.net/www/arch-overview.html
- "How Arch Works" -- a high level description of exactly what arch is and does. If you're like me, the necessary vagueness of an "overview" like the previous link can be tantalizing but frustrating. This short paper tries to give programmers and other technical types a slightly deeper picture.
  http://regexps.srparish.net/www/arch-tech.html
- "A Tutorial Introduction to The arch Revision Control System"
  http://regexps.srparish.net/www/tutorial/html/arch.html
- The user community wiki -- not something I help to maintain at all but (or therefore :-) a popular alternative to the tutorial. Also a forum where people work on new ideas and designs for improvements to arch.
  http://wiki.gnuarch.org

## So.... what's up with this site, then?

To understand what's up with this site it's helpful to understand my motivation for the behind-the-scenes work I'm up to. My motivation is based on a (hopefully accurate) contemplation of the strengths and weaknesses of GNU Arch:

### Some Tools are Better than Others --- But What Does that Mean?

For the discussion here, and ignoring (briefly) certain larger philosophical issues about the broader impacts of tool design, we can start from this:

> A good tool is one which, when given to a craftsperson, expands that person's "reach" within their chosen craft. I'm using "reach" as the name for what that craftsperson can reasonably accomplish given a fixed amount of other resources, such as time.

For example, higher-level, machine-independent programming languages are often good tools tools because they can allow programmers to more easily and more accurately write programs than if only assembly language is used. The C language may be arguably a better such tool than the otherwise comparable Bliss language because it is more widely ported and compilers for C have received far more attention over the years, making C the more reliably useful tool to reach for in most circumstances.

Another example: modern revision control systems seem to be demonstably better tools than older revision control systems because (in part) they make branching and merging easier --- thereby enabling programmers to cooperate with one another with greater control and greater ease.

### The Strengths of GNU Arch

In that light, Arch has plenty of strengths. Most readers know the "feature list" (e.g., best-of-breed branching and merging capabilities; good support for detached (from a network) operation; good distributed development support....)

I won't rehearse the "brag list" further, here, except to say that the core functionality of arch already has plenty of programmers doing far more sophisticated things, at significantly higher "scales" (problem sizes) than they could have sanely attempted without Arch (or something very much like it).

### The Weaknesses of GNU Arch

For all its goodness, as a tool, arch has its share of weaknesses.

One weakness is that Arch's availability on Windows is quite shaky, at the moment. That isn't the reason for changes to this site but I mention it so that people don't think I'm ignoring that problem.

Another weakness of Arch, the one of greatest concern here, is what I would call the fancy tablesaw problem. A tablesaw, in woodworking, is a powerful electric motor, attached to a spinning circular blade, mounted below a precision-milled table in such a way that the edge of the blade pokes up through the table. When the blade is spinning, anything that is passed over this part that pops up through the table will be cut. Pieces of wood can be placed on the table, securely braced in various ways, run against the blade -- in this way, a variety of precision cuts can be made. Experts can use such saws to create, in minutes, all manner of clever woodworking contructions that would otherwise be impossible or at least nearly so.

The fancy tablesaw problem is my name for two issues with a fancy tablesaw:

- Tablesaws Are Dangerous -- The inexperienced and under-trained user is extended ample opportunity to ruin his woodworking project very quickly (by making a bogus cut). Tablesaws are also great for causing yourself nasty personal injuries with just a second or so of inattention.
- Fancy Tablesaws are Confusing to Newbies -- A fancy table saw will come with a non-trivial number of attachments, adjustment controls, blade options, and so forth: lots of knobs and swappable parts, in other words. In software terminology: lots and lots of "input parameters" for every cutting operation. There is an entire micro-industry dedicated to publishing books, videos, and so forth just to explain useful ways to configure a fancy table saw. At the same time, if you drop a new user in front of such a saw, even giving them a reference manual for the configuration options -- it will take them lots of time and lots of trial and error to learn to use it well.

Arch suffers (somewhat needlessly) from its own analog of the fancy tablesaw program. Although powerful and flexible in the hands of an experienced expert, to the newbie it is all too often a confusing array of many, many parameters. Newbies who fail to seek good advice about Arch can easily botch their attempts to use arch. Even given the reference documentation --- newbies working on their own stand almost no chance of discovering many of the best ways to use Arch in practice.

What can we do about that?

### Two Wrong (but Popular) Answers

I often get two kinds of suggestion for how to solve the "fancy tablesaw problem" for Arch, both of which I reject:

- Remove Features -- Too many ways to merge? Too many parameters? Why not take some out?

  I don't often get that as a literal suggestion -- few users (most of whom are programmers) would make that suggestion with a straight face. But sometimes the kibbitzers, not seeing the reason for this or that arch sub-command are parameter, argue that it can be thrown away.

  Of course, I reject this solution because even though it would help newbies during their first exposure to arch, more experienced users would lose capabilities. To go this route would be to make Arch a tool that grants less "reach" to its users -- it would make it a less good tool.

- Optimize the UI for the Common Case -- Many suggestions ask that the value of a given parameter, currently one that has to be supplied "by hand", be made a default.

  That's a great rule of thumb but it is often misapplied in the cases I get suggestions about.

  The problem is that, more often than you might think, one user's "exceptional case" is the next user's "default case":

  > If you push in here it pops out there: changes to parameter defaults which satisfy one group of user's will often inconvenience another group who likes the current defaults.

### The Plan (as relates to this site) -- Getting Past the Tablesaw Stage

To review: arch is a leader in its field when it comes to the "reach" that it grants expert users --- a laggard when it comes to helping newbies get on board. Above, I created an extended analogy between arch and a "fancy table saw" -- both are in some sense dangerous and the input parameters they offer can overwhelm newbies.

I will now put aside the tablesaw analogy and offer a new one: the industrial manufacturing equipment problem.

By "industrial manufacturing equipment" I mean the family of machines that you might find in an industrial shop. For example, the massive-scale mixers and ovens you might find in a cookie factory are examples of industrial manufacturing equipment.

Industrial manufacturing equipment has the interesting property that it has to be newly and creatively deployed for every factory that will use it. The builder of the equipment has solved a general problem -- but when it comes time to install that solution in a specific factory, additional customization is often (not always) necessary. If you would like to read a bit about that (and about some social implications of tool design) I suggest the article Food Plant (at www.kuro5hin.org): a report from someone whose career has included selling industrial manufacturing equipment for food processing.

The field of industrial manufacturing equipment has come to grips with and aggressively works on solving the "fancy tablesaw problem". The factories using this equipment often use workers with a very narrow range of skills in relation to the tools. Experts configure the tools for a given factory but, once configured, a new user of the tool can be completely trained in its use in a matter of minutes.

Such narrowly-skilled user's are typically not qualified to, for example, reconfigure a factory to make tarts instead of cookies --- but they can learn and settle into their cookie-making roles without having to become experts in the field of manufacturing equipment generally.

> Arch should grow to become more like industrial manufacturing equipment in the sense that the task of configuring lots of complicated parameters is separated from the task of using the machine day-to-day. In this way, at least within each shop (or, really, each

> type of shop), newbies can learn what they need to know quickly and get started working with very little training.

To that end I have started working on `gtla`, which is a new "front-end program" to arch: an alternative to using the program `tla` directly.

`gtla` will initially be a command line program, just like `tla`. In fact, the prototype contains the entire `tla` command set as a subset of its own commands.

`gtla` will first add some new commands, tailored for the particular "industrial shop" which is the GNU Arch project itself. In other words, given gtla, if a new "line worker" were to join the GNU Arch project, I will be able to train them in what they need to know about arch very quickly, just by teaching them a small subset of the `gtla` command set. My informal goal is that everything a newbie needs to know should fit on a reference card, small enough to sit next to a keyboard.

`gtla` will next develop the holy trio:

- Self-documentation
- Customizability
- Extensibility

Those mean:

- Self-documentation: on-line documentation should be convenient, context sensative, and easy to author and extend.
- Customizability: it should be easy to configure gtla by changing the default values of key parameters in a site-specific way. The software part of an "arch shop" should largely be defined just by a small amount of configuration files which set shop- (or project-)specific parameters.
- Extensibility: The new commands `gtla` adds for the GNU Arch project (shop) itself are all quite trivial --- I'm implementing each in the prototype as just a few lines of shell script. In the longer term, `gtla` will concentrate on making such new commands easy to create (and easy to include within the features for self-documentation and customizability).

`gtla` will additionally develop (or integrate with) some non-CLI interfaces. Overall, `gtla` is mostly concerned with UI issues. Therefore, it will grow to include a comprehensive and interface-technology-independent model of user interaction. For example, `gtla` will model each command as a data structure which describes its parameters and options in detail and which includes documentation for these. That data structure can be used to "drive" any kind of interface: CLI, GUI, Web-based, or otherwise. In this area, `gtla`, is likely to borrow heavily from some underappreciated aspects of the design of GNU Emacs (and traditional lisp-based interactive systems generally) --- namely those design aspects that are key to the success of Emacs (et al.) at producing a self-documenting, customizable, extensible program.

There is more to the current conception of `gtla` than simply to parrot some features of Emacs, though....

### A Programmer's Blog

Over the coming weeks, I intend to adopt `gtla` myself, for my everyday revision control needs. That is, I will start using the `gtla` front-end rather than directly using `tla` itself.

I intend to extend `gtla` by adding features which will help me to maintain a programmer's blog: an on-line diary for arch-using programmer's. That's what this site will evolve into: a `gtla`-managed blog.

"Programmer's blog" is my name for a tool that helps a programmer to journal, document, and communicate his hacking efforts --- it is a an organizational tool, like a labbook or business diary.

Perhaps you've seen a very methodical programmer work (or are one yourself) who sits with a traditional, paper labbook by your terminal and documents carefully every significant hacking step you plan or take. I've known managers who kept personal databases of release-candidate benchmarks that way (not to mention all the usual PHB stuff about who's supposed to be doing what, when). I've known "line coders" who kept a personal database of issues assigned and fixed that way. That sort of thing.

From such a notebook, if it is thorough, many of the demands upon a programmer for personal organization and ability to communicate work status to others can be pleasantly satisfied. I would see, for example, that manager writing a complicated technical email to the team essentially by typing in excerpts from his notebook. That line coder, asked for a weekly status update, could just read down his list of issues fixed --- the notebook was perfect for making notes such as "fixing issue X was necessary for contract Y which is due on Tuesday".

In my various roles regarding Arch, Pika, and other projects, I find that (a) it's not very convenient to keep such a traditional notebook, largely because there are always overdue high-priority tasks (so I don't really do it); (b) nevertheless, i find myself both generating (on-line) what would make ideal content for such a notebook, and wishing later that I had that content better organized so that it was at least as useful as an actual notebook. For example, I'll write a few paragraphs for a commit message. Later, I'll rewrite essentially the same content for one or more emails. Later still I'll rewrite it a third time to put on a web site. All of these rewrites occur because it would be too expensive to go searching for the previous version, yet the rewrites themselves do take a lot of time.

So a "programmer's blog", then, will be a simple, arch-hosted database, designed to capture useful content (like significant commit logs) from a programmer, and help the programmer (and possibly others) organize and acess that content.

In a web site form, the programmer's blog idea is a bit more concrete. For example, some features I'd like to see on this page are:

- Latest Interesting Commits -- I work on several different arch archives and several projects. Some of the revision control "`commit`s" that I do for those projects are more interesting than others: a spelling fix to a help message is boring; a new module added to hackerlab is more interesting. I'd like this front page to list the summary lines and dates of my 10 most recent commits, to any project, where I put the string "`[MILESTONE]`" in the "`Summary:`" header. There should be links to full patch logs, changesets, and trees for these commits.
- Pending Merge Requests -- Nowadays, to get anything merged into the GNU Arch mainline (which happens to also contain my preferred branch of the Hackerlab C library) I have to prepare and submit a merge request to the integration manager, just like everybody else.

  `gtla` applies very regular naming conventions to contribution branches and understands the `./=merges` convention used in the GNU Arch project: I plan to teach `gtla` to display on this page lists of my contributions-recently-merged and lists of contributions-pending (with links to the "`./CONTRIBUTION-LOG`" files and so forth).

- The Usual Diary Entries `gtla`'s web-blog features will comprise, in essense, a highly specialized "viewer" for my collection of archives. For example, the "latest interesting commits" display is a specialized view of the list of revisions in this archive.

  The usual blog-ish diary entries (a running collection of short-items, posted by the blog owner) can be modeled as a GNU Arch version --- log entries for the commits in that version containing the successive diary entries.

- A Personal, Free-form Wiki To organize notes taken in relation to some long-standing topic (rather than notes found in diary entries and other commit logs), I'll add support for displaying a simple and flexible personal wiki from the latest revision of a specially named version in my archives.

...etc. It's easy to imagine many other features: links to "bug goo"; support for email archives; gateways to and from email; and on an on, no one of which seems at all difficult to implement.

### Programmer's Blogs and an Industrial Revolution?

How do `gtla` and a personal blog relate to the idea of solving the industrial manufacturing equipment problem?:

> Arch should grow to become more like industrial manufacturing equipment in the sense that the task of configuring lots of complicated parameters is separated from the task of using the machine day-to-day. In this way, at least within each shop (or, really, each

> type of shop), newbies can learn what they need to know quickly and get started working with very little training.

Initially, `gtla` will be a tool that anyone can use to play roles like those that I play. Especially, if someone wants to become a contributor to the GNU arch project itself, `gtla` will lower their learning curve, get them going very quickly, and help them to produce very professional and standard output for consumption by the upstream integration manager. I need those features -- that's one of my current prominent itches -- so I may as well code them up in a way that makes my solutions useful to others.

Ultimately, there are then (at least) two directions in which to generalize `gtla`.

In one direction, greater generality, `gtla` can simply be made more parameterized (customizable) and exenstensible. While my solutions might be optimized for the GNU Arch project, someone else might configure `gtla` to be perfect for, say, working on the Samba project.

In another direction, expanded focus, `gtla` can be extended with features for upstream hackers. For example, in addition to helping people who want to be (leaf node) contributors to GNU Arch, `gtla` can gain features to help Matthew, upstream, who collects changes from those leaf nodes and manages the mainline.

Extensions in the two directions can be complementary. For example, an upstream maintainers radar screen front-page box might link to those changes he intends to merge soon --- they can contain links to the contributor's blogs. Or: an upstream project might display on its blog a downloadable `gtla` configuration -- the optimal parameter settings for interacting with that particular project.

To complete, perhaps torturously, the analogy: `tla` is, pretty much, the essential guts of an ideal industrial strength revision control system. `gtla` will be the flexible, lego-brick-style, assemble-in-the-field technology for making custom UIs to arch at each site of deployment.

Of course, a few common cases (the basement-hobbiest hacker; the small business hacker; the "typical" freshmeat-project maintainer) may very well be covered by just a few "standard" `gtla` configurations --- hopefully many people will never have to, themselves, hack such configurations (they can think of them as "skins" and download their favorites.