[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Inaccurate documentation re "cvs tag"

From: Ming Kin Lai
Subject: Re: Inaccurate documentation re "cvs tag"
Date: Tue, 12 Jul 2005 14:04:48 -0700

> Sec 4.5 of 1.11.20 cederqvist says: "running the cvs tag command without
> arguments causes CVS to select the revisions which are checked out in the > current working directory. ... One potentially aspect of the fact that cvs
> tag operates on the repository is that you are tagging the checked-in
> revisions, which may differ from locally modified files ..."
> I think it is somewhat confusing, especially to new users.  At first it
> talks about a checked-out revision, then it talks about a checked-in
> revision. Well, I understand they mean the same, at least in some cases; but
> it is not quite accurate and probably confusing.
> 1. The problem with "checked out" is that it does not literally mean
> "checked out".

Actually it does literally mean the version which was checked out, not what
you currently have (i.e., not possible local mods).

Apparently you and I have disagreement about what "literally means" means.

> Suppose I check out a file with revision 1.1, modify it and
> commit it, so now I have revision 1.2 in my working directory.

Well this commit does do essentially a checkout (actually update, which is
why things like $Log:$ and $Id:$ get updated).

This makes it clear what you mean by "literally means" - to you, a commit essentially does a checkout, so a commit literally means a checkout. But to me, even though a commit essentially does a checkout, it is not a "literally" a checkout. Please note that there is nowhere in cederqvist that says a commit is essentially a checkout or a commit implies a checkout, etc (if you can find such, please show me). To an experienced user like you, that may be clear. But as I said, that may be confusing to a new user. A manual such as cederqvist is to make things clear. People should not need a yaer's experience using CVS to understand what cederqvist really means.

> I run "cvs
> tag".  And 1.2 gets tagged.

Because you checked out (updated to) 1.2 by committing it.

Again, I cannot find any place in cederqvist that says when the user commits a file, he in effect checks it out. And that's my point: cederqvist should mke this clear or use the word "checked out" with care.

> Literally 1.1 is the revision I checked out.  I
> did not check out 1.2, unless commit implies check out - but I think it's
> better separate them; after all ci and co are two different commands.

It was learned long ago that less confusion was created by cvs handling the
immediate update, otherwise cvs would have a hard time being Concurrent
Versions System, the command you imply are serial locking commands and CVS
is a parallel merging system.

I did not imply any command. What I mean is less confusion would be created by explaining what "check out" really mean, e.g. that would be implied by a commit.

>  Also,
> stating that a checked-out version is tagged may give the wrong impression
> that the user (unnecessarily) needs to do a "cvs co" before tagging.

No the update makes it the checked out version, this is simply a
misconception on your part.

I am pointing out a potential misconception because of the way "checked out" is used in cederqvist.

> 2. The problem with "checked in" is that there may not be any check-in (cvs > ci). Suppose I check out a file for the first time and without modifying > it, run "cvs tag". The one and only one revision gets tagged; but there is
> never any check-in.

If you checked it out there was a check in, which created 1.1.

Not necessarily. I initially import the file and then check it out. There is no check-in. Well, I guess you would say something like "an import essentially does a check-in" or "an import literally means a check-in". My take is that if that's what the CVS designers mean, fine, document it in cederqvist to avoid misunderstanding. A user should be not be left wondering whether xxx is essentially doing yyy.
From this discussion it is quite apparent that you separate the _concept_ of
checkin and checkout, respectively, from the actual command of "cvs checkin" (or "cvs ci") and "cvs checkout" (or "cvs ci"), respectively. It appears, to you, the concept of checkout encompasses both the "cvs checkout" and "cvs commit", for example. I am not arguing about the merit of this way of thinking. Look at the title of my post - "inacurrate documentation". I am talking about the documentation. If you can find any place in cederqvist that explains that the concept of checkin encompasses "cvs checkout" and "cvs commit", please show me. If you do not explain that to a new user, can you expect him to somehow figure it out himself? Yes, he will eventually. But why can't the documentation give him an easier time? cederqvist is not just a reference for experienced users, it also serves as a guide for first-time users.

> Stating that a checked-in revision is tagged may give
> the wrong impression that the user (unnecessarily) needs to do a "cvs ci"
> before tagging.
> Anyone agrees or disagrees?

Yes, see above.

> Incidentally, the entry for tag in Appendix B (page 132) says "Add a
> symbolic tag to checked out version".  I think "checked out" need to be
> re-worded, and "version" probably should be "revision".

In most cases people tag an entire baseline (which is also the better
practice), which has a "version", but also has many files which have
"revisions". It seems clear as written from here.

Section 4.2 of the 1.11.20 cederqvist says "To avoid confusion, the word version is almost never used in this document." Apparently the authors of the manual think that the use of the word "version" is not clear and may create confusion. And I agree with the authors of the manual.

> Finally there are a number of places in cederqvist that use the phase
> "checked out".  I am not sure all mean literally "checked out".  For
> example, Sec 1.3.4 says "diff compare[s] the version (revision?) of driver.c > that you checked out with your working copy." Again, suppose I check out a > file with revision 1.1, modify it and commit it, so now I have revision 1.2 > in my working directory. I run "cvs diff". There is no difference. The > comparison is NOT between 1.1 (the last revision I checked out (using cvs
> co))

see above information about your misunderstanding because cvs commit does an
update to get you synchronized with what is in the baseline after commit.

You can call it my "misunderstanding" but I don't think I misunderstand anything. If there is, then I think cederqvist can be improved to avoid misunderstanding. That's my point.

> and 1.2.  I think the phase "checked out" should be used with care.

It is, you simply have a little learning to do.

I think everyone, including you, is learning. I surely hope you can learn something from this discussion.

On the road to retirement? Check out MSN Life Events for advice on how to get there!

reply via email to

[Prev in Thread] Current Thread [Next in Thread]