Re: What is HEAD?

[Larry Jones]

Ming Kin Lai writes:
> 
> Appendix A-5 of the 1.12.12 version cederqvist says "HEAD refers to the most 
> recent version  available in the repository" when it describes "-r tag".  
> This is the only place in cerderqvist that has a formal definition of HEAD.

That description is lacking.  The manual source contains the following
comments immediately after that statement:

@c FIXME: What does HEAD really mean?  I believe that
@c the current answer is the head of the default branch
@c for all cvs commands except diff.  For diff, it
@c seems to be (a) the head of the trunk (or the default
@c branch?) if there is no sticky tag, (b) the head of the
@c branch for the sticky tag, if there is a sticky tag.
@c (b) is ugly as it differs
@c from what HEAD means for other commands, but people
@c and/or scripts are quite possibly used to it.

The "head" of a branch (or trunk) is also called the "tip" and refers to
the highest numbered revision on the branch.  The "default branch" is
generally the vendor branch if the file has been imported and not
locally modified, and the trunk otherwise.

> Q1: Are there some versions in the repository that are not available?  

No, it's just trying to distingish between the revision you have (which
may well have been the most recent revision at the time you last checked
it out or updated it) and the revision that is currently the most
recent.

> Q2: What does it mean by "the most recent"?

It means the head, as described above.

> Q3: Is HEAD dependent on where my working copy is?  That is, is it true that 
> if my working copy is on the trunk (i.e. it is based on a revision on the 
> trunk), then HEAD refers to the most recent revision the trunk, but if my 
> working copy is on a branch (i.e. it is based on a revision on the branch), 
> then HEAD refers to the most recent revision on the branch?

See the comments in the manual, above.

> Q4: is this "head revision of the trunk" the same as HEAD?

Usually, but not for diff as noted above.

> So, is there a "head revision" of each branch?

Yes, see above.

> And I assume that "annotate" will not print 
> the head revision of a branch by default even if my working copy is based on 
> that branch.

That is correct (and, perhaps, unfortunate).

> Q5: If there are many head revisions, then does HEAD depend on where my 
> working copy is?

Usually not, but it does for diff.

> Q6: Specifically, suppose I tag revision 1.2 as Root-of-mybranch:
> cvs tag Root-of-mybranch
> before creating a branch:
> cvs tag -b mybranch
> And then I make changes and commit them as revision 1.3 (on the trunk).
> Now I switch to the branch:
> cvs update -r mybranch
> and now I am on revision 1.2.  OK, but does this "update -r mybranch" 
> effectively switch me to a branch?

Yes.  If you do ``cvs status'' on a file, you should see a sticky tag of
"mybranch".

> If it does, and assumed that HEAD depends on where my working copy is, that 
> is, HEAD now should be 1.2, then
> cvs diff -r HEAD -r 1.2 file
> should output nothing.

Correct.

> Incidentally, can anyone be kind enough to clarify A.19.1 of the manual 
> about "update -r tag[:date]"?  The way it is written suggests that there are 
> two ways to supply valid argumnets to tag and date:
> 1. give only the value of tag and that value is a revision, e.g. 1.2
> 2. give both tag and date where tag is a branch tag such as "mybranch".
> What happens if I give only tag and tag is a branch tag?  (same problem with 
> the documnetation about checkout)

When used to specify a revision, a branch tag is always interpreted as
the head (or tip) of the branch.

> (By the way, is a Table of Contents deliberately omitted from cederqvist?)

It's not omitted, it's just at the end.

-Larry Jones

Ha!  Wild zontars couldn't drag that information out of me!  Do your worst!
-- Calvin