Inaccurate documentation re cvs tag
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. 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 tag. And 1.2 gets tagged. 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. 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. 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. 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? 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. 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)) and 1.2. I think the phase checked out should be used with care. Ming Kin Lai _ Express yourself instantly with MSN Messenger! Download today - it's FREE! http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/ ___ Info-cvs mailing list Info-cvs@gnu.org http://lists.gnu.org/mailman/listinfo/info-cvs
Re: Inaccurate documentation re cvs tag
Ming Kin Lai wrote: 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). 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). I run cvs tag. And 1.2 gets tagged. Because you checked out (updated to) 1.2 by committing it. 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. 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. 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. 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. 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. and 1.2. I think the phase checked out should be used with care. It is, you simply have a little learning to do. Ming Kin Lai -- Todd Denniston Crane Division, Naval Surface Warfare Center (NSWC Crane) Harnessing the Power of Technology for the Warfighter ___ Info-cvs mailing list Info-cvs@gnu.org http://lists.gnu.org/mailman/listinfo/info-cvs
Re: Inaccurate documentation re cvs tag
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
