• 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 the tla's slightly different semantics.

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.

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 set-tree-version ver && \ tla sync-tree rev && tla undo

  
  
• 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"

(Question: in the equivalent to the "cvs update -r rev", is the tla "ver" something special, or is it simply a typo for "rev"? If it's not a typo, is it the literal string "ver", or is it meant to mean some other version, distinct to the version tagged "rev" in the CVS example? Some more explanation might be needed.)

FIXME: This is too complex. The common operation in both CVS and tla is to just get the most recent revision on a particular version. That's what we should document first. Getting a particular old revision is a more advanced/uncommon operation.

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 ...

  
  
• 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.

Miscellaneous

Some description of other CVS features might be sensible here - especially, CVS modules. E.g. in Arch, how can you "link in" a separate module, as you can via the CVS modules file of aliases?