[ On Friday, November 14, 2003 at 08:04:48 (-0600), Frederick Bruckman wrote: ]
> Subject: Re: usr/src/xsrc/make build fails
>
> "current" is the HEAD of the CVS tree, as opposed to the release
> branches, such as netbsd-1-6. NetBSD 1.6, NetBSD 1.6.1, NetBSD
> 1.6.2_RC2, are all points on netbsd-1-6. Points on current are rarely
> tagged. The formal releases, these days, are all points on the release
> branches. The release branches consist entirely of pull-ups from the
> HEAD; no original work is allowed on the release branches. This
> differs from the way some other other projects use CVS. XFree86, for
> instance, puts all the original work on vendor branches; their release
> branch is the HEAD.

As an aside note that "HEAD" can be a bit misleading in this context, at
least once you get down to actually using CVS to access the code from
the (or a copy of the) repository.

The CVS documentation is a bit misleading about what the pseudo-tag
"HEAD" means in all cases.  For all CVS commands except "cvs diff"
"HEAD" refers to the head of the "default branch".  However for that
most commonly used "cvs diff" command the pseudo-tag "HEAD" _sometimes_
refers to the head of the branch specified by by the sticky tag, if any,
otherwise I believe it refers to the "default branch".  The concept of
the "default branch" is a hang-over from RCS (upon which CVS is built),
but it's sometimes misused inside CVS and should be left blank.  CVS
should be fixed so that all used of the pseudo-tag "HEAD" refer to the
sticky branch, if any, otherwise the trunk, but there are some other
related hang-overs in RCS since it keeps track of the "head" revision of
every file.  The confusion stems from the fact that CVS tries to be
efficient and speedy at branch creation (making branch creation a
"cheap" and thus "encouraged" operation), and it does so by not actually
creating real RCS branches in any file until the first commit is made to
the branch (just identifying the internal branch number in a "magic"
way), and then when it does create the actual RCS branch it only does so
only in the changed file(s).  Meanwhile the meaning of the pseudo-tag
"HEAD" is spread unevenly over the "head" revision tracked in every RCS
file and the current revision's branch (as opposed to the true sticky
branch).  The pseudo-tag "HEAD" (and its companion "BASE") where very
poorly designed hacks that should never have made it into an official
CVS release in the way thay did, but now that's all just water under the
bridge and so now we have to be careful to not misuse those reserved
names.

Back to NetBSD's repository.  If you wanted to read or build (or work
on) the netbsd-1-6 code, for example, you would check it out into a
working directory using a command like this (assuming your $CVSROOT
environment is set and any authentication mechanisms you might need are
also configured):

	cvs checkout -r netbsd-1-6 -d src-1.6 src

The result would be a source tree rooted at the new subdirectory
"src-1.6" created in the PWD of the above command, and each subdirectory
in that tree would have a sticky tag of "netbsd-1-6" such that when you
do any subsequent "cvs update" within that tree you would be tracking
changes made to the head of the "netbsd-1-6" branch.  You can see the
sticky tag name and other details with the "cvs status" command, e.g.:

	$ cvs status /usr/src-1.6/Makefile
	===================================================================
	File: Makefile          Status: Locally Modified
	
	   Working revision:    1.175.2.3       Fri May  9 01:29:39 2003
	   Repository revision: 1.175.2.3       /cvs/master/m-NetBSD/main/src/Makefile,v
	   Sticky Tag:          netbsd-1-6 (branch: 1.175.2)
	   Sticky Date:         (none)
	   Sticky Options:      (none)

In this example if you use the "HEAD" pseudo-tag explicitly with a
commands such as "cvs diff -r HEAD", it would show what changes have
been made in the repository (if any), on the working directory's branch
("netbsd-1-6" in this case), since the working directory was last
updated.

Assuming nobody's screwed up the major versions on any files in your
repository (they should all be left at "1" forever), then you can always
refer to the trunk by explicitly refering to the "1" branch.  The trunk
is the only branch that has a guaranteed consistent internal branch
number across all files in a CVS repository.

A better word than "HEAD" for use in this context, and one used commonly
in the CVS community for the same purpose as Frederick was using it
above (i.e. for refering to the branch that active development for
"-current" occurs on), is the word "trunk", which refers to the branch
from revision "1" of every file.  The trunk is (supposed to be) the
default branch and thus any working directory that was checked out
without specifying a sticky branch tag will be on the trunk, e.g.:

	$ cvs status /usr/src-current/Makefile
	===================================================================
	File: Makefile          Status: Up-to-date
	
	   Working revision:    1.221   Fri Oct 31 19:11:39 2003
	   Repository revision: 1.221   /cvs/master/m-NetBSD/main/src/Makefile,v
	   Sticky Tag:          (none)
	   Sticky Date:         (none)
	   Sticky Options:      (none)

So, "-current", in the NetBSD lexicon, refers to the head of the trunk
of the CVS module(s) which contain all of the base-OS code and
documentation files.  The trunk in the NetBSD CVS repository happens to
be the active development branch, thus the reason for calling it
"current" -- if you "cvs checkout" and then regularly "cvs update" from
the trunk you track the ongoing development of NetBSD.

Thus releases of NetBSD are tags made on the release branches
(e.g. NetBSD-1.6 is tagged "netbsd-1-6-RELEASE" on the "netbsd-1-6"
branch), and all changes on the release branches for NetBSD are
"pull-ups" of changes already committed to the "trunk" (which may or may
not be at the head of the trunk at the time they are pulled up).  Points
on the trunk are tagged, but only so that there's a uniform way to
identify the revisions from which a branch has been created without
having to figure out the corresponding internal revision number for each
file from the internal branch number the branch tag happens to be
assigned to in that file.

Note that using the trunk as the active development branch is just a
common convention for CVS users -- it's not strictly necessary since any
branch can be used as the active development branch.  The main advantage
of using the trunk is that it keeps things a bit simpler to understand
in terms of reading and following the private internal per-file revision
numbers (and of course the default branch for "cvs checkout" is the
trunk, but you only use that command once for every working directory
you create, and the only other command where such a default is much help
is "cvs rdiff").

I personally never ever use the pseudo-tag "HEAD" (or "BASE") with CVS
but instead I always use the explicit branch name (or number in the case
of the trunk where it's just "1") to refer to the head of the branch I
wish to refer to.

-- 
						Greg A. Woods

+1 416 218-0098                  VE3TCP            RoboHack <woods@robohack.ca>
Planix, Inc. <woods@planix.com>          Secrets of the Weird <woods@weird.com>