• Learning Arch commands for CVS users

Learning Arch commands for CVS users

This text is supposed to guide you through the transition from CVS to Arch for simple cases and make you aware of possible problems that you may run into. The biggest value may be contained in the one-to-one comparisons of cvs to tla commands. You are however encouraged to read through the additional remarks as well to make sure you don't get hit too hard by tla's slightly different semantics.

Contents

Versions and Revisions

A note on terminology: In CVS and Subversion, people tend to use the words revision and version loosely and interchangeably. In Arch, they have defined and specific meanings. A version is like a branch driving towards a new public release of the project. So where you might have a SAMBA_2_2 branch in CVS, you would have a samba--main--2.2 version in Arch. Within this version, revisions are the atomic steps of the tree, starting at base-0 and going up. Revisions are the closest correspondent to CVS or Subversion file versions.

In CVS it is common to do most work on the trunk and make branches only when strictly necessary, partly because working with branches in CVS is pretty painful and error-prone.

Arch makes it pretty easy to make new versions, so the general practice is that when you go from working on fooix 1.1 to fooix 1.2, you will create a new version for it. If, as on most smaller projects, you maintain just a single stream, then you will do this when 1.1 goes out, and then stop committing to the 1.1 version. Doing this is just for human convenience and clarity -- it doesn't really have any technical or performance consequences.

If you don't want to do this, you can just put everything in a version labelled "0". That might be appropriate for projects that never do public releases. If you just want a simple trunk rolling along with no punctuation, as is the default in CVS and Subversion, do all your work on fooix--main--0.

Identify yourself

• cvs	tla
  	tla my-id "John Doe <john@example.com>"

• CVS always identifies you just by your login name on the CVS server. Arch lets you specify your real name and your choice of domain name.

This is stashed in ~/.arch-params. You only need to do it once per machine/home directory. You don't have to use a real email address, but please be sure that what you choose is unique world-wide.

Creating an archive

• cvs	tla
  cvs -d ~/myarchive init	tla make-archive john@example.com--myarchive ~/myarchive
  export CVSROOT=~/myarchive	tla my-default-archive john@example.com--myarchive

  
  
