Arch naming conventions from a Layman's standpoint

One of the things that new arch users feel most uncomfortable with is some of the naming conventions that arch uses. These feelings are both reasonable and natural. Though these feelings are reasonable, take our word for it -- they are just feelings. If you work with these files for a couple of months, not only will you get used to them, but you will actually end up liking them. Trust us.

In particular, the feeling that arch inconveniences you by needlessly using shell metacharacters in filenames is just that -- a feeling.

The {arch} directory

One of the first things that people notice is that whenever a project is held within arch, each working tree has an  {arch}  directory (only one though, at the tree root, instead of one for every subdirectory as with CVS). Rather than hide the data directory by using a "dot file", we chose to make this directory clearly visible so that you could quickly tell whether or not any given tree was being managed by arch.

Why, then, did we decide to use  {arch}  rather than arch? There are several reasons. Most importantly, using an unusual name like this avoids namespace conflicts with a project's own files and directories (for instance, a linux source tree has its own arch subdirectory). In addition, the braces put the  {arch}  subdirectory at the end of a sorted directory listing, which helps avoid it being mistaken for a normal subdirectory (contrast this with "arch", which would show up after "CHANGES", but before "contact").

At first, the funny name is slightly disconcerting to users because they mistakenly think that they will need to dive into the  {arch}  directory on a frequent basis. In practice, however, very rarely will you actually need to go into the  {arch}  directory at all.

Names starting with "," and "+"

It is a widespread Arch convention that precious files be named with a leading "+" (plus) character and junk files be named with a leading "," (comma).

In the context of arch, a precious file is one that is important (and so care should be taken to preserve it), but should not be committed as part of an arch changeset -- so arch uses such names for files (in  {arch} ) that hold information that pertains to a particular project tree, but not to the project in general. A junk file is like a precious file, but is considered temporary information; arch uses such names to hold information it creates but which may safely be deleted, such as caches and temporary work files (but note that it won't delete any such files you create!).

Using these prefixes has several advantages:

Arch also sometimes creates such files in the project-tree root, in which case it doubles the special character just to make sure they don't conflict with user files; for instance, an as-yet-uncomitted log file (made with tla make-log) starts with ++, and the temporary changeset directories that many arch commands create, start with ,,.

If you overcome your reflex that all files should only contain [A-Za-z0-9._-] characters, you will find these conventions to be very convenient. Actually, according to TomLord, this naming pattern follows a very old Unix convention.

Files beginning with + can cause slight problems with some unix commands, such as vi and more -- they treat an argument starting + as an option (this usage is quite old and so unlikely to be changed!). Generally, this can be worked around easily, using the special "--" option to terminate option parsing, or by prefixing the filename with a leading "./".

Names starting with "="

Names beginning with "=" have a similar rationale (avoiding namespace collisions, sorting order) as with "+" and ",", but are considered source files, and so are put into the archive when you commit any changes.

An example of such a name that arch uses is the {arch}/=tagging-method file (it must not have a "normal" name because it is in  {arch}  and so could conflict with the patch-logs [see above], but is a part of the sources [should be committed] and so cannot begin with + or ,).

These names can occasionally be annoying, as due to a bug in bash filename completion (easily fixed, but not yet officially), it won't complete them unless you escape the = with a leading \.

FunkyFileNames (last edited 2006-03-10 14:51:47 by MichaelOlson)