2010-234 Tantek Çelik - originally drafted (with incremental updates since, e.g. 2011-081)
<html><div style=“width:50%;float:left”></html>
<html></div></html>
Setting up CVS and specifically, W3C's setup for CVS is quite challenging, obtuse, and painful.
Having failed to do this by myself, I took reasonably thorough notes while @fantasai and @davidbaron helped walk me through this setup, including trouble-shooting several problems I encountered along the way.
It is my hope that documenting the steps I had to take will help others get setup with CVS and editing W3C specs much more quickly and efficiently, and perhaps, in the long run, the process for editing W3C specifications can be made more efficient.
Tantek Çelik, 2010-236
If all you want to do is browse through W3C's CVS repository on the web, you can start here:
However, if you want to actually *check out* W3C's CVS repository (with the intent to make changes), the instructions/info on that page is a bit too cryptic for most folks.
That's why this document is here.
Before you get started with the setup steps, you need:
Send your public key file (id_dsa.pub) to Bert Bos. Until your public key file has been setup on the CVS server you will not be able to connect successfully using ssh.
You need to first install CVS on your system.
If you have a Mac:
The MacPorts installer will run a program to determine if it can be installed.
If you get an error alert like:
<html><pre> +—————————————————-+
| MacPorts-2.0.3 can't be installed on this |
| computer. |
| Xcode is not installed, or was installed with UNIX |
| Development (10.5+) or Command Line Support |
| (10.4) deselected. |
| 1) |
+—————————————————-+ </pre></html>
Then go back and make sure you've installed Xcode - you should have a “Developer” folder on your internal drive.
If you don't have a “Developer” folder on your internal drive, you probably haven't successfully installed Xcode.
If you have installed Xcode, make sure you've updated it to the latest version. You may need to check the Xcode page in the Apple Mac App store - if you see a button to “Update” or “Upgrade”, click it.
Now retry installing MacPorts again.
sudo port install cvs
If you get an error message like:
sudo: port: command not found
Then open a *new* Terminal window and try the command again:
sudo port install cvs
You will be asked for your “Password:” - enter it.
You should then see a bunch of messages like:
---> Fetching cvs ---> Attempting to fetch cvs-1.11.23.tar.bz2 from http://distfiles.macports.org/cvs ---> Verifying checksum(s) for cvs ---> Extracting cvs ---> Configuring cvs ---> Building cvs ---> Staging cvs into destroot ---> Installing cvs @1.11.23_0 ---> Activating cvs @1.11.23_0 ---> Cleaning cvs
Congratulations, you've installed the command-line cvs tool on your Mac.
For other platforms … tips forthcoming.
W3C requires you to use SSH to connect to their CVS server.
What does this mean? It means W3C only allows secure access to the CVS server - and thus you must setup SSH on your machine to act as the conduit for CVS.
The short version, type this into a terminal window (e.g. in the Terminal application on MacOSX)
export CVS_RSH=ssh
Now test that you did the right thing by typing in:
echo $CVS_RSH
You should see a message like:
ssh
followed immediately by a prompt.
You'll want to set that up to happen automatically for you.
The general solution is to add the above export command to your .bash_profile.
Alternatively on some systems you can set the preference via a system preferences:
Here is a command to add the above export command to your .bash_profile for you (which automatically creates a .bash_profile for you if you don't have one already, otherwise appends the command to the end).
echo "export CVS_RSH=ssh" | cat >> .bash_profile
You'll need to close your Terminal window and open a new one for it to take effect.
Here is another reference for setting up CVS to use SSH (though in practice I haven't found that I need it, and the instructions there seem cryptic too)
How to do secure checkouts that allow you to check in.
CVSROOT=:pserver:anonymous@dev.w3.org:/sources/publicpserver to extanonymous to your W3C usernameYou should have something like:
:ext:Tantekelik@dev.w3.org:/sources/public
But with YOUR username instead of “Tantekelik” (used only as a placeholder in these examples)
Note that your W3C username is CASE-SENSITIVE, be sure to enter it precisely.
cvs -d :ext:Tantekelik@dev.w3.org:/sources/publiccvs -d :ext:Tantekelik@dev.w3.org:/sources/public co csswgcvs -d :ext:Tantekelik@dev.w3.org:/sources/public co csswg
You might see a message like:
The authenticity of host 'dev.w3.org (128.30.52.19)' can't be established. RSA key fingerprint is fb:30:ab:09:1c:b3:1a:74:93:67:57:fd:69:16:0b:97.
That's the right one. If you get a different fingerprint back you're being hacked.
Then when asked:
Are you sure you want to continue connecting (yes/no)?
Answer:
yes
Then you'll likely get a warning like:
Warning: Permanently added 'dev.w3.org,128.30.52.19' (RSA) to the list of known hosts.
IF you get an error message like
Permission denied (publickey).
FIRST check to make sure you typed in your username *case-sensitively* including proper capitals if any.
THEN if it still doesn't work, something is wrong with your public key setup. Email Bert Bos and ask him for help making sure your public key is setup correctly with W3C.
On Mac OS X (10.6) Terminal, you should get an alert dialog box that says:
<html><pre> +———————————————–+
| Enter your password for the SSH key “id_dsa”. |
| Password: |
| (Cancel) 2) |
+———————————————–+ </pre></html>
Enter your SSH pass phrase that you used when you created the key and click OK.
On other OS's (or terminal/shell applications), you'll be prompted in some other way for pass phrase for your SSH key. Feel free to edit this and add OS-specific experiences/screenshots.
You may get a message like:
Identity added: /Users/USERNAME/.ssh/id_dsa (/Users/USERNAME/.ssh/id_dsa)
where USERNAME is your login alias for your client box.
IF you get an error message like:
Connection closed by 128.30.52.19 cvs [checkout aborted]: end of file from server (consult above messages if any)
THEN it could be a number of things. E.g.
You SHOULD see a message like:
cvs.bin checkout: Updating csswg
and then a bunch of messages like:
U csswg/.htaccess U csswg/default.css U csswg/logo-ED.png cvs.bin checkout: Updating csswg/css-style-attr U csswg/css-style-attr/Overview.html U csswg/css-style-attr/Overview.src.html U csswg/css-style-attr/issues-lc-2009.txt
…
etc.
CONGRATULATIONS!
You now have a checkout of the csswg CVS repository.
If you want to check out the HTML Working Group's (HTMLWG) html5 repository instead, you can use a check out command with html5 as the project rather than csswg.
First make sure that your Terminal application/window is in the directory where you want to create the “html5” check out, and then execute a command like:
cvs -d :ext:Tantekelik@dev.w3.org:/sources/public co html5
and again, with YOUR username instead of “Tantekelik”.
If you use the BBEdit text editor:
BBEdit menuPreferences…Source Control in the left column list of preference panes(Add CVS…) button in the right columnName: field.|x| Use SSH(Save) button.
You'll see a new CVS menu between the #! and the script icon menu for performing operations on files that are part of a CVS checkout.
Repeat these steps for any other CVS repositories you checkout, substituting their name/folder for “csswg” in the instructions (e.g. “htmlwg”).
BBEdit menuPreferences…Tools in the left column list of preference panes|x| CVS Integration(Save) button and close the BBEdit Preferences window.
If you're running BBEdit 7.1.x you'll see a new “yellow diamond merge” menu icon between the #! and the script icon menu for performing operations on files that are part of a CVS checkout.
Feel free to add more specific info about other versions of BBEdit.
Other windowing/GUI text editors may have their own ways of enabling CVS support. Feel free to add documentation for those here in their own sections, named similarly to the previous section on Enabling BBEdit CVS Support.
Say you're working on a new spec, CSS3 Foo and want to create the respective directory, “css3-foo”, here's how you do it.
Create the new folder for “css3-foo” in your filesystem.
E.g. on a Mac, go to the “csswg” folder in the Finder, and choose “New Folder” (cmd-shift-N) and rename the folder to “css3-foo” (without the quotes).
Or cd to that directory and do a
mkdir css3-foo
command in your terminal/shell.
Then you need to do an explicit cvs add on the directory, e.g.
cvs add css3-foo
You should get a message back like:
Directory /sources/public/csswg/css3-foo added to the repository
If you get a message like:
cvs-debian-1.12.13 checkout: cannot find module `csswg/css3-foo - New directory ' - ignored
Ignore it.
Now cd into that directory
cd css3-foo
CVS needs at least one file in a new directory for that new directory to be propagated to the server.
Create your new HTML pre-processor source file and name it something like: Overview.src.html
and save it in the aforementioned css3-foo directory.
To commit this file and thus create the new directory, you have to do a cvs add, e.g. from the shell.
cvs add Overview.src.html
You should see messages like:
cvs.bin add: scheduling file `Overview.src.html' for addition cvs.bin add: use 'cvs.bin commit' to add this file permanently
Now you have to do a cvs commit of the file and the directory, which means first going to (cding up to) its parent.
cd ..
Do a cvs commit with the name of the directory explicitly (doing so is safer, because otherwise you'll checkin anything you've changed at that directory or inside an descendant folder/directory), with a proper commit message.
copy the following line:
cvs commit -m "YOUR COMMIT MESSAGE HERE" css3-foo
and replace
YOUR COMMIT MESSAGE HERE
with something more meaningful, like:
creating css3-foo for the CSS3 Foo module spec
Now you should see a set of messages like:
cvs commit: Examining css3-foo RCS file: /sources/public/csswg/css3-foo/Overview.src.html,v done Checking in css3-foo/Overview.src.html; /sources/public/csswg/css3-foo/Overview.src.html,v <-- Overview.src.html initial revision: 1.1 done cvs-debian-1.12.13 checkout: Updating csswg/css3-foo
CONGRATULATIONS!
You've checked in your first new directory and file.
IF you forget to type -m and a commit message in the cvs command line, e.g. type something like:
cvs commit css3-foo
THEN
You might quickly see a message like:
cvs commit: Examining css3-foo
And then be teleported into a terminal based text editor.
In MacOS X 10.6 Terminal, the title of the terminal window will change to indicate the name of the text editor (e.g. vim is indicated by something like
Terminal — vim — 80×24
Regardless of which editor, you'll see lines at the top starting with:
CVS: ---------------------------------------------------------------------- CVS: Enter Log. Lines beginning with `CVS:' are removed automatically
IF you're using VIM:
type 'i' to go into INSERT mode (you should see a bold – INSERT – at the bottom of the terminal screen)
Type in a commit message for the new directory and file and press return.
then press the 'esc' (escape) key
and type the keys ':' 'w' 'q' (one at a time, without the quotes or spaces)
and press the enter/return key.
You should see messages like:
RCS file: /sources/public/csswg/css3-foo/Overview.src.html,v done Checking in css3-foo/Overview.src.html; /sources/public/csswg/css3-foo/Overview.src.html,v <-- Overview.src.html initial revision: 1.1 done cvs-debian-1.12.13 checkout: Updating csswg/css3-foo
Your code has been checked in with the comments you wrote in the vim edited file.
In order to avoid vim popping up like that in the future, be sure to to always explicitly specify a commit message with -m like
cvs commit -m "YOUR COMMIT MESSAGE HERE" css3-foo
(If you do want to use an editor, just not vim, see the -e option in the CVS manual for various ways to do that.)
How to check in a new file from BBEdit.
Open the new file e.g. Overview.html in BBEdit
Choose “Add” from the CVS (or mergeicon) menu.
Choose “Commit File…” from the CVS (or mergeicon) menu.
You will be presented with a “Commit File” modal dialog.
Enter your checkin comments for the file and click (OK).
How to check in multiple files from BBEdit.
IF all the new files are in the same folder (or descendants of that folder)
THEN open a file that folder
and choose “Commit Parent Folder…” from the CVS (mergeicon) menu.
You will be presented with a “Commit Message” modal dialog.
Enter your checkin comments for all the files you have changed in that folder or its descendants and click OK.
Open the Overview.src.html file in the directory of the spec you want to edit.
Make sure you edit the *.src.html version, NOT the *.html version.
Look for the W3C style sheet <link> tag - it will look something like this:
<link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-CR">
It may end in “W3C-WD” or “W3C-PR” or something else. Make sure it is the EDITOR's stylesheet by using this <link> element:
<link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED">
You'll probably need to make other edits. You should check a good editor's draft as an example, e.g. CSS3 Color is pretty good.
One thing to make sure is that the “Previous version:” at the top of the document links to the absolute latest official /TR/ version of the document.
Both before you start editing a document, and when you're ready to check in a document, you should update your local CVS checkout.
cd to your CVS checkout, e.g. if your check out is in your home directory:
cd ~/csswg cvs up -d
IF it seems to stall and not do anything, or eventually gives an error message like:
lionel-hutz.w3.org: Connection refused cvs [update aborted]: end of file from server (consult above messages if any)
OR an error message like:
cvs [update aborted]: cannot exec value: No such file or directory cvs [update aborted]: end of file from server (consult above messages if any)
THEN check to see if your CVS_RSH is defined by trying:
echo $CVS_RSH
IF you get nothing but a blank line or something other than “ssh”, THEN do this (you likely need to setup your CVS_RSH system variable as documented in Step 1 setup cvs_rsh) :
export CVS_RSH=ssh
THEN retry the cvs up line:
cvs up -d
You should see messages like:
cvs.bin update: Updating . cvs.bin update: Updating css-style-attr
… etc.
If you see a line starting with a “M”, like:
M css3-color/Overview.src.html
That means that you have a locally modified version of that file and should verify your changes and check it in.
If you see a line starting with a “P”, like:
P css3-background/Overview.src.html
That means that that file was updated with a “P”artial download (CVS was able to be more efficient by only downloading diff).
If you see a line starting with a “U”, like:
U css3-transitions/step.png
That means that that file was “U”pdated with a full download.
Go to:
http://www.w3.org/Style/Group/css3-src/bin/postprocess-file
Click (Choose File) and select the Overview.src.html file on your local machine that you want to post-process (you should do this when you're ready to check it in).
Choose (*) Generated HTML - radio button
Click the (Submit) button
Save the page (e.g. in Firefox, choose the “Save Page as…” menu item from the “File” menu, be sure to choose “Web page, HTML only” from the “Save as” popup), name the file Overview.html (without the quotes), and save it right next your Overview.src.html - you'll likely be replacing an older version, that's ok, go ahead and confirm (command-R in the replace dialog).
If you're on a system with curl on it, just save the following line to a file somewhere in your executable path:
curl -u USERNAME:PASSWORD -F file=@Overview.src.html -F group=CSS -F output=html -F method=file http://cgi.w3.org/member-bin/process.cgi -o Overview.html''
(Replace the USERNAME:PASSWORD with your W3C username and password, the same that you would enter when visiting the web form linked above.)
Mark the file as executable, then just run it from within the folder of the spec you're working on. It will automatically submit Overview.src.html to the post-processor and save the results to Overview.html.
Now when you check in your Overview.src.html file be sure to also check in Overview.html to keep them sync.
You can also just check-in from their parent folder by cding in a terminal window to their directory and then:
cvs -m "COMMIT MESSAGE HERE" commit
where you replace COMMIT MESSAGE HERE with a message that applies to all the files you're checking in.
“cd” to a directory that you have a checkout and try a
cvs version
IF you get an error message like:
Client: Concurrent Versions System (CVS) 1.11.18 (client/server) lionel-hutz.w3.org: Operation timed out Server: cvs [version aborted]: end of file from server (consult above messages if any)
THEN something is wrong with your CVS setup probably.
TRY:
echo $CVS_RSH
IF it shows just a blank line then you need to set it:
export CVS_RSH=ssh
try again:
cvs version
IF you see a message like (On MacOSX 10.4 at least) :
The authenticity of host 'dev.w3.org (128.30.52.19)' can't be established. RSA key fingerprint is fb:30:ab:09:1c:b3:1a:74:93:67:57:fd:69:16:0b:97. Are you sure you want to continue connecting (yes/no)?
Verify that the fingerprint is correct and then type in
yes
and press return.
you may see a message like:
Warning: Permanently added 'dev.w3.org' (RSA) to the list of known hosts.
You may be asked:
Enter passphrase for key '/Users/USERNAME/.ssh/id_dsa':
where USERNAME is your username alias on your local system.
Enter your pass phrase for your key.
IF you keep getting asked that for every CVS command you run,
THEN try
ssh-add ~/.ssh/id_dsa
you might get an error like:
Could not open a connection to your authentication agent.
TRY
ssh-agent -s
Now you might see something like:
SSH_AUTH_SOCK=/tmp/ssh-VWXYZVWXYZ/agent.555; export SSH_AUTH_SOCK; SSH_AGENT_PID=333; export SSH_AGENT_PID; echo Agent pid 333;
(numbers and ssh-VWXYZVWXYZ string obscured with fakes for the sake of documentation).
Now try:
eval `ssh-agent -s` ssh-add ~/.ssh/id_dsa
and you might see a message like:
Enter passphrase for /Users/USERNAME/.ssh/id_dsa:
where USERNAME is your username alias on the system.
Enter your pass phrase for your key.
Then you might see a message like this: (at least on Mac OS X)
Identity added: /Users/USERNAME/.ssh/id_dsa (/Users/USERNAME/.ssh/id_dsa)
Now try:
cvs version
And you should get messages like:
Client: Concurrent Versions System (CVS) 1.11.18 (client/server) Server: Concurrent Versions System (CVS) 1.11.22 (client/server)
On Mac OS X 10.5 and later, download and double-click install the “Environment Variable Preference Pane 1.3” from:
Choose “System Preferences…” from the Apple menu.
Choose the “Environment Variables” preference pane.
Click the “+” to add a new entry.
double-click the new “key” entry in the list and change it to CVS_RSH.
double-click the new “value” entry in the list and change it to ssh.
Quit System Preferences.
Logout of your machine and log back in.
From now on, the CVS_RSH environment variable is automatically set for all applications whenever you log into your account on your machine. This means it will work both with terminal/shell applications, and nice text editors that have integrated CVS support for example.
If you've gotten this far, and you happen to also be a W3C Member (or a W3C Invited Expert that's been granted Member Access), you might want to also check-out and help with some W3C Member-only parts of w3.org.
Assuming you've already successfully checked-out and checked-in to W3C's Public CVS repository by following the above steps, here's what you need to use the W3C Member-Only CVS Repository.
First, make sure your staff contact (in whatever W3C working group you're working with/in) has upgraded your CVS account access for member-only areas, in particular, for cvs.w3.org.
Just as you checked out into a new directory from the public repository, you'll do the same here, just with a different command line.
In a Terminal window, be sure to cd to the directory you want to create the new checkout, then modify this command line:
cvs -d Tantekelik@cvs.w3.org:/w3ccvs co WWW
with YOUR username instead of “Tantekelik” (used only as a placeholder in these examples)
Note that your W3C username is CASE-SENSITIVE, be sure to enter it precisely.
Now execute the command line.
You might see a message like:
The authenticity of host 'cvs.w3.org (128.30.52.19)' can't be established. RSA key fingerprint is fb:30:ab:09:1c:b3:1a:74:93:67:57:fd:69:16:0b:97.
That's the right one. If you get a different fingerprint back you're being hacked.
Then when asked:
Are you sure you want to continue connecting (yes/no)?
Answer:
yes
Then you'll likely get a warning like:
Warning: Permanently added 'cvs.w3.org' (RSA) to the list of known hosts.
IF you get messages like:
cvs.bin checkout: Updating WWW cvs.bin checkout: cannot open directory /w3ccvs/WWW: Permission denied cvs.bin checkout: skipping directory WWW
Then you don't have access to the top level WWW directory. You'll have to pick a subdirectory instead, perhaps associated with the working group you're working with, e.g. for the W3C CSS Working Group, use a command like this instead:
cvs -d Tantekelik@cvs.w3.org:/w3ccvs co WWW/Style/Group
again with your username instead of “Tantekelik”.
You SHOULD see a message like:
cvs.bin checkout: Updating WWW/Style/Group
and then a bunch of messages like:
U WWW/Style/Group/970117-usersettings.html U WWW/Style/Group/CSS-X-schema.gif U WWW/Style/Group/CSS-X-schema.idraw U WWW/Style/Group/CSS-X-small.gif U WWW/Style/Group/CSS-X.html U WWW/Style/Group/CSS-selectors.html U WWW/Style/Group/History.html
…
etc.
This might take some time to check out all of WWW/Style/Group, so just let it run for a while.
The total checkout size might be in the range of about 220MB or a bit more (depending on how much has been added since these instructions were updated).
If it seems to get “stuck”, i.e. you've left it running for a while, and it's stopped on a status line like:
cvs.bin checkout: Updating WWW/Style/Group/2002
You can try ctrl-c to stop the check out - whereby it will probably give you messages like:
^Ccvs [checkout aborted]: received interrupt signal cvs [checkout aborted]: received interrupt signal
Now go the specific directory you checked out:
cd WWW/Style/Group
and restart your checkout:
cvs up -d
If it still seems to stall in the same place, e.g. on
cvs.bin checkout: Updating WWW/Style/Group/2002
Just give it a bit longer - there's a 100+ MB .rm file in that directory that may just be taking a while to pull down.
Eventually, you should see a bunch of cvs.bin updated: Updating … lines like:
cvs.bin update: Updating . cvs.bin update: Updating 2003 cvs.bin update: Updating 2003/WD-css3-content-20030514 cvs.bin update: Updating 2003/WD-css3-template-20030514 cvs.bin update: Updating 2004
…
etc. Just give a little while to finish with something like:
cvs.bin update: Updating pjirc/img cvs.bin update: Updating pjirc/snd cvs.bin update: Updating test-suite
CONGRATULATIONS!
You now have a checkout of the W3C Member-Only WWW/Style/Group CVS repository.
If you're in the CSS Working group, you probably also want to check out the WWW/Style/CSS CVS repository. Do a quick:
pwd
if the path returned ends with “/WWW/Style/Group” then cd back out of it:
cd ../../..
and then issue a new check out command like before but with the WWW/Style/CSS:
cvs -d Tantekelik@cvs.w3.org:/w3ccvs co WWW/Style/CSS
again with your username instead of “Tantekelik”.
You should see messages like:
cvs.bin checkout: Updating WWW/Style/CSS U WWW/Style/CSS/.Disclosures.var U WWW/Style/CSS/.Overview.var U WWW/Style/CSS/.htaccess
… etc.
In fact, if all you wanted was stuff inside WWW/Style/CSS, then you can simply check that out instead of checking out WWW/Style/Group. As of this writing the WWW/Style/CSS checkout may take about 1.31GB (yes gigabytes, that's not a typo) for over 250,000 files.
Creating new directories, getting updates, and checking in works exactly the same on cvs.w3.org as for the public repository. All the repository-specific information is contained in the folders of your checkout, so CVS doesn't have to be told which server to get updates from etc.