• Arch refers to repositories by name, not by location. An archive name is your email address, then two dashes, then an arbitrary identifier chosen by you. You should be prepared to have several archives, because huge repositories tend to be harder to handle. Some people have one archive for each year. Don't worry, it's easy to carry over revisions from one archive to another: You just tag your project from the old archive into the new one. (In Arch, tagging "doesn't do much" besides create a "symbolic" revision for another one that's stored somewhere else.)

• ~/myarchive above could easily be sftp://myuser@host.com/path/to/archive or even http://example.com/path/to/archive. tla doesn't need a dedicated server, any "stupid" file server, sftp, webdav or even ftp is enough. Even better: all you need to host a read-only archive is a bit of webspace.

Your default archive is also remembered in ~/.arch-params.

As with CVS, each Arch working directory remembers the archive/server and module/version that it's associated with. So in both systems, you don't need to worry about this when re-entering a working directory, only when getting or importing a new one.

Importing a version

• cvs	tla
  cvs import hello andreas initial	tla init-tree hello--dev--1.0 tla add file... tla import -S
  ls CVS/	ls {arch}/

  
  

• Arch imposes a namespace scheme onto your archive, it consists of category--branch--version. You would create a category for each project, a branch for each independent development effort within the project (like stable and development) and within that, a version for each release that you're independently supporting. If you find this awkward right now, think about it for a week, and you'll like it. It remains to say that together with the archive name, something like john@example.com--myarchive/hello--dev--1.0 is a globally unique identifier for a version, and is called a fully qualified version name.

• If you habitually use .cvsignore files, you're in for a bit of a surprise. Unlike CVS, tla complains when it doesn't know whether to archive a file or not. This means that you can't just dump all your temporary files in the project directories and expect tla to not complain (like you could with CVS, it would just issue a "? whatever_file" warning at update and commit time). A quick trick is to start the names of temporary files with plus signs. Files with such names are automatically precious (but not source). Should you really need to have temporary files, the equivalent of .cvsignore is a set of regular expressions in {arch}/=tagging_method for tree-wide rules, and .arch-inventory in each directory of the source tree. You'd want to edit the regular expression following the precious keyword.

• After you are done with this, the directory you've just imported is a fully-fledged working directory with no need to re-checkout like with CVS.

Getting a revision

• cvs	tla
  cvs -d :server-info:/path/to/cvsroot \   checkout -d hello-1.0 -r 1.17 hello	tla get archive-name/hello--dev--1.0--patch-17 hello-1.0
  cvs update -r rev	tla update rev

  
  
• One thing to note here is that revisions in tla are always whole-tree revisions. It starts out with a base-0 revision, goes on to patch-1, patch-2, patch-3 and so on.
• You can have a default archive, just like you can have a default CVS root.
• Somebody asked on IRC about the missing "cvs co" equivalent. FYI, this is a shortcut for "cvs checkout".

• When you want to get revision on other computer (e.g. remote host), you have to first register archive: "tla register-archive remote_archive"

Making modifications

• cvs	tla
  cvs add file...	tla add file...	(in tla, only needed for explicit tags)
  cvs delete file...	tla delete file...	(in tla, only needed for explicit tags)
  	tla mv file1 file2	(in tla, only needed for explicit tags)
  cvs update	tla update
  cvs commit	tla commit
  cvs commit -m "log-message"	tla commit -s "log-message"

  
  
• To the seasoned CVS user, there are no big surprises here.
• Renames actually work and retain all version history.

• Commands such as add, delete, mv are only required in tla if you use the "explicit" tagging-method; if you use "tagline" tagging-method, tla will figure everything out for itself! See ID-tagging methods for more information on tagging-methods.

• When committing without a log-message specified on the command-line, both CVS and tla will allow you to edit a log message (tla starts your editor to do so). With tla it's also possible to create the log-file before you commit, using the tla make-log command; when you finally use tla commit, it will automatically notice the pre-created log file. This allows you to create a log file early on and just write down the changes as you go (note that tla make-log prints the name of the log file it creates, so for instance using vi you can try: vi `tla make-log`). tla also alleviates the need to write GNU-style changelogs -- They can be autogenerated from the log messages (see the tutorial for that).

Showing local changes

• cvs	tla
  cvs -n update	tla changes
  cvs diff -u	tla changes --diffs
  cvs diff -r 1.2 file	tla file-diffs file patch-2
  cvs diff -r 1.2 -r 1.5	tla delta --diffs patch-2 patch-5

  
  
• TODO: Comments/fixes needed.

• In CVS, the update command does three things: it lists updates to the current branch, retrieves them (without -n), and lists local changes too. tla update does only the first two things, but it also provides two separate commands to list differences: changes that only lists local changes and does not retrieve updates, and missing that lists futher revision names missing in the working tree.

• Diffs produced by tla commands changes, file-diffs and delta are always unified diffs.

Tagging and branching

• cvs	tla
  cvs tag ...	tla tag ...
  cvs tag release-1.0 .	tla tag -S $(tla tree-version) mysoft-release-1.0

  
  
• The whole topic of tagging and branching in tla is hugely different from CVS, and rightfully so, because this is where CVS fails miserably. There is one thing that you need to know:
  • All a tag does in tla is create an "alias" revision in your current tree for another revision somewhere else. Unlike tagging in CVS, this is a very inexpensive operation.

  CVS transition tips page has many examples of what that means. For example, to create a branch off someone else's source code, you just create a new version (e.g. hello--dev--1.0) and tag their source code into that new version. Your first revision will be exactly the same as their current one. As mentioned above, you just do the same thing, for example, when you change over from hello--dev--1.0 to hello--dev--1.2. Post-branch merging is easy, too, since tla has the advanced star-merge command that you may want to read up on. If you tag from somewhere else, you might want to read up on caching revisions, so your repository is independent of the original one and doesn't become unusable if the first one goes away. If you are uncertain about the difference between a version and a revision, consult the FAQ. Before you delve too deeply into this topic, it is probably advisable to actually read the tutorial.

Merging

• cvs	tla
  cvs update -j rev-1 -j rev-2	tla apply-delta patch-1 patch-2
  	tla star-merge
  	tla replay

  
  

• star-merge and replay are far more suitable than apply-delta for most merging scenarios.

• Conflicts are usually managed using .rej and .orig context diff files, not inline conflict markers.
• tla takes care of the bookkeeping about which revisions have been merged.

See Merging with Arch for more info.

.cvsignore

• cvs	tla
  .cvsignore	.arch-inventory
  generated_file	precious ^generated_file$
  *.x	precious \.x$

  
  

You may also want to use the junk keyword instead of the precious keyword for files you really don't care about, and that can be overwritten at any time by tla.

See section Customizing the inventory Naming Conventions of the tutorial.

.cvsrc

.cvsrc files are used to supply particular commands with preferred default arguments.

However there is no such equivalent in the tla implementation of Arch. RobertCollins has indicated that tla won't create .rc files and that he believes that is the job of wrapper programs such as aba, raw, payba and xtla to take of this functionality instead.

Keywords in source

Unlike CVS, arch does not implement keywords substitution in source files. This is a deliberated choice (taken from this discussion) :

• It means the commit operation must modify the source files, during what really should be a read-only operation. This in turn implies you have to reload any open source files in editors you might have running.
• It causes problems for diffs and merges unless you hack these operations to ignore keywords. Subversion has even more hacks(?) to deal with this[1].
• It breaks revision libraries (forcing them to either no longer have like versions hardlinked or convert the substitution tags in/out whenever copying anything to and from). It breaks every hardlink-based optimization. It requires touching files which would be otherwise completely untouched (making a one-file tla update touch every other file in the repository).

Miscellaneous

Some description of other CVS features might be sensible here - especially, tla configs versus CVS modules.