Juggle CVS Quickstarter (Unix)

CVS comes with extensive documentation in "info" format, generally just called "the Cederqvist" after its author. Since it also covers the administrative tasks required to create and maintain a CVS repository, it has over 100 pages and can make a tough reading for someone who just wants to use an existing repository server.

The following steps show you quickly how to connect to the CVS server at juggle.gaertner.de, to retrieve a small package for demonstration purposes, and commit your changes back to the master source.

Checkouts and Committing Changes

1. Make sure you are connected to the Internet; you should be able to
   ping juggle.gaertner.de.
2. cd to/some/place/where/you/can/write
3. cvs -d :pserver:cvsdemo@juggle.gaertner.de:/usr/local/cvs login

   The long string after the -d is the exact specification of the repository where "official master sources" are kept. The spec mentions:

   pserver

   the access method (password protected via TCP/IP)

   cvsdemo

   the account used to access the files and identify your changes

   juggle.gaertner.de

   the server hosting the repository

   /usr/local/cvs

   the path to the complete repository on the server

   You'll be asked for a password. For "cvsdemo", it's "fumpen". cvs will connect to juggle and verify the password. If that succeeds, the password will be stored in your ~/.cvspass file and automatically be used whenever you access that repository again.

   If you have trouble to login, contact me (neitzel@gaertner.de) to arrange for a little more handholding.

   Generally, one does not check out an entire repository (which may be huge). Instead, one accesses just files or specific directories from a repository. Meaningfull subsets are usually predefined and called "modules". Our next step will query the modules defined at juggle:

4. cvs -d :pserver:cvsdemo@juggle.gaertner.de:/usr/local/cvs checkout -c

   A list should be displayed. The line with "j-demo" refers to a small set of demo files in the repository. Remember the module name: "j-demo". Also remember the "-d poetry".

5. cvs -d :pserver:cvsdemo@juggle.gaertner.de:/usr/local/cvs checkout j-demo

   This will get a copy of the "j-demo" module. A subdirectory "poetry" created if it's not already there. (Make sure the latter is indeed the case.) The "-d poetry" from above is responsible for this.

   When the transfer is completed:

6. cd poetry

   You will find all the files belonging to the "j-demo" module. In addition, there is a "CVS" subdirectory. It is used by cvs to store administrative infomation like version numbers and so on. You generally don't touch anything in there.

   Most importantly, the CVS subdirectory remembers the original repository location for you. For this reason, you don't need to use the -d :pserver:/cvsdemo@juggle.gaertner.de:/usr/local/cvs with further cvs commands once you are working with your copies.

   Note the version number of the "limerix.ijs" file. You can check this by invoking a simple

7. cvs status limerix.ijs

   The branch number "1.x" refers to the so-called "trunc". It is the working branch were most changes happen and side-branches fork off from.

   At this point, you would usually forget about CVS, and work on your copies for the next hours/days. There is no need for a "logout" corresponding to your initial "login". (Each cvs command uses a new TCP connection and password handshake with the CVS server; you are not holding a connection beyond each single cvs command.)

   If your Internet connection is just a temporary one, you could typically "pull the plug" now. But since this just a little exercise, we just stay connected to the Internet. You need the Internet access to juggle.gaertner.de for all of the cvs commands.

8. Edit the "limerix.ijs" file. Add a new stanza.
9. Re-check the status of all files: cvs status | more

   You'll see that the limerix.ijs file is now listed as "modified". To see the exact changes, use:

10. cvs diff limerix.ijs

    You'll see some lines in their "before" and "after" change variations.

11. cvs diff

    does the comparison for the entire directory (and any subdirectories) you are in. Most commands work this way when used with/without specific file arguments.

    Well, enough work on the new version for today, all works fine, that's a great big fix you made ==> put it back to the repository so everybody else can use the fruits of your labor:

12. cvs commit

    You'll be prompted for a message describing the change you made. One or two terse lines are usually enough. But do give a short description.

    There is a very small chance that somebody else already revised the demo files in the meantime. If the changes overlap, you'll be prompted to resolve the conflicts. Use cvs update to incorporate the external changes. Revise the files marked with "M", they are the ones requiring manual merging. This is usually straight forward. After the merge, you can have another go at a "cvs commit".

    OK. After the "commit" is completed, you'll see the file limerix.ijs at a higher revision number. A

13. cvs status limerix.ijs

    will list it as "unmodified" (because you are in sync with the repository, or rather, the repository is now again in sync with you.)

    Do another diff on limerix.ijs to see there are none anymore.

14. Give cvs log | more a try.

    This gives an overview about the revisions of a file.

Well, that has been *a lot* for Day 1.

How to proceed from here

There are basically two options how to proceed with your copy of the "j-demo" module:

1. If you do not need the copies for yourself anymore, you could simply remove them. A bit better would be to move one directory level up and to issue the command cvs -d :pserver:cvsdemo@juggle.gaertner.de:/usr/local/cvs release -d poetry. This would make some checks regarding any uncomitted changes and take care of notifying other developers if a module is configured for monitoring. A "cvs release -r" command just removes your copy. The master version in the repository stays. You can get a new copy anytime by issuing another "cvs checkout".
2. If you want to keep your copies, just do that. You can query the diffs, logs, and status anytime. The "cvs update" command will incorporate changes that others have made into your copy. It will even merge them with your yet uncommitted changes. Use a "cvs commit" whenever you some new, consistent changes in your version (a new stanza or a spelling fix).

You are welcome to make your own further experiments with the "j-demo" module. That's what it's for.

For example, try to add a new file to the repository. Try to diff your limericks against a specific date. Just stay away from things that mention "edit/unedit/lock/tag/untag/ watch/branch". This is because the "cvsdemo" account is shared by many people and therefore a bit special.

Accessing the J Repository

To access the proper J Repository, do not use the "cvsdemo" account. Instead, log in using the "anoncvs" account. The password is "cvs". It gives you read-only access to the files.

If you are contributing material to the J repository, you are welcome to mail me for your own, write-enabled account.

About the cvs info documentation

The entire "Cederqvist" you get with "info cvs" is a 115 page binder if printed out. You can skip much information on the more complicated tasks. If you made it through this tutorial, you should be able to separate the important from the not-so-important chapters quickly.

It is also very helpful to know that the "-H" option will give you quick summaries about cvs subcommands, their options, and the proper syntax. For example, have a look at cvs -H status to see all the details of that subcommand.