1175261Sobrien------------------------------------------------------------------------------- 2175261Sobrien 3177391Sobrien CVS is Copyright (C) 1986-2006 The Free Software Foundation, Inc. 4175261Sobrien 5175261Sobrien CVS is free software; you can redistribute it and/or modify 6175261Sobrien it under the terms of the GNU General Public License as published by 7175261Sobrien the Free Software Foundation; either version 1, or (at your option) 8175261Sobrien any later version. 9175261Sobrien 10175261Sobrien More details are available in the COPYING file but, in simplified 11175261Sobrien terms, this means that any distributed modifications you make to 12175261Sobrien this software must also be released under the GNU General Public 13175261Sobrien License. 14175261Sobrien 15175261Sobrien CVS is distributed in the hope that it will be useful, 16175261Sobrien but WITHOUT ANY WARRANTY; without even the implied warranty of 17175261Sobrien MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18175261Sobrien GNU General Public License for more details. 19175261Sobrien 20175261Sobrien------------------------------------------------------------------------------- 21175261Sobrien 2232785SpeterThis file contains a CVS FAQ. Until 1995 it was maintained by David 2332785SpeterGrubbs. It was out of date and not being maintained, but it had a 2432785Spetercertain following and in 1997 Pascal Molli decided to start 2532785Spetermaintaining it with the FAQ-O-Matic package which allows any 2632785Spetercontributor with a web browser to help maintain it. The following 2732785Spetertext is (mostly automatically) extracted from the FAQ-O-Matic. The 2832785Speterodds are good that the file that you are currently reading is out of 2932785Speterdate with respect to the online FAQ-O-Matic, which is part of Pascal 3032785SpeterMolli's CVS web site at http://www.loria.fr/~molli/cvs-index.html 3132785Speter(currently under "Documentation"). The online version is also 3232785Spetersomewhat better in terms of things like tables of contents (at least 3332785Speteruntil someone can write some code to extract data from a FAQ-O-Matic 3432785Speterand insert things like tables of contents). 3532785Speter 3632785SpeterThe answers which are dated "6/13/1997" below are really from the 1995 37175261SobrienFAQ, for the most part. Many of them are out of date. The current FAQ may 38175261Sobrienbe found at <http://ximbiot.com/cvs/wiki/index.php?title=CVS_FAQ>. If you have 39175261Sobriensome time, you are encouraged to export that FAQ as text and import it here. 40175261SobrienIf you don't have such time, take the answers in this file with at least a few 41175261Sobriengrains of salt. 4232785Speter 43175261SobrienSince August, 2005, many of the existing CVS resources have been centralized on 44175261Sobrien<http://cvs.nongnu.org> & <http://ximbiot.com>. 4566525Speter 4632785Speter Category: /, all questions 4732785Speter 4832785Speter Category: / 4932785Speter 5032785Speter " [INLINE] " 5132785Speter 5232785Speter 1. About FAQ-O-Matic 5332785Speter 5432785SpeterThis is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by 5532785SpeterJon Howell. 5632785Speter 5732785SpeterIt seems like most FAQ maintainers make a valiant initial effort, then get 5832785Spetera life and don't have time to keep their FAQs up to date. Also, I often 5932785Speterfind out a solution to a problem, and feel like I could write a single 6032785SpeterFAQ answer on it in a few minutes, but where to post it? 6132785Speter 6232785SpeterThus the FAQ-O-Matic was born. FAQ-O-Matic is a couple sleazy Perl scripts 6332785Speterthat allow people to submit FAQ answers to this database, so it can stay 6432785Spetercurrent, with just a tiny bit of work on any one person's part. 6532785Speter 6632785SpeterYes, a bad guy could come along and wipe out all the FAQ entries. Please don't. 6732785SpeterBut to give the good guys some measure of comfort, each submission is stored 6832785Speterin an RCS file, so if someone does tamper, we can recover the database. 6932785Speter 7032785SpeterGuidelines for submissions: 7132785Speter 7232785Speter1. Please _try to be fairly unbiased in matters of opinion._ Mailing lists are 7332785Speterthe place to start flame wars (just kidding :v), but definitely not here. 7432785Speter 7532785Speter2. Please _use HTML only conservatively_ in your entries. Links are appropriate 7632785Speter, 7732785Speterbut put the URL in the plaintext also so it's useable on printed versions of 7832785Speterthe FAQ. Inline images pointing off this site are inappropriate, as is much 7932785Speterfancy formatting. This is meant to be bandwidth-light and dumb-browser-friendly 8032785Speter. 8132785Speter 8232785Speter3. If you feel there's a place for a _new category, or a reorganization of 8332785Speterexisting questions_, don't hesitate to mail me (molli@loria.fr). 8432785SpeterCategory changes need to be done from my end. 8532785Speter 8632785Speter4. Please _leave an email address_ at the bottom of your submission so that oth 8732785Speterers 8832785Spetercan drop you a note. 8932785Speter 9032785Speter5. _If you only have a question_, not an answer, you should probably post 9132785Speterit to a mailing list, not here. If there are frequently asked questions to whic 9232785Speterh 9332785Speterthe answer is not forthcoming on mailing lists (or perhaps there's no 9432785Speteruseful answer yet other than "no one knows"), then it's appropriate to 9532785Speterpost here, in hopes that someone will see it and know the answer. 9632785Speter 9732785Speter6. Please refrain from crude or inconsiderate language. Please don't use 9832785Speterthis as a forum for advertising. However, mention of worthy commercial 9932785Speterproducts is certainly appropriate (even if you sell said product). Just 10032785Speterdon't overdo it. :v) 10132785Speter 10232785Speter Last modified: _6/13/1997_ 10332785Speter 10432785Speter 2. Adding a new category ? 10532785Speter 10632785Speterjust send me a mail at 10732785Spetermolli@loria.fr 10832785Speter 10932785Speter Last modified: _6/13/1997_ 11032785Speter 11132785Speter Category: /Advanced_Topics_/ 11232785Speter 11332785Speter " Advanced Topics " 11432785Speter 11532785Speter Category: /Advanced_Topics_/Branching_and_Mergin/ 11632785Speter 11732785Speter " + Branching and Merging" 11832785Speter 11932785Speter 1. What is a branch? 12032785Speter 12132785Speter Unfortunately, the word "branch" is an overloaded technical 12232785Speter term. It is used in too many different ways in three 12332785Speter categories. It might help to understand some of the issues by 12432785Speter going through the categories: 12532785Speter 12632785Speter How Humans use the word "branch": 12732785Speter 12832785Speter Most development starts with everyone working on the same 12932785Speter software, making changes and heading toward a single goal. This 13032785Speter is called something like "Main Line Development". Note that 13132785Speter though many people do main line development on CVS's "Main 13232785Speter Branch", that is a choice, not a requirement. 13332785Speter 13432785Speter After a release or when one or more developers want to go off 13532785Speter and work on some project for a while, the Software Engineers 13632785Speter assigned to deal with large software issues generate a "Branch 13732785Speter in Development" to support the release or project. (Keep in 13832785Speter mind that a programmer is no more a Software Engineer than a 13932785Speter carpenter is a Civil Engineer.) 14032785Speter 14132785Speter Essentially, the word "branch" implies a way to allow 14232785Speter simultaneous development on the same files by multiple people. 14332785Speter 14432785Speter The above terms are human-oriented. They refer to actions that 14532785Speter people would like to take. They do *not* imply any particular 14632785Speter implementation or set of procedures. Branches in development 14732785Speter can be supported in many different ways. 14832785Speter 14932785Speter How CVS uses the word "branch": 15032785Speter 15132785Speter CVS uses the word "branch" in a number of ways. The two most 15232785Speter important are: 15332785Speter 15432785Speter - The vendor branch holds releases from (normally) an outside 15532785Speter software vendor. It is implemented using a specific RCS branch 15632785Speter (i.e. 1.1.1). 15732785Speter 15832785Speter - The "Main Branch", which normally holds your "Main Line 15932785Speter Development", but is defined as the collection of revisions you 16032785Speter get when you "checkout" something fresh, or when you use the 16132785Speter '-A' option to "update". 16232785Speter 16332785Speter Important Note: The CVS "Main Branch" is *not* the same as the 16432785Speter RCS concept with the same name. If you are using Vendor 16532785Speter Branches, files you have never changed are on three branches at 16632785Speter the same time: 16732785Speter 16832785Speter - The RCS 1.1.1 branch. 16932785Speter - The CVS Vendor branch. 17032785Speter - The CVS "Main Branch". 17132785Speter 17232785Speter The concepts overlap, but they are not equivalent. 17332785Speter 17432785Speter In referring to CVS, "branch" can be used in four other ways: 17532785Speter 17632785Speter - A CVS working directory satisfies the definition of "branch" 17732785Speter for a single developer -- you are on a private "virtual branch" 17832785Speter that does not appear in any of the RCS files or the CVS control 17932785Speter files. 18032785Speter 18132785Speter - The CVS "default branch" is the Repository source for the 18232785Speter collection of files in your working directory. It is *not* the 18332785Speter same as the RCS "default branch". Normally the CVS default 18432785Speter branch is the same as the CVS Main branch. If you use the "-r 18532785Speter <branch_tag>" option to the "checkout" command, you will record 18632785Speter a "sticky" tag that changes your default branch to the one you 18732785Speter checked out. 18832785Speter 18932785Speter - A "magic" branch can be a branch that hasn't happened yet. It 19032785Speter is implemented by a special tag you can check out that is not 19132785Speter attached to a real RCS branch. When you commit a file to a 19232785Speter magic branch, the branch becomes real (i.e. a physical RCS 19332785Speter branch). 19432785Speter 19532785Speter - And, of course, CVS uses "branch" to indicate a 19632785Speter human-oriented "branch in development". 19732785Speter 19832785Speter How RCS uses the word "branch": 19932785Speter 20032785Speter - The RCS "Main Branch" (Synonym: "The Trunk") contains a 20132785Speter series of two-part revision numbers separated by a single '.' 20232785Speter (e.g. 1.2). It is treated specially and is the initial default 20332785Speter branch. (The default default?) 20432785Speter 20532785Speter - The RCS "Default" branch starts out attached to the RCS "Main 20632785Speter Branch". For RCS purposes, it can be changed to point to any 20732785Speter branch. Within CVS, you *must*not* alter the RCS default 20832785Speter branch. It is used to support the CVS idea of a "Main Branch" 20932785Speter and it must either point to the RCS Main Branch, or the Vendor 21032785Speter Branch (1.1.1) if you haven't made any changes to the file 21132785Speter since you executed "import". 21232785Speter 21332785Speter Last modified: _6/13/1997_ 21432785Speter 21532785Speter 2. Why (or when) would I want to create a branch? 21632785Speter 21732785Speter Remember that you can think of your working directory as a "branch for 21832785Speter one". You can consider yourself to be on a branch all the time because 21932785Speter you can work without interfering with others until your project (big 22032785Speter or small) is done. 22132785Speter 22232785Speter The four major situations when you should create a branch: 22332785Speter 22432785Speter When you expect to take a long time or make a large set of changes 22532785Speter that the merging process will be difficult. Both "long" and "large" 22632785Speter are defined in your own environment. 22732785Speter 22832785Speter When you want to be able to "commit" and "tag" your work repeatedly 22932785Speter without affecting others. 23032785Speter 23132785Speter If you ever think you need Source Control for your own work, but don't 23232785Speter want your changes to affect others, create a private branch. (Put your 23332785Speter username in the branch tag, to make it obvious that it is private.) 23432785Speter 23532785Speter When you need to share code among a group of developers, but not the 23632785Speter whole development organization working on the files. 23732785Speter 23832785Speter Rather than trying to share a working directory, you can move onto a 23932785Speter branch and share your work with others by "committing" your work onto 24032785Speter the branch. Developers not working on the branch won't see your work 24132785Speter unless they switch to your branch or explicitly merge your branch into 24232785Speter theirs. 24332785Speter 24432785Speter When you need to make minor changes to a released system. 24532785Speter 24632785Speter Normally a "release" is labeled by a branch tag, allowing later work 24732785Speter on the released files. If the release is labeled by a non-branch tag, 24832785Speter it is easy to add a branch tag to a previously tagged module with the 24932785Speter "rtag" command. If the release is not tagged, you made a mistake. 25032785Speter Recovery requires identifying all revisions involved in the release 25132785Speter and adding a tag to them. 25232785Speter 25332785Speter Last modified: _6/13/1997_ 25432785Speter 25532785Speter 3. How do I create and checkout a branch? 25632785Speter 25732785Speter Suggested technique: 25832785Speter 25932785Speter Attach a non-branch tag to all the revisions you want to branch 26032785Speter from. (i.e. the branch point revisions) 26132785Speter 26232785Speter When you decide you really need a branch, attach a branch tag to the 26332785Speter same revisions marked by the non-branch tag. 26432785Speter 26532785Speter "Checkout" or "update" your working directory onto the branch. 26632785Speter 26732785Speter Suggested procedure when using modules: 26832785Speter 26932785Speter cvs rtag <branch_point_tag> module 27032785Speter 27132785Speter cvs rtag -b -r <branch_point_tag> <branch_tag> <module> 27232785Speter 27332785Speter cvs checkout -r <branch_tag> module 27432785Speter 27532785Speter Suggested procedure when using your working directory, which 27632785Speter contains the revisions of your working files you want to branch from: 27732785Speter 27832785Speter cvs tag <branch_point_tag> 27932785Speter 28032785Speter cvs rtag -b -r <branch_point_tag> <branch_tag> <module> 28132785Speter 28232785Speter cvs update -r <branch_tag> 28332785Speter 28432785Speter In each procedure above, Step #1 applies a non-branch tag to all the 28532785Speter branch point revisions in the module/directory. Though this is not 28632785Speter strictly necessary, if you don't add a non-branch tag to the revisions 28732785Speter you branch from, you won't be able to refer to the branch point in the 28832785Speter future. 28932785Speter 29032785Speter Between steps 1 & 2 you may commit changes. The result would be same 29132785Speter because "rtag -r <oldtag> <newtag>" applies <newtag> to the same 29232785Speter revision that <oldtag> is attached to. You can use this technique to 29332785Speter avoid attaching *any* branch tags until you need them. 29432785Speter 29532785Speter Step B.2 has two corollaries: 29632785Speter 29732785Speter If you plan to create the branch tag before committing anything in 29832785Speter your working directory, you can use "cvs tag -b <branch_tag>" instead 29932785Speter of the "rtag" command. 30032785Speter 30132785Speter The <module> can be a relative path to a directory from which your 30232785Speter working directory was checked out. 30332785Speter 30432785Speter If you have trouble figuring out what <module> to use (or pathname to 30532785Speter use in its place), you can aim it at whatever parent directories you 30632785Speter believe will cover all your work. 30732785Speter 30832785Speter If you are sure the <branch_tag> is not being used anywhere else, you 30932785Speter can even aim it at the whole Repository ($CVSROOT), if you have to. It 31032785Speter might take some extra time, but assuming that your <tag> is a unique 31132785Speter string and you don't use the '-f' option to "rtag -r", "rtag" will 31232785Speter only add a <tag> to files in which it actually *finds* the earlier 31332785Speter <tag>. 31432785Speter 31532785Speter In each procedure above, Step #3 may occur any time after step 2. 31632785Speter Unless you explicitly remove them with "tag -d", a <tag> is permanent. 31732785Speter 31832785Speter The <branch_tag> is an unusual creature. It labels a branch in a way 31932785Speter that allows you to "checkout" the branch, to "commit" files to the end 32032785Speter of the branch and to refer to the end of the branch. It does not label 32132785Speter the base of the branch (the branch point). 32232785Speter 32332785Speter There are two obvious ways to choose the <branch_point_tag> and 32432785Speter <branch_tag> names. But keep in mind that the <branch_tag> is typed by 32532785Speter any developer who wants to work on the branch -- you should make it 32632785Speter mean something to them. 32732785Speter 32832785Speter Style #1 presumes that the simple version string refers to a set of 32932785Speter designed, documented or promised features, not to a specific set of 33032785Speter files. In this case, you tag the branch with the generic Version 33132785Speter string and assume that whenever you refer to "Version", you want the 33232785Speter "latest" set of files associated with that Version, including all 33332785Speter patches. (You can substitute whatever you like for "bp_", as long as 33432785Speter your <branch_point_tag> is some modification of the <branch_tag>.) 33532785Speter 33632785Speter <branch_point_tag> Matching <branch_tag> 33732785Speter 33832785Speter bp_V1_3 V1_3 33932785Speter bp_Release2-3-5 Release2-3-5 34032785Speter bp_Production4_5 Release4_5 34132785Speter 34232785Speter Style #2 presumes that the simple version string refers to the 34332785Speter specific set of files used to construct the first release of 34432785Speter "version". In this case, you tag the branch-point revisions with the 34532785Speter generic Version string and assume that whenever you refer to this 34632785Speter Version, you want the original set of released revisions. To get the 34732785Speter latest patched revisions of the release, you refer to the branch tag 34832785Speter "latest_<branch_point_tag>". (You can substitute what ever you like 34932785Speter for "latest_", as long as your <branch_tag> is some modification of 35032785Speter the <branch_point_tag>.) 35132785Speter 35232785Speter <branch_point_tag> Matching <branch_tag> 35332785Speter 35432785Speter V1_3 latest_V1_3 35532785Speter Release2-3-5 latest_Release2-3-5 35632785Speter Release4_5 latest_Production4_5 35732785Speter 35832785Speter In both styles you can find out what you had to change since the 35932785Speter original release of this Version by typing: 36032785Speter 36132785Speter cvs diff -r <branch_point_tag> -r <branch_tag> 36232785Speter 36332785Speter For Style 1, this is: 36432785Speter 36532785Speter cvs diff -r bp_<branch_tag> -r <branch_tag> 36632785Speter 36732785Speter For Style 2, this is: 36832785Speter 36932785Speter cvs diff -r <branch_point_tag> -r latest_<branch_point_tag> 37032785Speter 37132785Speter Notes on "being on a branch": 37232785Speter 37332785Speter - "update -r <tag>" tells CVS to attach a "sticky tag" to working 37432785Speter directory (in ./CVS/Tag) and the checked-out files (on each line of 37532785Speter ./CVS/Entries). 37632785Speter 37732785Speter - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands 37832785Speter to act as if "-r <tag>" were on the command line. 37932785Speter 38032785Speter - A "sticky" <branch_tag> indicates that the working directory (and 38132785Speter working files) are "on the branch". 38232785Speter 38332785Speter Last modified: _6/13/1997_ 38432785Speter 38532785Speter 4. Once created, how do I manage a branch? 38632785Speter 38732785Speter The most important thing you should know about managing a branch is 38832785Speter that the creation of a branch is not a lightweight act. When you 38932785Speter create a branch, you must also create a set of procedures to keep 39032785Speter track of it. 39132785Speter 39232785Speter Specifically, you must: 39332785Speter 39432785Speter - Remember that the branch exists. (This is non-trivial if you create 39532785Speter a lot of them.) 39632785Speter 39732785Speter - Plan when to merge it back into the main line of development. 39832785Speter 39932785Speter - Schedule the order that multiple branch merges are to be done. 40032785Speter 40132785Speter - If you ever intend to merge branches into each other, instead of 40232785Speter limiting merges of branch work back into the "main line", you must 40332785Speter keep careful track of which parts of which branches have merged into 40432785Speter which other branches. 40532785Speter 40632785Speter The simplest way to deal with branches is to limit their number, 40732785Speter "collapse" them back into the main line as quickly as is reasonable 40832785Speter and forget them. If a group wants to continue working, tell them to 40932785Speter create another branch off the fully merged main line. 41032785Speter 41132785Speter Remember that CVS is just a tool. Over time, it will probably handle 41232785Speter branching better, requiring less careful attendance. But no matter how 41332785Speter good it becomes, the whole idea of "branching" is a complicated 41432785Speter management problem. Don't take it lightly. 41532785Speter 41632785Speter Last modified: _6/13/1997_ 41732785Speter 41832785Speter 5. Are there any extra issues in managing multiple branches? 41932785Speter 42032785Speter If you plan to split from the "main line" and merge back after a time, 42132785Speter the only problem will be scheduling the order of branch merges. As 42232785Speter each branch is merged, the main line must be rebuilt and tested. 42332785Speter Merging multiple branches (i.e. "lines of development") before 42432785Speter building and testing creates more problems than you are ready for. 42532785Speter 42632785Speter If you plan to collapse some branches into others, then move the 42732785Speter combined branches back into the main line, you have to be careful with 42832785Speter the revisions and tags you hand to your "update -j" command, but it 42932785Speter shouldn't be much trouble. 43032785Speter 43132785Speter If you plan to allow every branch to incrementally take the work done 43232785Speter on other branches, you are creating an almost insurmountable 43332785Speter bookkeeping problem. Every developer will say "Hey, I can handle 43432785Speter taking just this little bit," but for the system as a whole it is 43532785Speter disaster. Try it once and see. If you are forced into this situation, 43632785Speter you will need to keep track of the beginning and end points of every 43732785Speter merge ever done. Good Luck. 43832785Speter 43932785Speter Last modified: _6/13/1997_ 44032785Speter 44132785Speter 6. How do I merge a whole branch back into the trunk? 44232785Speter 44332785Speter If you don't have a working directory, you can checkout and merge in 44432785Speter one command: 44532785Speter 44632785Speter cvs checkout -j <branch_tag> <module> 44732785Speter cd <module> 44832785Speter 44932785Speter If you already have a working directory: 45032785Speter 45132785Speter cd <working_directory> 45232785Speter cvs update <== Optional, to bring it up to date. 45332785Speter cvs update -j <branch_tag> 45432785Speter 45532785Speter CVS will print lines beginning with 45632785Speter 45732785Speter 'U' for files that you hadn't changed, but the branch did. 45832785Speter 45932785Speter 'M' for files that you changed and the branch didn't 46032785Speter *and* for files that you both changed that were merged 46132785Speter without overlaps. (This overload is unfortunate.) 46232785Speter 46332785Speter 'C' for files that you both changed in a way that conflicts 46432785Speter with each other. 46532785Speter 46632785Speter You need to go edit all the 'C' files and clean up the conflicts. Then 46732785Speter you must commit them. 46832785Speter 46932785Speter Last modified: _6/13/1997_ 47032785Speter 47132785Speter 7. How do I merge changes from the trunk into my branch or between 47232785Speter branches? 47332785Speter 47432785Speter The idea is similar to the above, but since CVS doesn't treat the main 47532785Speter branch like other branches, you'll have to be more careful. There are 47632785Speter 5 different ways to look at the problem. 47732785Speter 47832785Speter The way to merge *all* changes made on the trunk into a working 47932785Speter branch is to move to the branch you want via "checkout -r" or "update 48032785Speter -r": 48132785Speter 48232785Speter cvs update -r <branch_tag> {optional files} 48332785Speter 48432785Speter Then merge the changes from the trunk into your working branch using 48532785Speter the pseudo-tag named "HEAD": 48632785Speter 48732785Speter cvs up -j HEAD {optional files} 48832785Speter 48932785Speter You will get everything from the branch point of the branch named 49032785Speter <branch_tag> up to the HEAD of the main branch. This is still kind of 49132785Speter strange. If the file is on a branch, HEAD should be the latest thing 49232785Speter on the branch, not the HEAD of MAIN. But that's not the way CVS 49332785Speter (currently) works. 49432785Speter 49532785Speter If you run "cvs up -j HEAD" again after adding more revisions to the 49632785Speter trunk, you may get overlaps for the text you have already merged. It 49732785Speter depends on your version of your RCS "merge" command (actually the "co 49832785Speter -j" option, which depends on the version of "diff3" you configured RCS 49932785Speter to use). 50032785Speter 50132785Speter You can merge the difference between any two <tags> using two "-j" 50232785Speter options on "update" or "checkout". 50332785Speter 50432785Speter Identify the two tags on the branch you want to merge from. 50532785Speter 50632785Speter cvs update -j <tag1> -j <tag2> {optional files} 50732785Speter 50832785Speter This step assumes you were careful about tagging milestones. You can 50932785Speter use this technique for any two <tags> on the same branch, even the 51032785Speter trunk. It is also possible to use tags on different branches, but 51132785Speter you'll have to ponder the meaning of the difference between those two 51232785Speter tags. 51332785Speter 51432785Speter In place of one of the <tags>, you can use a <branch_tag> to refer to 51532785Speter the latest revision on that branch. See 4C.11 and 4C.3 for info on 51632785Speter branch points. 51732785Speter 51832785Speter Merges can also be performed by handing RCS revisions to the '-j' 51932785Speter options, but since revision numbers aren't the same in all files, 52032785Speter merging by number is normally limited to one file. Sets of files with 52132785Speter the exact same trees of branches and revision numbers would work too, 52232785Speter but that's a rare situation. 52332785Speter 52432785Speter To "take" revisions from other branches instead of merging them, see 52532785Speter 4C.19 for an idea. 52632785Speter 52732785Speter A way to gain the effect of merging the main to the branch is to 52832785Speter merge the branch into the main using the normal 52932785Speter 53032785Speter cvs update -A {optional files} 53132785Speter cvs update -j <branch_tag> {optional files} 53232785Speter cvs commit 53332785Speter cvs tag -F -b <same_branch_tag> {optional files} 53432785Speter 53532785Speter See part B of 4D.5 53632785Speter 53732785Speter Other oddities. 53832785Speter 53932785Speter This also works, but is probably not officially supported: 54032785Speter 54132785Speter cvs update -j N {optional files} 54232785Speter 54332785Speter where N is a number. This will merge all the changes from the branch 54432785Speter point up to the highest revision on the main branch starting with N. 54532785Speter For example, if your highest trunk revision is 1.52, you can use this 54632785Speter to grab revisions from the trunk: 54732785Speter 54832785Speter cvs update -j 1 {optional files} 54932785Speter 55032785Speter Another example: Say you have a branch point at rev 1.2 for a branch 55132785Speter named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2. 55232785Speter Then: 55332785Speter 55432785Speter cvs update -j 1 {optional files} 55532785Speter 55632785Speter will merge the changes from 1.2 to 1.4 55732785Speter 55832785Speter cvs update -j 2 {optional files} 55932785Speter 56032785Speter will merge the changes from 1.2 to 2.3 56132785Speter 56232785Speter cvs update -j 3 {optional files} 56332785Speter 56432785Speter will merge the changes from 1.2 to 3.2, which in this example, is 56532785Speter equivalent to the use of "-j HEAD" in part A above. 56632785Speter 56732785Speter The intuitive (at least to me): 56832785Speter 56932785Speter cvs up -j MAIN (or TRUNK) {optional files} 57032785Speter 57132785Speter doesn't work. If the trunk (i.e. "main branch") had an implicit branch 57232785Speter named "MAIN", you could use: 57332785Speter 57432785Speter cvs up -j MAIN:10/26 -j MAIN:now {optional files} 57532785Speter 57632785Speter and refer to date-stamped revisions on the trunk using the 57732785Speter <branch_tag>:<date> support that works on other branches. 57832785Speter 57932785Speter You might also think you could place an explicit tag on branch 1 (or 58032785Speter higher) (e.g. MAINHACK:1) and use it in place of the implicit "MAIN", 58132785Speter but I haven't found the right combination. 58232785Speter 58332785Speter [[If you find working techniques, I'll add them here.]] 58432785Speter 58532785Speter Last modified: _6/13/1997_ 58632785Speter 58732785Speter 8. How do I merge onto the Main Branch a file that exists only on a branch 58832785Speter other than the Main Branch? (i.e. it is in the Attic) 58932785Speter 59032785Speter For how such a file can exist, see 3A.2 and 3A.3. 59132785Speter 59232785Speter For how to avoid creating such a file, see 3A.5. 59332785Speter 59432785Speter Though you might think that the "update -j" command could perform the 59532785Speter "merge" of a file from the side branch to the Main Branch, it isn't 59632785Speter (yet) smart enough. Unfortunately, there is no single CVS command to 59732785Speter do this -- it takes three steps: 59832785Speter 59932785Speter To move something onto the Main Branch from the Attic, you have to 60032785Speter physically move the file from the Attic to the main Repository 60132785Speter directory associated with your working directory. 60232785Speter 60332785Speter It is exactly like resurrecting a removed file. See 3L.4 60432785Speter 60532785Speter I use something like this: (csh-like syntax) 60632785Speter 60732785Speter set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v 60832785Speter $repos/filename,v 60932785Speter 61032785Speter (If you use relative paths in your Repository files, that first line 61132785Speter becomes: set repos = $CVSROOT/`cat ./CVS/Repository`) 61232785Speter 61332785Speter Now that the file is physically in the right place within the 61432785Speter Repository, "update -A" will make it appear in your working directory 61532785Speter on the Main Branch. Do that now. 61632785Speter 61732785Speter You now have a choice. The act of physically moving the file has 61832785Speter fused together the <branch_tag> branch and the Main Branch for this 61932785Speter file. You can continue that way, making changes along the RCS Main 62032785Speter Branch which CVS will (for this type of file only) treat as both the 62132785Speter Main Branch and the <branch_tag> branch. 62232785Speter 62332785Speter The other choice, which I would suggest, is to re-tag the file with 62432785Speter <branch_tag>, restoring a normal-looking magic branch tag to the file: 62532785Speter 62632785Speter cvs tag -F -b <branch_tag> <file> 62732785Speter 62832785Speter After you have done the above, you can run "update -A" or "update -r 62932785Speter <branch_tag>" to resume whatever you were doing before you started 63032785Speter this procedure. 63132785Speter 63232785Speter Caveat: The final result is a file whose revision tree doesn't look 63332785Speter like it was ever on any branch but the Main Branch until the above 63432785Speter "tag -F -b" command was executed. CVS and RCS have no way of saving 63532785Speter the history of the actions you have just performed. 63632785Speter 63732785Speter Last modified: _6/13/1997_ 63832785Speter 63932785Speter 9. How do I know what branch I'm (working) on? 64032785Speter 64132785Speter Type: 64232785Speter cvs status 64332785Speter 64432785Speter and look at the "Sticky Tag" field for each file. If: 64532785Speter 64632785Speter The *same* tag is on *every* file in your working tree, *and* 64732785Speter 64832785Speter That tag matches the contents of the ./CVS/Tag file, *and* 64932785Speter 65032785Speter That tag is a branch tag, 65132785Speter 65232785Speter then you know what branch you are working on. You can get sticky Tag 65332785Speter information directly from the ./CVS/Entries file instead of "cvs 65432785Speter status". 65532785Speter 65632785Speter If all the sticky Tags don't agree, then your directory is temporarily 65732785Speter inconsistent. This is a feature allowing you to make changes (or 65832785Speter perform merges) to individual files on multiple branches without 65932785Speter checking out the whole directory. 66032785Speter 66132785Speter The sticky Tag on each file in the ./CVS/Entries file (as displayed by 66232785Speter the "status" command) indicates what branch the working file is on. 66332785Speter New files are added to the Tag stored in ./CVS/Tag. 66432785Speter 66532785Speter To force your entire working directory onto the same branch, type: 66632785Speter 66732785Speter cvs update -r <branch_tag> 66832785Speter 66932785Speter Last modified: _6/13/1997_ 67032785Speter 67132785Speter 10. Do I really have to know the name of the branch I'm working on? 67232785Speter 67332785Speter If a developer can't be relied on to know what branch of development 67432785Speter to work on, then either the developer's manager isn't planning 67532785Speter branches properly or the developer has serious problems. 67632785Speter 67732785Speter I have found that one of the hardest concepts to get across to 67832785Speter developers (and some managers) is that "a branch in development" (as 67932785Speter opposed to the use of RCS branches to support some other scheme) is a 68032785Speter heavyweight act. Every time you create a real branch in development, 68132785Speter you must spawn a set of managerial procedures and a schedule by which 68232785Speter you plan to merge each branch into each other branch. Unless you plan 68332785Speter to keep it simple and collapse (by merging and forgetting) branches 68432785Speter quickly, they are not to be created lightly. 68532785Speter 68632785Speter In other words, if you don't regularly attend group meetings in which 68732785Speter the branch to be worked on is a major topic of discussion, then the 68832785Speter group is not managing branches properly. 68932785Speter 69032785Speter We created a couple major branches a few months ago and even the 69132785Speter customer service people refer to the "XYZ branch" as a shorthand for 69232785Speter "continuing development on the XYZ project". 69332785Speter 69432785Speter Last modified: _6/13/1997_ 69532785Speter 69632785Speter 11. How do I refer to the revision where I branched so I can see what 69732785Speter changed since the Branch Point on another branch? 69832785Speter 69932785Speter Given the current <branch_tag> format, there is no direct way to refer 70032785Speter to the branch point, which is more useful in many ways than referring 70132785Speter to the branch, which always refers to the latest revision on the 70232785Speter branch. 70332785Speter 70432785Speter When CVS adds a branch tag, it attaches an RCS symbol to a 70532785Speter non-existent revision number containing the revision number of the 70632785Speter branch point as a prefix. (See Section 3O, on the "tag" command.) RCS 70732785Speter can't use the CVS magic branch tag and many of the CVS commands can't 70832785Speter refer to it. 70932785Speter 71032785Speter To be certain of your ability to refer to a branch point, you must 71132785Speter create a "branch point" tag at the same time as the Branch tag. See 71232785Speter 4C.3. 71332785Speter 71432785Speter Last modified: _6/13/1997_ 71532785Speter 71632785Speter 12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch? 71732785Speter 71832785Speter Because your command creates an RCS branch, not a CVS branch. See the 71932785Speter above discussion on branches. RCS branches are used to support CVS 72032785Speter branches, but they are not the same. You can't act as if you have 72132785Speter direct control over the RCS files. 72232785Speter 72332785Speter The "admin" command was placed there as a convenience to allow you to 72432785Speter execute raw "rcs" commands on the Repository, taking advantage of 72532785Speter CVS's ability to find the files in the Repository. 72632785Speter 72732785Speter But you have to remember that you are using RCS commands on a CVS 72832785Speter Repository, which is not generally safe unless you know exactly what 72932785Speter CVS depends on. 73032785Speter 73132785Speter For one thing, CVS insists on control of the default branch. It is set 73232785Speter either to the Main branch or the Vendor branch depending on whether 73332785Speter you have changed the Vendor's code. If you change the default branch, 73432785Speter you are monkeying with the internals and you will get unexpected 73532785Speter results. 73632785Speter 73732785Speter To set your "default CVS branch" to BRANCH1, you must use "checkout" 73832785Speter or "update" with the "-r BRANCH1" option. Then you have changed CVS's 73932785Speter idea of your "default branch", which has little to do with RCS's 74032785Speter default branch. 74132785Speter 74232785Speter Last modified: _6/13/1997_ 74332785Speter 74432785Speter 13. Is it possible to set the "default CVS branch" for everyone? 74532785Speter 74632785Speter No. It doesn't work that way. 74732785Speter 74832785Speter When using CVS, all administrative information (such as what branch 74932785Speter you checked out) is stored in CVS sub-directories, local to the user. 75032785Speter There is no global state, other than the description and logging files 75132785Speter in the $CVSROOT/CVSROOT directory. 75232785Speter 75332785Speter You tell "checkout" or "update" what branch you want to check out via 75432785Speter the "-r <tag>" option. The default is CVS's "Main Branch". 75532785Speter 75632785Speter I don't see a problem in *designing* a new way to indicate what branch 75732785Speter you get by default, instead of the main one, but that's not how it 75832785Speter currently works. 75932785Speter 76032785Speter Last modified: _6/13/1997_ 76132785Speter 76232785Speter 14. How do I perform a large merge? 76332785Speter 76432785Speter Large merges require a bit more planning to be able to track what has 76532785Speter happened in the inevitable cases where something goes wrong. No tool 76632785Speter can force a "merge" to make perfect sense. 76732785Speter 76832785Speter Though you can handle the details in many different ways, the two ends 76932785Speter of the spectrum of merge techniques are: gonzo and paranoid. 77032785Speter 77132785Speter The gonzo method assumes that you know everything about your sources 77232785Speter so that recovery from failures is "just a matter of typing." You 77332785Speter created the branch this way: 77432785Speter 77532785Speter cvs checkout <module> 77632785Speter cd <module> 77732785Speter cvs tag -b <branch_tag> 77832785Speter cvs update -r <branch_tag> 77932785Speter >>> Edit away. 78032785Speter cvs commit <<== Onto branch 78132785Speter 78232785Speter Now you want to merge your branch back into the Main branch, you are 78332785Speter certain you can make it work, or at least detect all the failures, so 78432785Speter you dive in and hack away: (For simplicity, we will assume you are 78532785Speter collapsing (i.e. merging and forgetting) a side-branch into the Main 78632785Speter branch from your single working directory.) 78732785Speter 78832785Speter cvs update -A 78932785Speter cvs update -j <branch_tag> 79032785Speter >>> Edit the 'C' files and remove the overlaps. 79132785Speter >>> Edit some more to make it all compile and work. 79232785Speter cvs commit 79332785Speter 79432785Speter Looks simple. For more details on the output from the "update -j" 79532785Speter command, see 3P.2 and 4C.6. 79632785Speter 79732785Speter Note: You could also checkout a whole new working directory and 79832785Speter perform the merge at the same time by replacing the two 79932785Speter update commands with these two commands: 80032785Speter 80132785Speter cvs checkout -j <branch_tag> <module> 80232785Speter cd <module> 80332785Speter 80432785Speter The paranoid way is more difficult, but it can catch all sorts of 80532785Speter problems. You created the branch this way: 80632785Speter 80732785Speter cvs checkout <module> 80832785Speter cd <module> 80932785Speter cvs tag <branch_point_tag> 81032785Speter cvs tag -b <branch_tag> 81132785Speter cvs update -r <branch_tag> 81232785Speter >>> Edit away. 81332785Speter cvs commit <<== Onto branch 81432785Speter 81532785Speter The extra tag command places a non-branch tag on the Branch Point, an 81632785Speter act that makes it easier to do "diffs" later. Now we decide to perform 81732785Speter the merge: 81832785Speter 81932785Speter cvs tag <latest_on_branch_tag> 82032785Speter cvs update -A 82132785Speter *1* cvs diff -r <branch_point_tag> -r <latest_on_branch_tag> 82232785Speter >>> *1* shows all the changes on the branch. 82332785Speter *2* cvs diff -r <branch_point_tag> -r HEAD 82432785Speter >>> *2* shows the changes on the trunk since branching. 82532785Speter cvs tag <premerge_tag> 82632785Speter cvs update -j <branch_tag> 82732785Speter >>> Edit the 'C' files and remove the overlaps. 82832785Speter *3* cvs diff 82932785Speter >>> Verify that *3* matches *1*, except for line numbers. 83032785Speter cvs commit 83132785Speter cvs tag <just_merge_changes_tag> 83232785Speter >>> Edit some more to make it all compile and work. 83332785Speter cvs commit 83432785Speter cvs tag <after_merge_cleanup_tag> 83532785Speter 83632785Speter The reason *3* and *1* match so closely is that they are the 83732785Speter differences between two pairs of starting points and ending points 83832785Speter after the same data was inserted. If they are significantly different, 83932785Speter you will want to figure out why. 84032785Speter 84132785Speter NOTE: You will have to tell everyone to stay the hell out of the 84232785Speter Repository while you do this. If they commit something while you are 84332785Speter in the middle of a merge, your job will be much more difficult. If 84432785Speter they "update" at the wrong time, their work will be randomized until 84532785Speter you finish. It's better to call a halt. 84632785Speter 84732785Speter See 3H.13 for some more information about dealing with merges after 84832785Speter import. The last part of the procedure is applicable to any large 84932785Speter merge. 85032785Speter 85132785Speter Last modified: _6/13/1997_ 85232785Speter 85332785Speter 15. Is a Vendor merge any different from a branch merge? 85432785Speter 85532785Speter No. In most ways, a Vendor branch is exactly the same as any other 85632785Speter branch. In a Vendor merge, the data is append to the branch by the 85732785Speter "import" command, rather than by hand-editing, but the merge process 85832785Speter is the same. 85932785Speter 86032785Speter See the "import" command in section 3H. 86132785Speter 86232785Speter Last modified: _6/13/1997_ 86332785Speter 86432785Speter 16. How do I go back to a previous version of the code on a branch? 86532785Speter 86632785Speter 86732785Speter 86832785Speter 86932785Speter You can avoid digging into RCS revision numbers (executing "update 87032785Speter -r (rev)" on each file) by trying one of these: 87132785Speter 87232785SpeterUse non-branch tags as you normally would. Non-branch tags 87332785Speter attach to specific revisions, so a "tag (tag)" command would 87432785Speter mark the revisions you have in your working directory, which 87532785Speter are on your branch. If you need to retrieve them, use "update 87632785Speter -r (non-branch-tag)" 87732785Speter 87832785Speter Doing this overrides the sticky (branch-tag) attached to your 87932785Speter working directory with a non-branch tag, which means you won't 88032785Speter be able to commit until you again move forward to the end of 88132785Speter the branch with "update -r (branch-tag)". 88232785Speter 88332785SpeterUse the "update -r (branch-tag):(date)" trick. 88432785Speter 88532785Speter This is almost like using the '-D' option, but it looks for 88632785Speter revisions extant on (date) only along the given branch. 88732785Speter 88832785Speter As in #1, you can't commit to this kind of working area, 88932785Speter because it has a sticky date referring to revisions in the 89032785Speter middle of a branch. 89132785Speter 89232785Speter[comment from the audience: You are dreaming.. 89332785Speterthis does not work.. try it, you get 89432785SpeterNo such tag: "MYTAG:May 1" 89532785Speteror similar. I wish it did because I need it. julian@whistle.com] 89632785Speter 89732785Speter 89832785SpeterYou can branch a branch. 89932785Speter 90032785Speter If you add a branch tag to file in a working directory that was 90132785Speter checked out on a branch, you will branch the branch. This 90232785Speter works just fine, though you'll have to play some games to merge 90332785Speter everything back together again. You'll also create 6-part 90432785Speter revision numbers. (They'll be 8-part revision numbers if you 90532785Speter branch a branch that started out with some unmodified files on 90632785Speter the Vendor branch. Think about it. How does revision 90732785Speter 1.2.4.2.4.2.2.1 grab you?) 90832785Speter 90932785Speter 91032785Speter(fixed formatting, kingdon@cyclic.com) 91132785Speter 91232785Speter Last modified: _9/8/1997_ 91332785Speter 91432785Speter 17. Once I've found the files I want, how do I start changing them? I keep 91532785Speter getting warnings about sticky tags. 91632785Speter 91732785Speter What you probably did was type "cvs update -r <tag>" where <tag> is a 91832785Speter non-branch tag. "update" created a sticky tag for a specific revision, 91932785Speter not a branch. To start working right there, you have to create a 92032785Speter branch to work on. 92132785Speter 92232785Speter You have two choices. 92332785Speter 92432785Speter You can do it in place and keep working: 92532785Speter 92632785Speter cvs tag -b <branch_tag> <<== To tag the current files. 92732785Speter cvs update -r <branch_tab> <<== To move onto the branch. 92832785Speter 92932785Speter You can do it "externally" and create a new working directory: 93032785Speter 93132785Speter cvs rtag -b -r <tag> <branch_tag> <module> 93232785Speter cvs checkout -r <branch_tag> <module> 93332785Speter 93432785Speter <module> can be a relative path within the Repository. 93532785Speter 93632785Speter <tag> in the above is the non-branch tag you placed earlier 93732785Speter that caused the error in your question. Be warned that 93832785Speter if <tag> is not set on all the files (or all the right 93932785Speter revisions) you won't get exactly what you wanted. 94032785Speter 94132785Speter Last modified: _6/13/1997_ 94232785Speter 94332785Speter 18. Why do I get the latest files on the branch when I tried to "update -r 94432785Speter <tag>"? 94532785Speter 94632785Speter If "update -r <tag>" always retrieves the latest files on a branch, 94732785Speter then <tag> is really a <branch_tag>. A branch tag is supposed to be 94832785Speter used to grab a branch to work on. Since you can't modify a file in the 94932785Speter middle of a branch, checking out a <branch_tag> will give you the 95032785Speter latest revision on the branch. 95132785Speter 95232785Speter If you want to "checkout" a specific collection of revisions, you must 95332785Speter use a "non-branch" tag. See the first part of 4C.16. 95432785Speter 95532785Speter Last modified: _6/13/1997_ 95632785Speter 95732785Speter 19. How can I avoid a merge? I just want to move the latest revision on my 95832785Speter working branch directly onto the trunk. 95932785Speter 96032785Speter There is no direct way to do this using CVS, though the technique is 96132785Speter not difficult using shell commands. Here's one way: 96232785Speter 96332785Speter Move your working directory to the Main Branch. 96432785Speter 96532785Speter cvs update -A 96632785Speter 96732785Speter Use "update -p" to grab the latest revision on the branch and write 96832785Speter it over your working files. Make sure you don't have an modified files 96932785Speter -- you will lose them. The following is in "csh" syntax. Change the 97032785Speter wildcard to grab the files you want 97132785Speter 97232785Speter foreach i (Makefile *.cc *.hh) 97332785Speter cvs update -p -r <branch_tag> $i > $i 97432785Speter end 97532785Speter 97632785Speter Commit all the working files onto the Main Branch. 97732785Speter 97832785Speter cvs commit -m 'Moved branch <branch_tag> onto MAIN' 97932785Speter 98032785Speter You should experiment with the above before blasting everything. 98132785Speter 98232785Speter Last modified: _6/13/1997_ 98332785Speter 98432785Speter 20. How to I avoid merge collisions in the RCS $\Log$ data? 98532785Speter 98632785Speter In short, you can't. The RCS $\Log$ keyword is handled differently 98732785Speter from all other RCS keywords. 98832785Speter 98932785Speter On the info-cvs mailing list, there is a periodic discussion that goes 99032785Speter something like this: 99132785Speter 99232785Speter Question: How do I deal with $\Log$? Answer1: You can't do much with 99332785Speter it. Here's how it works. . . Answer2: I've found a limited way to use 99432785Speter it. . . Answer3: Get rid of it. $\Log$ is an abomination. 99532785Speter 99632785Speter I tend to lean toward answer #3. There are only two sets of people who 99732785Speter would ever have access to logs stored within sources files, developers 99832785Speter and source customers. 99932785Speter 100032785Speter For developers: 100132785Speter 100232785Speter Log entries within sources files are notoriously incomplete, rushed, 100332785Speter poorly phrased and in many cases incorrect, making them useless for 100432785Speter debugging or file maintenance. I remember a maxim from "Software 100532785Speter Tools" (I believe): "Read the code, not the comments." No managerial 100632785Speter order or plan for programmer discipline will affect this in the real 100732785Speter world. 100832785Speter 100932785Speter Log entries are usually in an unreadable mixture of styles. Many log 101032785Speter entries are just plain meaningless. Some are foolish. Some are even 101132785Speter insulting. Examples: 101232785Speter 101332785Speter "Corrected spelling of misspelling." "Bug fix." "Reversed stupid 101432785Speter change in previous revisions." "If Joe could do his job, this would 101532785Speter already have worked." 101632785Speter 101732785Speter Log entries are not managed well by the tools. Any merge can cause 101832785Speter conflicts in the $\Log$ data. Branch merges produce incomplete logs. 101932785Speter They can be edited into chaos and they are not regenerated. They waste 102032785Speter space duplicating information available to the developer with a single 102132785Speter command. 102232785Speter 102332785Speter Even if correct when originally entered, as changes are made to the 102432785Speter file, log entries become false over time. Humans are not good at 102532785Speter reading down through a list and remembering only the last change 102632785Speter affecting something. Over time *most* of the log is wrong. 102732785Speter 102832785Speter Even if still correct, the log data is almost useless to developers 102932785Speter without the code diffs. If you can get code diffs, you can display the 103032785Speter log. 103132785Speter 103232785Speter For source customers the problem is even worse. The last thing you 103332785Speter want to show customers is a hodge-podge of tiny comments about large 103432785Speter changes followed by a series of emergency fixes before delivery. If 103532785Speter you distribute sources, then you should provide documentation, or 103632785Speter changelogs reviewed by people who won't let comments like "Fixed for 103732785Speter stupid customer." out the door. 103832785Speter 103932785Speter Conclusion: Though some people would prefer to see in this FAQ 104032785Speter techniques for making the $\Log$ entries the best they can be, I 104132785Speter believe them to be a lost cause. My suggestion is to hunt down, root 104232785Speter out and destroy all occurrences of $\Log$ and the unusable data 104332785Speter attached to it wherever you may find it. 104432785Speter 104532785Speter Last modified: _6/13/1997_ 104632785Speter 104732785Speter 21. Why should I trust automatic merges? 104832785Speter 104932785Speter Some developers have the feeling that three-way merging doesn't work. 105032785Speter They fear and distrust the way the "update" command automatically 105132785Speter merges committed changes from the Repository into the working file. 105232785Speter 105332785Speter Experience has shown that most merges are utterly painless and most of 105432785Speter the rest are easily resolved. The few conflicts that cause headaches 105532785Speter are nearly all due to poor communication between developers, a problem 105632785Speter no source control system can obviate. 105732785Speter 105832785Speter Some developers were troubled in the past by flaky Unix software. I 105932785Speter can't say that everything is perfect, but the tools CVS depends on 106032785Speter (RCS and diff, mainly) are fairly solid nowadays. They work. 106132785Speter 106232785Speter Since it does seem to work for most of us, the algorithm is unlikely 106332785Speter to change soon. Why not test it on a couple trouble spots and if it 106432785Speter works for you, use it for a while? Then you can make an informed 106532785Speter decision. 106632785Speter 106732785Speter Last modified: _6/13/1997_ 106832785Speter 106932785Speter 22. How does CVS decide if it can safely perform a merge? 107032785Speter 107132785Speter CVS can merge any text file, possibly discovering a conflict and 107232785Speter leaving overlaps for you to edit. Editing the conflict markers out of 107332785Speter the file is a moment's work, but resolving the conflict could take an 107432785Speter arbitrary amount of time. CVS works to determine if it *should* merge, 107532785Speter not if it *can*. 107632785Speter 107732785Speter See 2B.6 for how the merge proceeds. 107832785Speter 107932785Speter Last modified: _6/13/1997_ 108032785Speter 108132785Speter 23. After resolving merge conflicts in a file, what if I want to keep my 108232785Speter previous version, and not take any of the branch changes? 108332785Speter 108432785Speter If you want to retain your previous version, a version on the MAIN 108532785Speter branch greater than 1.1 (one you committed there), just throw the 108632785Speter merged file away and "cvs update" the file. 108732785Speter 108832785Speter You don't need to commit something to remember it. The tags you place 108932785Speter before and after the merge should give all the handles you need to 109032785Speter find various versions. You don't have to create a new version of the 109132785Speter file. 109232785Speter 109332785Speter If you want to retain the previous Vendor revision, you can grab a 109432785Speter copy of it using "cvs update -p" and commit it or use the technique 109532785Speter described in 3B.3 to revert back to the Vendor branch. 109632785Speter 109732785Speter Last modified: _6/13/1997_ 109832785Speter 109932785Speter Category: /Advanced_Topics_/Engineering/ 110032785Speter 110132785Speter " + Engineering" 110232785Speter 110332785Speter 1. Where can I find out about Software Engineering? 110432785Speter 110532785Speter A couple different people suggested this book: 110632785Speter 110732785Speter Software Configuration Management: Coordination for Team Productivity; 110832785Speter Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0 110932785Speter 111032785Speter A number of others suggested Appendix B of the book "Decline and Fall 111132785Speter of the American Programmer" by Ed Yourdon, called "The Programmer's 111232785Speter Bookshelf". It list 87 books you are expected to have read. Since they 111332785Speter publish many of the books, Prentice-Hall distributes this list as 111432785Speter "Prentice Hall Professional Technical reference PTR-125-AA3. 111532785Speter 111632785Speter One interesting item from the Yourdon book: The total number of 111732785Speter professional computer books sold is less than the number of 111832785Speter programmers currently in the United States. It wasn't clear from the 111932785Speter book whether this meant "per year" or not, but it is still 112032785Speter frightening. 112132785Speter 112232785Speter Last modified: _6/13/1997_ 112332785Speter 112432785Speter 2. How do I flexibly arrange the modules file to describe my sources? 112532785Speter 112632785Speter An equivalent question might be, "How do I structure my sources?" This 112732785Speter can be a difficult question especially in the areas that are more 112832785Speter political than technical. 112932785Speter 113032785Speter Generally you want to think about which pieces of your system need to 113132785Speter be checked out together, built as one system or tagged as a consistent 113232785Speter whole. You should certainly create module names that correspond to 113332785Speter complete, buildable collections that you would tag and release as one 113432785Speter "product". It is also convenient to create module names for small 113532785Speter sections of the Repository containing files that will all be worked on 113632785Speter at the same time by the same person or group. 113732785Speter 113832785Speter Once you have defined the structure of your work, you can usually see 113932785Speter how to lay it out in a Repository. After that the modules file is 114032785Speter easy. You set up module names and aliases to match what you need to 114132785Speter check out by name. If you like relative directories, it is possible, 114232785Speter but not recommended, to work completely without a modules file. See 114332785Speter 1D.11 and 2C.7 for some info about the modules file. 114432785Speter 114532785Speter Here are a few types of modules. You should experiment to see what 114632785Speter kind of structure each of these produces. They all have different 114732785Speter uses. 114832785Speter 114932785Speter Connected projects in one group with two separate helper 115032785Speter directories. The helper directories can contain build tools, header 115132785Speter files, libraries, or whatever you like. 115232785Speter 115332785Speter These are all aliases that checkout relative pathnames. The equivalent 115432785Speter results could be produced by placing the selected relative pathnames 115532785Speter on the "cvs checkout" command line. 115632785Speter 115732785Speter pr1 -a P1 HELPERS 115832785Speter pr2 -a P2 HELPERS 115932785Speter pr3 -a P3 HELPERS 116032785Speter pr12 -a P1 P2 HELPERS 116132785Speter pr13 -a P1 P3 HELPERS 116232785Speter pr23 -a P2 P3 HELPERS 116332785Speter 116432785Speter P1 -a group1/proj1 116532785Speter P2 -a group1/proj2 116632785Speter P3 -a group1/proj3 116732785Speter HELPERS -a group1/helper1 group1/helper2 MAKEFILE 116832785Speter MAKEFILE -a group1/Makefile 116932785Speter 117032785Speter Actual Repository directory structure: (from $CVSROOT down) 117132785Speter 117232785Speter group1/ Makefile The top level Makefile. helper1/ helper2/ Helper 117332785Speter files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/ 117432785Speter Files and dirs 117532785Speter 117632785Speter "checkout group1" produces a duplicate of the above. "checkout projX" 117732785Speter produces all but "projY" and "projZ". "checkout projXY" produces all 117832785Speter but "projZ". 117932785Speter 118032785Speter Here is the exact same set of module names describing the same 118132785Speter Repository layout using module names (and aliases containing module 118232785Speter names) instead of merely aliases for relative pathnames. 118332785Speter 118432785Speter There is one difference in the result. The name of the top level 118532785Speter directory in the checked out working tree will match the "module" name 118632785Speter (e.g. pr1) instead of always being "group1" as it was in the first 118732785Speter example above. 118832785Speter 118932785Speter pr1 group1 proj1 &HELPERS 119032785Speter pr2 group1 proj2 &HELPERS 119132785Speter pr3 group1 proj3 &HELPERS 119232785Speter pr12 group1 proj1 proj2 &HELPERS 119332785Speter pr13 group1 proj1 proj3 &HELPERS 119432785Speter pr23 group1 proj2 proj3 &HELPERS 119532785Speter 119632785Speter HELPERS -a helper1 helper2 group1-Makefile 119732785Speter helper1 group1/helper1 119832785Speter helper2 group1/helper2 119932785Speter group1-Makefile -d . group1 Makefile 120032785Speter 120132785Speter The above line (with the -d in it) says that when the module named 120232785Speter "group1-Makefile" is checked out, the file named Makefile file will be 120332785Speter found in a directory named $CVSROOT/group1 and will be checked out 120432785Speter into a directory named '.', which obviously already exists. 120532785Speter 120632785Speter The & references say to interpret those pathnames relative to the 120732785Speter directory where the whole module is stored. For the "pr1" module, that 120832785Speter directory is "group1", so the &HELPERS reference winds up placing 120932785Speter Makefile in '.' relative to "group1". 121032785Speter 121132785Speter A short one containing the basic "module" actions: 121232785Speter 121332785Speter m1 head/path file1 dir2 file3 dir4 file5 121432785Speter 121532785Speter When checked out, a directory named "m1" appears in your current 121632785Speter directory. Elements named file1, dir2, file3, dir4, and file5 appear 121732785Speter in it. They were originally taken as relative paths from 121832785Speter $CVSROOT/head/path. 121932785Speter 122032785Speter Here's another way to construct a working directory out of pieces of 122132785Speter the Repository: 122232785Speter 122332785Speter projX projX Makefile &projX_inc &projX_src &projX_doc 122432785Speter 122532785Speter # The first line selects a single file within projX, plus 122632785Speter # the contents of three other modules. Those three other 122732785Speter # modules rename their directories. 122832785Speter 122932785Speter projX_inc -d include projX/inc projX_src -d source projX/src projX_doc 123032785Speter -d documentation projX/doc 123132785Speter 123232785Speter A Unix tree. This is similar to what CVS was developed for and the 123332785Speter way I have used it for years. 123432785Speter 123532785Speter # Top level 123632785Speter unix unix 123732785Speter u_bin unix/bin 123832785Speter u_etc unix/etc 123932785Speter u_man unix/man 124032785Speter usr-bin unix/usr.bin 124132785Speter 124232785Speter # Subdirs of top level dirs. (tiny subset) 124332785Speter ls unix/bin/ls 124432785Speter fsck unix/etc/fsck 124532785Speter man8 unix/man/man8 124632785Speter 124732785Speter # Programs without subdirs. (tiny subset) 124832785Speter cat unix/bin Makefile cat.c 124932785Speter uniq unix/usr.bin Makefile uniq.c 125032785Speter 125132785Speter # /usr/local/src 125232785Speter localsrc localsrc 125332785Speter gnu localsrc/gnu 125432785Speter public localsrc/public 125532785Speter X11 localsrc/X11 125632785Speter 125732785Speter # GNU and PD tools 125832785Speter cvs localsrc/gnu/cvs 125932785Speter emacs localsrc/gnu/emacs 126032785Speter rcs localsrc/gnu/rcs 126132785Speter btoa localsrc/public/btoa 126232785Speter tcsh localsrc/public/tcsh 126332785Speter 126432785Speter # X11 related items. 126532785Speter tvtwm localsrc/X11/contrib/tvtwm 126632785Speter 126732785Speter "unix" was checked out and built from the top down, using a set of 126832785Speter Makefiles that knew about the whole structure. "localsrc" was kept 126932785Speter checked out in /usr/local/src. 127032785Speter 127132785Speter At any time I could run "checkout ls" or "checkout cat" and get a 127232785Speter simple directory with only that tool in it, plus a subset Makefile 127332785Speter that knew how to build that tool against the installed (or alternate, 127432785Speter via environment variables) headers and libraries. 127532785Speter 127632785Speter I found it very handy to be able to run "ls" and see the three tools I 127732785Speter was porting that week. 127832785Speter 127932785Speter Last modified: _6/13/1997_ 128032785Speter 128132785Speter 3. Can I have multiple source repositories, one for each project? 128232785Speter 128332785Speter Yes, you can have as many Repositories as you like. But each 128432785Speter Repository must be managed separately, creating additional work. 128532785Speter 128632785Speter Question 4A.1 provides a short description of setting up a single 128732785Speter Repository. A few additional considerations: 128832785Speter 128932785Speter It is a good idea to start by creating a single Repository and split 129032785Speter it up (or create additional Repositories) only if you believe it is 129132785Speter really necessary. I would only create a new Repository if the data is 129232785Speter completely disconnected from the rest of the main Repository. 129332785Speter 129432785Speter If there is a lot of overlap among the developers working on the 129532785Speter collections of files you want to place in different Repositories, or 129632785Speter if there is any connection between those collections, I would go out 129732785Speter of my way to create a single Repository. It is much easier to manage. 129832785Speter 129932785Speter Disk space should not be a factor since you can build up a 130032785Speter Repository using symbolic links and/or remote mounts. 130132785Speter 130232785Speter Each Repository is completely distinct. You can't check out modules 130332785Speter from different Repositories at the same time. A better way of looking 130432785Speter at it is that if you *can* check out two modules or directories with a 130532785Speter single "checkout" command (without contortions or explicit absolute 130632785Speter pathnames), then they are in the same Repository. 130732785Speter 130832785Speter To "checkout" modules from multiple Repositories, you must use the 130932785Speter "cvs -d" option on all CVS commands or alter your $CVSROOT variable 131032785Speter when you change focus to another Repository. If you work with multiple 131132785Speter Repositories, it is a good idea to configure CVS to use absolute 131232785Speter pathnames in the ./CVS/Repository file, since most commands (other 131332785Speter than "checkout") will use that file rather than $CVSROOT. 131432785Speter 131532785Speter If you configure CVS to use relative pathnames in your 131632785Speter ./CVS/Repository files, you must always be careful to set your 131732785Speter $CVSROOT properly or you will get unexpected results. 131832785Speter 131932785Speter If you have two modules or directories by the same name at the same 132032785Speter relative path inside two different Repositories, you are asking for 132132785Speter disaster. You could unexpectedly update a directory with completely 132232785Speter unrelated files. This is not a fanciful example -- a Repository is 132332785Speter occasionally duplicated for release purposes in which case *all* the 132432785Speter paths in the two Repositories are the same. 132532785Speter 132632785Speter Last modified: _6/13/1997_ 132732785Speter 132832785Speter 4. Who should administer the Repository and manage the modules file? 132932785Speter 133032785Speter This is a "management style" question. In large or traditional groups, 133132785Speter the CVS procedures are warped to conform to local conventions. In 133232785Speter small groups, in groups with strong personalities or on new projects 133332785Speter the choice of source control procedures can help create some of the 133432785Speter working environment. Here is a taxonomy of environments I have worked 133532785Speter in or helped set up: 133632785Speter 133732785Speter Situation 1. 133832785Speter 133932785Speter A small number of competent developers working on a medium size 134032785Speter project. We all got along and we all respected each other (at least 134132785Speter technically). Anyone edited anything. 134232785Speter 134332785Speter Modules and Repository admin was mostly left to me. I never found a 134432785Speter problem in minor changes made by anyone else. 134532785Speter 134632785Speter Situation 2. 134732785Speter 134832785Speter A large number of experienced developers sprinkled with wackos. Many 134932785Speter of the developers didn't want to deal with any kind of source control. 135032785Speter They wanted a full-service source control system that caused them zero 135132785Speter thought. 135232785Speter 135332785Speter I learned "big stick" diplomacy here. There was a small number of 135432785Speter "designated" (by me) people who were allowed to do *anything* other 135532785Speter than "update" and "commit". Even "checkouts" were controlled. This is 135632785Speter where I found "history" and "release" the most useful. 135732785Speter 135832785Speter Situation 3. 135932785Speter 136032785Speter A small number of developers who wanted me to "help", but who didn't 136132785Speter want to deal with anything other than their favorite algorithms. 136232785Speter 136332785Speter I didn't have the time to baby-sit this group, so I designated one of 136432785Speter them to be my official contact and made him do it all. He felt sullied 136532785Speter by the requirement to pay attention to anything other than his pet 136632785Speter coding projects, but enjoyed the "status" of being the only one who 136732785Speter could touch the control files without my kicking the chair out from 136832785Speter under him. 136932785Speter 137032785Speter Situation 4. 137132785Speter 137232785Speter A huge number of developers of covering the whole spectrum of 137332785Speter competence and experience split into 20 groups, none of which 137432785Speter cooperated with the others, working on 57 different projects, most of 137532785Speter which didn't inter-operate. 137632785Speter 137732785Speter Managing it in any coherent way was not my responsibility (and beyond 137832785Speter my tolerance for chaos). Too many people. So I privately designated a 137932785Speter person in each group to be the contact and kept watch on the 138032785Speter Repository activity. When something went wrong, I notified the contact 138132785Speter for the group and told him what was happening and *he* kept his troops 138232785Speter in line. They were tougher with their own group that I would have 138332785Speter been. 138432785Speter 138532785Speter Eventually only a few people were willing to touch the control files, 138632785Speter since they were flamed from all directions if they screwed up. 138732785Speter 138832785Speter Situation 5. 138932785Speter 139032785Speter In a medium group of really *serious*, and seriously overworked, 139132785Speter people, someone else was designated the "master". I convinced the 139232785Speter master I knew what I was doing and went on my way. 139332785Speter 139432785Speter No one else in the world was allowed to touch anything. 139532785Speter 139632785Speter Situation 6. 139732785Speter 139832785Speter In a large amorphous group of beginners, experts and clowns, over whom 139932785Speter no one had official control, I was forced to employ a group of 140032785Speter relative beginners (who became experts rather quickly) to police the 140132785Speter world. The ultimate in locking the barn after the horse was stolen, we 140232785Speter kept Chaos from destroying us only by use of superior firepower. 140332785Speter 140432785Speter My choice, if allowed, is to let anyone touch anything. I keep backups 140532785Speter of important items and let people know individually whether I want 140632785Speter them to touch things or not. If someone on my "no touch" list touches 140732785Speter and succeeds, they are allowed more slack. If they screw up after 140832785Speter being warned, their screwup becomes public. After a few months, I 140932785Speter usually have no trouble keeping the world running smoothly, at least 141032785Speter from my (and CVS's) perspective. 141132785Speter 141232785Speter Last modified: _6/13/1997_ 141332785Speter 141432785Speter 5. Isn't disk space a big factor? CVS copies files out of the Repository, 141532785Speter duplicating everything. 141632785Speter 141732785Speter Everyone knows that disk space is getting cheaper. How do we reconcile 141832785Speter this with the equally well-known problem that *all* disk is *always* 141932785Speter filled up? 142032785Speter 142132785Speter In my opinion, the main reason disk space will never be an unlimited 142232785Speter resource is that it is the major variable in organizational time/space 142332785Speter tradeoffs. It isn't a problem of waste or an aspect of Murphy's law, 142432785Speter as some claim it is, but rather a direct consequence of good 142532785Speter management. Disk space is, and will always be, a limited resource. 142632785Speter 142732785Speter First, the cost of *deploying* that disk is not dropping as fast as 142832785Speter the cost of the storage medium. The cost of machines to hold the disks 142932785Speter and the networks to connect them are dropping more slowly than disk 143032785Speter media. And the cost of the human time necessary to manage the 143132785Speter machines, networks, disks, and the developers using them, is not 143232785Speter dropping at all. The cost of human time continues to rise. 143332785Speter 143432785Speter If management decides that expensive human time can be saved by using 143532785Speter all that new disk space to keep the last three releases online, then 143632785Speter that's what it will be used for. If each release takes up a Gigabyte 143732785Speter and you support 30 platforms, a simple time-saving suggestion has just 143832785Speter grabbed 100 Gigabytes of disk space. And we've ignored the potential 143932785Speter disk storage needed to support "better Customer Service", another 144032785Speter management refrain. 144132785Speter 144232785Speter Even at 30 cents per Megabyte (next year's price), you've just used up 144332785Speter $30,000 of disk space. And that doesn't count the computers, tape 144432785Speter drives and humans necessary to maintain and deploy all of it. Spending 144532785Speter money to save time has its own overhead, too. 144632785Speter 144732785Speter Binaries are getting bigger. Graphics and data collection devices can 144832785Speter eat up any amount of disk. There are more tools available, more 144932785Speter libraries, more raw data than you can ever store. My home computer has 145032785Speter a Gigabyte of disk on it. It could easily handle 30. 145132785Speter 145232785Speter The "economy" of disk storage media will never remove the need to 145332785Speter manage disk space. 145432785Speter 145532785Speter So, here's an un-reviewed suggestion originally from Graydon Dodson 145632785Speter <grdodson@lexmark.com>, which I've altered and edited heavily. 145732785Speter 145832785Speter - Keep a directory where the whole tree is checked out. (It might be 145932785Speter built and tested once in a while to make sure it is worth linking to, 146032785Speter but that doesn't affect the source control aspect of this procedure). 146132785Speter Let's call it /master/build. 146232785Speter 146332785Speter - Write a tool that creates a tree of directories (like the X11 146432785Speter "lndir" command) filled with links to the checked out files in the 146532785Speter /master/build tree. 146632785Speter 146732785Speter This tool should also provide real copies of, not symlinks to, all the 146832785Speter files within the CVS administrative directories. 146932785Speter 147032785Speter - You could also provide a way for the tool to take a list of whole 147132785Speter directories that you will never change, for which it would create a 147232785Speter single symlink to the directory and not a subtree of symlinks to 147332785Speter files. Or you could rm -r pieces of the resulting working directory 147432785Speter yourself and replace it with links. 147532785Speter 147632785Speter - If you want to edit a file, you have to grab a real copy and keep it 147732785Speter until your revision shows up in the /master/build tree. I'd create a 147832785Speter script to do this: cvsgrab <file> 147932785Speter 148032785Speter #!/bin/csh -f 148132785Speter set f = $1 148232785Speter if (! -l $f) then 148332785Speter echo "file $f is not a symlink" 148432785Speter exit 1 148532785Speter endif 148632785Speter rm $f 148732785Speter set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'` 148832785Speter cvs update -p -r $rev $f > $f 148932785Speter 149032785Speter You can't do a plain "cvs update" since that would grab newer 149132785Speter revisions from the Repository, not the revision you wanted to start 149232785Speter with. After the file is no longer a symlink, you can work normally. 149332785Speter You'll have to run "update" before "commit" anyway if there are newer 149432785Speter revisions. 149532785Speter 149632785Speter - Presumably there would also be a tool to traverse the link tree and 149732785Speter revert it to links if there are no modified files and/or if all the 149832785Speter real files match the revision of the /master/build tree. 149932785Speter 150032785Speter - To avoid confusing CVS when the /master/build revisions are updated 150132785Speter but your CVS/Entries files is not, CVS would have to change to handle 150232785Speter symlinks. It currently causes problems with this scenario: 150332785Speter 150432785Speter ./<file> is a symlink. 150532785Speter 150632785Speter ./CVS/Entries says you are revision 1.2. 150732785Speter 150832785Speter The corresponding CVS/Entries file in /master/build says the latest 150932785Speter revision is 1.3. 151032785Speter 151132785Speter cvs update <file> shows a 'C' conflict flag. 151232785Speter 151332785Speter Last modified: _6/13/1997_ 151432785Speter 151532785Speter Category: /Advanced_Topics_/Installing_CVS/ 151632785Speter 151732785Speter " + Installing CVS" 151832785Speter 151932785Speter 1. What do I have to do before I install CVS? 152032785Speter 152132785Speter You must decide where to set up a Repository. 152232785Speter 152332785Speter Though you can construct a Repository tree structure using links and 152432785Speter mount points, there must be a single copy of each real file across 152532785Speter your entire organization. You may not "rdist" files and expect to edit 152632785Speter both copies. 152732785Speter 152832785Speter CVS does not support a truly distributed Repository. You can have 152932785Speter multiple Repositories, but each one must be mounted (not copied or 153032785Speter "rdist"ed) from a single place onto all machines where it will be 153132785Speter used. 153232785Speter 153332785Speter Initially, a Repository takes about same amount of disk space as the 153432785Speter sources you want to put into it, plus a bit of overhead for the RCS 153532785Speter files. 153632785Speter 153732785Speter See Section 4B. For multiple Repositories, see 4G.3 153832785Speter 153932785Speter You need a directory in everyone's $PATH variable where you can 154032785Speter install all the executables. /usr/local/bin is a common place. 154132785Speter 154232785Speter You need some helper tools besides CVS such as "RCS" and a good set 154332785Speter of "diff" and "diff3" programs. See 1B.4 for suggestions. 154432785Speter 154532785Speter Read the README, INSTALL and ChangeLog files to see what you are 154632785Speter getting into. 154732785Speter 154832785Speter Though you can probably muddle along without it, you should appoint 154932785Speter one or more "Repository Administrators" who will be responsible for 155032785Speter maintaining the Repository structure, administrative files and the 155132785Speter "modules" interface. 155232785Speter 155332785Speter Someone at your site should probably be on the info-cvs mailing list. 155432785Speter See 1B.5. 155532785Speter 155632785Speter Last modified: _6/13/1997_ 155732785Speter 155832785Speter 2. How do I configure the CVS programs? 155932785Speter 156032785Speter You should certainly start by reading the README file, the INSTALL 156132785Speter files and possibly the ChangeLogs in each directory, the Makefile.in 156232785Speter files and the "cvsinit.sh" program. 156332785Speter 156432785Speter Execute the ./configure command. 156532785Speter 156632785Speter Type "make". 156732785Speter 156832785Speter After running "make" you might try running the "sanity.sh" script: 156932785Speter ./src/sanity.sh `pwd`/src/cvs 157032785Speter 157132785Speter It writes into /tmp/cvs-sanity by default. 157232785Speter 157332785Speter Finish reading the INSTALL file and test out the system. 157432785Speter 157532785Speter Last modified: _6/13/1997_ 157632785Speter 157732785Speter 3. What do I have to install? 157832785Speter 157932785Speter Install the "cvs" executable and "mkmodules" from the CVS sources. 158032785Speter The man page is useful too. If you plan to report bugs, you should 158132785Speter also install "cvsbug". 158232785Speter 158332785Speter Set your $CVSROOT environment variable and create the Repository 158432785Speter (which you planned out in 4A.1) with the "cvsinit" command at the top 158532785Speter of the CVS sources. 158632785Speter 158732785Speter You'll need to edit the Repository control files created by 158832785Speter "cvsinit". 158932785Speter 159032785Speter Install any helper programs mentioned in the modules file. 159132785Speter 159232785Speter Last modified: _6/13/1997_ 159332785Speter 159432785Speter 4. How do I work around the merge problems in GNU diff version 2.1 or 159532785Speter later? 159632785Speter 159732785Speter See 1B.4 If you use recent versions of RCS and "diff", you won't run 159832785Speter into the above. If you do, see 5B.8 159932785Speter 160032785Speter Last modified: _6/13/1997_ 160132785Speter 160232785Speter Category: /Advanced_Topics_/Internal_errors/ 160332785Speter 160432785Speter " + Internal errors" 160532785Speter 160632785Speter 1. Explain: "ci error: unexpected EOF in diff output" 160732785Speter 160832785Speter RCS versions earlier than 5.5 print the above error when a file does 160932785Speter not end in a newline character. It can be caused by: 161032785Speter 161132785Speter - Editing with Emacs and not using "require-final-newline". 161232785Speter - Committing a binary file. 161332785Speter - Filesystem failures (NFS!) that put nulls in your file. 161432785Speter 161532785Speter The solution is to upgrade to RCS 5.5 or later. (Of course, this won't 161632785Speter fix filesystem failures. It will merely allow RCS (and therefore CVS) 161732785Speter to handle the file without error.) 161832785Speter 161932785Speter Last modified: _6/13/1997_ 162032785Speter 162132785Speter 2. Explain: "RCS file /Repository/module/file.c,v is in use" 162232785Speter 162332785Speter This is an RCS error that occurs when its internal lock file has been 162432785Speter left around by an RCS command interrupted by some sort of system 162532785Speter crash, disk failure or SIGKILL signal. 162632785Speter 162732785Speter Go into the Repository and look for files with names similar to 162832785Speter "file.c,v", usually starting with ',', '_' or '#'. Make sure they are 162932785Speter really crash remnants and do not belong to transactions in progress -- 163032785Speter a recent last-modified timestamp is a good indicator of a live 163132785Speter transaction. Delete them if they are old. 163232785Speter 163332785Speter Last modified: _6/13/1997_ 163432785Speter 163532785Speter 3. Explain: "co error, line 2: Missing access list" 163632785Speter 163732785Speter This is an error message from RCS Version 3 when it tries to read a 163832785Speter file created by a later version of RCS. 163932785Speter 164032785Speter HP decided to "standardize" on an ancient version of RCS some time 164132785Speter ago. You can't use it for CVS. See 4H.6. 164232785Speter 164332785Speter Since the error comes from having a later version of RCS than HP 164432785Speter supports, you probably did install the later version but must have 164532785Speter recently changed your $PATH or installed the HP package that has RCS 164632785Speter in it. 164732785Speter 164832785Speter You should either reconfigure CVS to use absolute pathnames to the 164932785Speter proper versions of the RCS programs that CVS uses, or change your PATH 165032785Speter to look there first. If you haven't installed the latest version of 165132785Speter RCS, you should upgrade. See 1B.4 165232785Speter 165332785Speter Last modified: _6/13/1997_ 165432785Speter 165532785Speter 4. Explain: "error: RCS file name `xyz .c' contains white space" 165632785Speter 165732785Speter RCS 5.6 doesn't allow white space in filenames. Apparently this 165832785Speter restriction will be removed in RCS 5.7, but CVS may still require that 165932785Speter filenames have no white space in them. 166032785Speter 166132785Speter Last modified: _6/13/1997_ 166232785Speter 166332785Speter 5. Explain: cvs checkout: warning: <X> is not (any longer) pertinent 166432785Speter 166532785Speter This message occurs in three instances: 166632785Speter 166732785Speter When there is an entry in the ./CVS/Entries for file <X> and there 166832785Speter is no RCS file in the Repository to back it up. 166932785Speter 167032785Speter If the working file exists, and hasn't changed (determined from the 167132785Speter timestamp) it is removed. 167232785Speter 167332785Speter When you try to check out a piece of the Repository with: 167432785Speter 167532785Speter cvs checkout some/place/in/repository/tree 167632785Speter 167732785Speter and at least the first element of the path (i.e. "some" in the above) 167832785Speter exists, but some part of the rest of it does not. 167932785Speter 168032785Speter The checkout command checks the modules file first for the whole path, 168132785Speter then for a prefix of the path as a module name. If it doesn't find 168232785Speter *any* portion of your path in the modules file, it says: 168332785Speter 168432785Speter cvs checkout: cannot find module `<module/path>' - ignored 168532785Speter 168632785Speter If it finds some set of prefix directories, it prints the message you 168732785Speter see. 168832785Speter 168932785Speter In practice this is usually a spelling error. 169032785Speter 169132785Speter If the Repository files you are trying to check out or update are 169232785Speter not readable by you, the same problems can occur. Check the 169332785Speter permissions on the files involved. 169432785Speter 169532785Speter Last modified: _6/13/1997_ 169632785Speter 169732785Speter 6. Why did a Repository file change from <file>,v to ,<file>,? 169832785Speter 169932785Speter This is an RCS problem, since the ,<file>, syntax for file names is 170032785Speter used by RCS and not CVS. 170132785Speter 170232785Speter RCS constructs a new <file>,v in a temporary file named ,<file>, 170332785Speter (which doubles as a lock file) then renames it to <file>,v when it is 170432785Speter done. The only way this is reliable is if your system's version of 170532785Speter rename(2) is an atomic, as required by POSIX. 170632785Speter 170732785Speter If your system has a non-atomic (and therefore non-POSIX) rename(2) 170832785Speter system call, RCS runs uses an internal version of this algorithm to 170932785Speter approximate the atomic rename: 171032785Speter 171132785Speter rm <file>,v; ln ,<file>, <file>,v; rm ,<file>, 171232785Speter 171332785Speter If the system crashes, or you lose your NFS connection between the 171432785Speter first "rm", but before the "ln", you can be left only with the 171532785Speter ,<file>, file. If the crash or network failure occurs between the "ln" 171632785Speter and the final "rm", you could be left with a pair of linked names. 171732785Speter 171832785Speter Recovery: 171932785Speter - If only the ,<file>, exists, rename it to <file>,v. 172032785Speter 172132785Speter - If both ,<file>, and <file>,v exist and are linked, remove the 172232785Speter ,<file>, file. 172332785Speter 172432785Speter - If both ,<file>, and <file>,v exist and are separate files, look at 172532785Speter the dates, "diff" them and make your best guess. This sounds like the 172632785Speter remnants of two separate events. 172732785Speter 172832785Speter Last modified: _6/13/1997_ 172932785Speter 173032785Speter Category: /Advanced_Topics_/Other_Systems/ 173132785Speter 173232785Speter " + Other Systems" 173332785Speter 173432785Speter 1. I use a NeXT. Is there anything I need to know? 173532785Speter 173632785Speter NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather than 173732785Speter the files used in previous revisions. It removes files it doesn't 173832785Speter recognize, making it impossible to place such a directory under CVS -- 173932785Speter the CVS admin directory will be removed. 174032785Speter 174132785Speter Some time ago, <Bob_Vadnais@pdh.com> posted a palette named CVSPalette 174232785Speter that claimed to resolve this problem. It was intended to preserve the 174332785Speter CVS administrative directories within nib documents (directories) that 174432785Speter Interface Builder usually removes. 174532785Speter 174632785Speter CVSPalette is no longer in its announced place: 174732785Speter 174832785Speter ftp.cs.orst.edu:/pub/next/submissions 174932785Speter 175032785Speter though I did find two other interesting files on ftp.cs.orst.edu: 175132785Speter 175232785Speter /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z 175332785Speter 175432785Speter which is a port of CVS 1.3 (along with RCS and diff) and: 175532785Speter 175632785Speter /software/NeXT/sources/programming/cvs.postamble-2.4.gz 175732785Speter 175832785Speter which appears to be a set of wrappers for CVS commands that claim to 175932785Speter allow you to use CVS effectively (and without need for the "command 176032785Speter line") on a NeXT machine. 176132785Speter 176232785Speter [[Anyone know the truth about CVS and NeXT?]] 176332785Speter 176432785Speter Last modified: _6/13/1997_ 176532785Speter 176632785Speter 2. I use OS/2 and/or DOS and/or Windows. Is there anything I need to know? 176732785Speter 176832785Speter When using a local repository, be sure to specify the local access 176932785Speter method or CVS will interpret the drive letter as a remote host name 177032785Speter due to the : following it: 177132785Speter 177232785Speter WRONG: CVSROOT=C:\SRC\CVSROOT 177332785Speter 177432785Speter RIGHT: CVSROOT=:local:C:\SRC\CVSROOT 177532785Speter 177632785Speter (larry.jones@sdrc.com) 177732785Speter 177832785Speter You can share RCS files between Unix and DOS while avoiding the MS-DOS 177932785Speter file name limits by setting your RCSINIT environment variable to 178032785Speter '-x/,v'. New RCS files will be created without the standard ",v" 178132785Speter suffix, though files ending in ",v" will still be found if there is no 178232785Speter matching file in the same directory without the ",v". 178332785Speter 178432785Speter Erik van Linstee offers an OS/2 and a DOS port of CVS 1.3 in: 178532785Speter 178632785Speter ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools or 178732785Speter ftp.rrzn.uni-hannover.de:/pub/os2-local 178832785Speter 178932785Speter The files are named: 179032785Speter 179132785Speter cvs13p?[bs].zip 179232785Speter 179332785Speter Where the ? stands for the patch level (currently 8) and the b is for 179432785Speter the binaries, the s for the sources. 179532785Speter 179632785Speter There are three binaries. An OS/2 only one (32-bit), a DOS only one 179732785Speter (16-bit) and an EMX one that runs on both (32-bit). 179832785Speter 179932785Speter There are many differences between the Unix and the DOS versions of 180032785Speter CVS. Read the material that comes with the DOS version before using 180132785Speter it. 180232785Speter 180332785Speter [[Updates?]]. 180432785Speter 180532785Speter Last modified: _9/22/1997_ 180632785Speter 180732785Speter 3. I use SCO Unix. Is there anything I need to know? 180832785Speter 180932785Speter On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the 181032785Speter configure program detects POSIXness and configures in the use of POSIX 181132785Speter signals. Workaround : Edit out the check for POSIXness in the 181232785Speter configure script. [[You could also remove all occurrences of 181332785Speter "-DPOSIX=1" from the Makefiles after configure is run. -dgg-]] 181432785Speter 181532785Speter SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks the 181632785Speter use of log.pl as it gets invoked by /bin/sh instead of 181732785Speter !#/usr/local/bin/perl. WorkAround : edit log.pl and change it into a 181832785Speter shell script which invokes perl with log.perl (renamed from log.pl) as 181932785Speter input. 182032785Speter Contributed by Joe Drumgoole 182132785Speter 182232785Speter Last modified: _6/13/1997_ 182332785Speter 182432785Speter 4. I use AIX. Is there anything I need to know? 182532785Speter 182632785Speter The only report on AIX claims to have no trouble using it in concert 182732785Speter with SunOS and IRIX platforms. 182832785Speter 182932785Speter Last modified: _6/13/1997_ 183032785Speter 183132785Speter 5. I use IRIX. Is there anything I need to know? 183232785Speter 183332785Speter If you see "uid" numbers where you would expect user names, try adding 183432785Speter -lsun to the link line. Without it CVS is unable to retrieve "passwd" 183532785Speter data through NIS. 183632785Speter 183732785Speter Last modified: _6/13/1997_ 183832785Speter 183932785Speter 6. I use an HP system. Is there anything I need to know? 184032785Speter 184132785Speter HP distributes RCS version 3 (a circa 1983 release!) with HP-UX. CVS 184232785Speter does not work with RCS version 3; it requires RCS version 4 or later. 184332785Speter Your best bet is to find the latest version of RCS and install it 184432785Speter somewhere. 184532785Speter 184632785Speter HP-UX 8.07 has a serious bug with the mmap system call and NFS files; 184732785Speter the bug can crash the operating system. Make sure that you configure 184832785Speter RCS to avoid mmap by setting has_mmap to 0 in RCS's conf.h. This bug 184932785Speter is fixed in HP-UX 9. 185032785Speter 185132785Speter Contributed by Paul Eggert 185232785Speter 185332785Speter If using the setgid() trick described in 4D.13, you will have to 185432785Speter create an entry in the /etc/privgroup file to give the group assigned 185532785Speter to the cvs executable setgid permission (see setprivgrp(1m)). 185632785Speter Additionally, if you are restricting "read" access to the Repository 185732785Speter by limiting access to the executable (this requires yet another 185832785Speter group), then you will require that /etc/logingroup exists and is 185932785Speter configured correctly (usually it's just alink to /etc/group). 186032785Speter 186132785Speter Contributed by Dale Woolridge 186232785Speter 186332785Speter Last modified: _6/13/1997_ 186432785Speter 186532785Speter 7. I use AFS. Is there anything I need to know? 186632785Speter 186732785Speter There is a problem with the way CVS performs its locking when the 186832785Speter files are within AFS. When your current PTS id != your uid, the locks 186932785Speter are not deleted. The stat() system call returns the PTS id of the 187032785Speter owner. If that id != your uid, CVS assumes you did not lock it, and 187132785Speter leaves the lock files alone. The next time you try to use it, it 187232785Speter complains that someone has the repository locked. 187332785Speter 187432785Speter Contributed by Michael Ganzberger 187532785Speter 187632785Speter [[This was against CVS 1.3. Is it still in CVS 1.4?]] 187732785Speter 187832785Speter Last modified: _6/13/1997_ 187932785Speter 188032785Speter 8. I use A/UX. Is there anything I need to know? 188132785Speter 188232785Speter [[??]] 188332785Speter 188432785Speter Last modified: _6/13/1997_ 188532785Speter 188632785Speter Category: /Advanced_Topics_/Related_Software/ 188732785Speter 188832785Speter " + Related Software" 188932785Speter 189032785Speter 1. How do I use CVS under Emacs? Is there an Emacs cvs-mode? 189132785Speter 189232785Speter The pcl-cvs package distributed with CVS is an emacs package that 189332785Speter helps with the update/commit process. When you are ready to update, 189432785Speter you use the 'cvs-update' command within emacs. This executes "update" 189532785Speter and fills a cvs-mode buffer with a line for each file that changed. 189632785Speter The most helpful features are: descriptive words for what happened 189732785Speter (i.e. Merged or Conflict rather than 'U' or 'C'), single keys bound to 189832785Speter diffs and commits, and the ability to mark arbitrary groups of files, 189932785Speter possibly from different directories, for commit as a whole. 190032785Speter 190132785Speter All the developers in my group that use emacs find pcl-cvs a much 190232785Speter friendlier and more helpful way to update/commit than raw cvs. One vi 190332785Speter user even converted to emacs just to use pcl-cvs. 190432785Speter 190532785Speter Contributed by Jeffrey M Loomis 190632785Speter 190732785Speter Last modified: _6/13/1997_ 190832785Speter 190932785Speter 2. What is GIC (Graphical Interface to CVS)? 191032785Speter 191132785Speter 191232785Speter 191332785Speter 191432785Speter GIC provides a graphical user interface to the Concurrent Version 191532785Speter System (CVS), a powerful revision control system. GIC is 191632785Speter implemented in the Tcl/Tk programming language and is intended to 191732785Speter augment the sometimes cumbersome CVS command line interface. 191832785Speter 191932785Speter Note that according to the official GIC page at 192032785Speter http://www.cpsc.ucalgary.ca/redirect/grouplab/projects/gic/ 192132785Speter GIC is no longer being maintained and tkCVS is recommended 1922128266Speter instead. 192332785Speter 1924175261Sobrien For more on tkCVS, see 1925175261Sobrien <http://ximbiot.com/cvs/cvshome/dev/addontkcvs.html>. 1926128266Speter 192732785Speter kingdon@cyclic.com 192832785Speter 192932785Speter Last modified: _9/6/1997_ 193032785Speter 193132785Speter 3. What is CAVEMAN? 193232785Speter 193332785Speter CAVEMAN is a front end to CVS written in PERL providing a collection 193432785Speter of features desired by the site where it was developed. 193532785Speter 193632785Speter - The ability to spread a "project" over multiple Repositories. 193732785Speter - Optional automatic tagging after each commit. 193832785Speter - Additional locking of files. 193932785Speter - Extra before and after program hooks. 194032785Speter - A layer of event logging. 194132785Speter - All sorts of error messages. 194232785Speter - Many changes to the semantics of commands. 194332785Speter 194432785Speter It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18] in 194532785Speter gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.) 194632785Speter 194732785Speter contact Kathleen Dyer kdyer@llnl.gov 194832785Speter (510)423-6803 194932785Speter (510)423-5112 FAX 195032785Speter 195132785Speter [[Does someone want to elaborate?]] 195232785Speter 195332785Speter Last modified: _6/13/1997_ 195432785Speter 195532785Speter Category: /Advanced_Topics_/Setting_up_and_Manag/ 195632785Speter 195732785Speter " + Setting up and Managing the Repository" 195832785Speter 195932785Speter 1. What do I do first? How do I create a Repository? 196032785Speter 196132785Speter First, install all the programs. (See Section 4A.) 196232785Speter 196354427Speter Then create a Repository by executing "cvs -d init". (This works with 196454427Speter CVS 1.9.) 196532785Speter 196654427Speter Now you can configure your repository by checking out CVSROOT: "cvs -d 196754427Speter checkout CVSROOT". Change into the created directory CVSROOT. Edit the 196854427Speter files you want to edit, and afterwards, commit the changes by typing 196954427Speter "cvs commit". 197032785Speter 197132785Speter You will certainly want to add modules of your own. Edit the "modules" 197232785Speter file and add lines to describe the items you want to "checkout" by 197332785Speter module name. Here's a short list that could be used for storing a 197432785Speter small number of GNU and PD sources: 197532785Speter 197632785Speter local local 197732785Speter 197832785Speter gnu local/gnu 197932785Speter emacs local/gnu/emacs 198032785Speter cvs local/gnu/cvs 198132785Speter 198232785Speter public local/public 198332785Speter pdprog1 local/public/pdprog1 198432785Speter pdprog2 local/public/pdprog2 198532785Speter 198632785Speter test test 198732785Speter junk test/junk 198832785Speter 198954427Speter Andreas Kostyrka 199032785Speter 199154427Speter Last modified: _4/21/1998_ 199232785Speter 199332785Speter 2. What are those files in $CVSROOT/CVSROOT? 199432785Speter 199532785Speter There are eight Repository control (or "database") files of interest 199632785Speter in the CVSROOT directory: 199732785Speter 199832785Speter modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and 199932785Speter 4B.7 for more details. 200032785Speter 200132785Speter commitinfo contains two columns: 1. a regular expression to match 200232785Speter against pathnames within the Repository and 200332785Speter 200432785Speter a <command> to execute for matching pathnames. 200532785Speter 200632785Speter When you execute "commit", CVS passes the Repository pathname for each 200732785Speter directory (and the files to commit within that directory) to 200832785Speter <command>. If <command> exits with a non-zero status, the commit is 200932785Speter blocked. 201032785Speter 201132785Speter A <command> associated with a pathname of "DEFAULT" is executed if 201232785Speter nothing else matches. Every <command> associated with a pathname of 201332785Speter "ALL" is executed separately. 201432785Speter 201532785Speter rcsinfo contains the same first column as commitinfo, but the second 201632785Speter column is a template file for specifying the log entry you are 201732785Speter required to enter for each commit. 201832785Speter 201932785Speter "DEFAULT" and "ALL" work the same as in the commitinfo file. 202032785Speter 202132785Speter editinfo contains the same two columns as commitinfo, but the 202232785Speter <command> in the second column is intended to do some consistency 202332785Speter checking on the commit log. 202432785Speter 202532785Speter "DEFAULT" works as in commitinfo. 202632785Speter 202732785Speter loginfo contains the same two columns as commitinfo, but the 202832785Speter <command> is expected to read a log message from its standard input. 202932785Speter The <command> can do anything it wants with the log information, but 203032785Speter normally it is appended to a log file or sent to mailing lists. 203132785Speter 203232785Speter "DEFAULT" & "ALL" work the same as in commitinfo. 203332785Speter 203432785Speter cvsignore contains "ignore" patterns that are added to the built-in 203532785Speter ignore list. See 2D.10. 203632785Speter 203732785Speter checkoutlist contains a list of other files kept under RCS in 203832785Speter $CVSROOT/CVSROOT that should be checked out by mkmodules to provide a 203932785Speter readable copy. 204032785Speter 204132785Speter history contains a stream of text records, one for each event that 204232785Speter the "history" command is interested in. Though the contents of the 204332785Speter history file can be read, it is intended to be read and displayed by 204432785Speter the "history" command. This file is the only one in the above list 204532785Speter that is not under RCS. 204632785Speter 204732785Speter Last modified: _6/13/1997_ 204832785Speter 204932785Speter 3. Is there any other state stored in the Repository besides in the 205032785Speter $CVSROOT/CVSROOT directory? 205132785Speter 205232785Speter Only in the RCS files. The Repository holds exactly two things: the 205332785Speter tree of RCS files (each usually ending in ",v") and the CVSROOT 205432785Speter directory described above. 205532785Speter 205632785Speter Last modified: _6/13/1997_ 205732785Speter 205832785Speter 4. How do I put sources into the Repository? 205932785Speter 206032785Speter There are three main ways to put files in the Repository: 206132785Speter 206232785Speter Use the "import" command described in Section 3H. 206332785Speter 206432785Speter This method is the fastest way to put trees of new code into the 206532785Speter Repository and the *only* way to handle source releases from a 3rd 206632785Speter party software vendor. 206732785Speter 206832785Speter Use "add" followed by "commit". 206932785Speter 207032785Speter This is how to add new files and directories to the Repository, a few 207132785Speter at a time. Directories don't need to be committed. 207232785Speter 207332785Speter You can move RCS files directly into the Repository. 207432785Speter 207532785Speter You should create a directory hierarchy to hold them, but you can just 207632785Speter move arbitrary ",v" files into the Repository. The only "state" in the 207732785Speter Repository other than within ",v" files is in the required CVSROOT 207832785Speter directory at the top of the Repository. 207932785Speter 208032785Speter Last modified: _6/13/1997_ 208132785Speter 208232785Speter 5. What file permissions should I use on (and in) the Repository? 208332785Speter 208454427Speter If you are using pserver (password-authenticated access), see below. 208554427Speter 208632785Speter If you run a completely open environment (which usually means that you 208732785Speter don't have, or don't want to waste, the time to deal with it): 208832785Speter 208932785Speter - Set all directory permissions to 777. 209032785Speter 209132785Speter - Have everyone set their umasks to 0. 209232785Speter 209332785Speter (BTW, I don't suggest this. I am merely reporting it.) 209432785Speter 209532785Speter If you are a normal Unix shop and want to use groups effectively: 209632785Speter 209732785Speter - Set all the directory permissions in the Repository to 775. 209832785Speter 209932785Speter If you are using a system that handles both System V and BSD 210032785Speter filesystems, you might have to set the permissions to 2775.) 210132785Speter 210232785Speter If you are using one of the many recent versions of Unix that don't 210332785Speter allow you to use the full octal mode, then you'll have to type: chmod 210454427Speter u=rwx,g=rwx,o=rx,g+s dir> 210532785Speter 210632785Speter - Change all the groups on the directories to match the groups you 210732785Speter want to write to various directories. 210832785Speter 210932785Speter - Make sure every user is in the appropriate groups. 211032785Speter 211132785Speter - Have everyone set their umask to 002, including root. 211232785Speter 211332785Speter If you don't want non-group members to even read the files, do the 211432785Speter above, but change: 211532785Speter 211632785Speter - Repository directory permissions to 770. (or 2770) 211732785Speter 211832785Speter - umasks to 007. 211932785Speter 212032785Speter If you work in an environment where people can't be trusted to set 212132785Speter their "umask" to something reasonable, you might want to set the umask 212232785Speter for them: 212332785Speter 212432785Speter mv /usr/local/bin/cvs /usr/local/bin/cvs.real 212532785Speter cat > /usr/local/bin/cvs 212632785Speter #!/bin/sh 212732785Speter umask 2 # Or whatever your site standard is. 212832785Speter exec /usr/local/bin/cvs.real ${1+"$@"} 212932785Speter ^D 213032785Speter 213154427Speter Pserver (Password-Authenticated Access) <blome@de.ibm.com> 213232785Speter 213354427Speter The above suggestions are not valid when you use the pserver facility. 213454427Speter Be sure to read and understand the manual section about this (should 213554427Speter be 4.6.something). Above all: do /not/ make the repository and CVSROOT 213654427Speter group writeable. In CVSROOT, make `history� group or world writeable 213754427Speter instead. 213854427Speter 213954427Speter I suggest creating one unix group per project group. In the 214054427Speter repository, you would then create one directory for each group, group 214154427Speter writeable. New projects must then be created in these group 214254427Speter directories. If you don't want to say <group>/<project> on 214354427Speter checkout, create a <project> module and point it there. 214454427Speter 214554427Speter Last modified: _9/24/1998_ 214654427Speter 214732785Speter 6. How do I structure my Repository? 214832785Speter 214932785Speter The Repository holds your software. It can be all interrelated or it 215032785Speter can be a bunch of separately managed directories. 215132785Speter 215232785Speter How you break a whole system down into its component parts, while 215332785Speter defining interfaces between them, is one aspect of "Software 215432785Speter Engineering", a discipline that requires the study of dozens of 215532785Speter strange and wonderful areas of the computer and management worlds. 215632785Speter 215732785Speter CVS provides a way to keep track of changes to individual files, a way 215832785Speter to "tag" collections of files, and a way to "name" collections of 215932785Speter files and directories. That's all. Everything else is in the way you 216032785Speter apply it. 216132785Speter 216232785Speter In other words, you should structure your Repository to match your 216332785Speter needs, usually tied in with the other tools you use to build, install 216432785Speter and distribute your work. Common needs include the ability to: 216532785Speter 216632785Speter - mount (or automount) directories from many places in your 216732785Speter organization. 216832785Speter - check out just what you need and no more. 216932785Speter - check out multiple sections in a fixed relation to each other. 217032785Speter - check out large sections to match the assumptions built into your 217132785Speter build system. (Makefiles?) 217232785Speter 217332785Speter In my opinion, you should start small and keep everything in one tree, 217432785Speter placing each major sub-system into a separate directory. Later, when 217532785Speter you know what you are doing, you can make it more sophisticated. 217632785Speter 217732785Speter Last modified: _6/13/1997_ 217832785Speter 217932785Speter 7. Why would anyone use "modules"? They are too restrictive. I want to be 218032785Speter able to select just the files I want to edit. 218132785Speter 218232785Speter Any form of structure is restrictive. If you believe that total chaos 218332785Speter is a viable working paradigm, or if you believe you can keep track of 218432785Speter the interrelations between all portions of your Repository in your 218532785Speter head, then you can do what you please. 218632785Speter 218732785Speter If you believe that systems of files require management and structure, 218832785Speter then the "modules" idea is very useful. It is a way to impose a naming 218932785Speter scheme on a tree of files, a naming scheme that can be simpler than a 219032785Speter large list of relative pathnames. 219132785Speter 219232785Speter The "modules" file represents a published interface to the Repository 219332785Speter set up by your Repository Administrator. If s/he did a creditable job, 219432785Speter the modules offered will be internally consistent and will smoothly 219532785Speter interact with the rest of your environment. 219632785Speter 219732785Speter Last modified: _6/13/1997_ 219832785Speter 219932785Speter 8. How do I rename a file or directory? What are the consequences? 220032785Speter 220132785Speter In CVS there is no single "rename" command. 220232785Speter 220332785Speter See 2C.4 for the suggested way to rename a file or directory. 220432785Speter 220532785Speter The rest of this section covers some of the consequences of renaming. 220632785Speter 220732785Speter A "renaming database" has been proposed that would keep track of name 220832785Speter changes so that "update -r <tag>" would continue to work across the 220932785Speter renaming. But as it stands, you have to pick one of the following 221032785Speter options: 221132785Speter 221232785Speter Use the technique described in 2C.4. (For each file, duplicate the 221332785Speter file in the Repository, "remove" the old version so it winds up in the 221432785Speter Attic and strip all Tags off the new version.) 221532785Speter 221632785Speter - "update -r <tag>" produces the correct files. 221732785Speter 221832785Speter - The duplicated revision history can be slightly misleading. 221932785Speter 222032785Speter - A plain (i.e. without the "-r <tag>") "checkout" or "update -d" will 222132785Speter create directories "renamed" this way, but you can delete it and a 222232785Speter plain "update" won't bring it back. 222332785Speter 222432785Speter Move the files and directories in the Repository to the new names. 222532785Speter 222632785Speter - You save the revision history under a different file name. 222732785Speter 222832785Speter - You save a little space. 222932785Speter 223032785Speter - "update -r <tag>" produces the wrong files or directories. 223132785Speter 223232785Speter This is not a good general solution, but if you plan never to look 223332785Speter back (someone may be gaining on you!), it is sometimes a useful 223432785Speter notion. 223532785Speter 223632785Speter If you are clever with Makefiles, you might be able to rework them to 223732785Speter handle either the new or old names, depending on which ones exist at 223832785Speter the time. Then you can move an old <tag> onto the new, more 223932785Speter sophisticated, revision of the Makefile. (Yes, this changes the 224032785Speter "released" file if <tag> indicates a release. But it is an option.) 224132785Speter 224232785Speter - Important Note: If you rename a directory, you must rename the 224332785Speter corresponding directory in every checked-out working directory. At the 224432785Speter same time, you must edit the pathname stored in the ./CVS/Repository 224532785Speter file within each of the moved directories. 224632785Speter 224732785Speter The easiest way to move a lot of directories around is to tell 224832785Speter everyone to remove their working directories and check them out again 224932785Speter from scratch. 225032785Speter 225132785Speter - The file exists in the working directory and in the ./CVS/Entries 225232785Speter file, but not in the Repository. For the old file, "update" prints: 225332785Speter 225432785Speter cvs update: xyz.c is no longer in the repository 225532785Speter 225632785Speter and deletes the file. If the file was modified, "update" prints: 225732785Speter 225832785Speter cvs update: conflict: xyz.c is modified but no longer in the 225932785Speter repository C xyz.c 226032785Speter 226132785Speter and leaves the file alone. In the new directory, you see: 226232785Speter 226332785Speter U xyz.c 226432785Speter 226532785Speter as you would if someone else executed "add" and "commit". 226632785Speter 226732785Speter For each file, copy the working file to a new name in the working 226832785Speter directory and use the "cvs remove" to get rid of the old old file and 226932785Speter "cvs add" to add the new one. Since there is no way for CVS to remove 227032785Speter a directory, this only works for files. 227132785Speter 227232785Speter - This is what most people think of first. Without a "rename" command, 227332785Speter the remove/add technique seems obvious. 227432785Speter 227532785Speter - You lose the connection of your new working file to its past 227632785Speter revision history. 227732785Speter 227832785Speter Last modified: _6/13/1997_ 227932785Speter 228032785Speter 9. What are "Attic" directories? 228132785Speter 228232785Speter When you use the "remove" command on a file, CVS doesn't delete the 228332785Speter file, it only registers your desire to delete it. 228432785Speter 228532785Speter When you "commit" a removed file, CVS moves the Repository's matching 228632785Speter RCS file into a sub-directory named "Attic" within the Repository. 228732785Speter 228832785Speter Attic files are examined when the '-r' or '-D' option is used on 228932785Speter "checkout" or "update". If the specified revision, tag or date matches 229032785Speter one on a file in the Attic, that file is checked out with the others. 229132785Speter 229232785Speter You can think of the Attic as a sort of dead branch, which is only 229332785Speter looked at when you refer to a <tag> or <date>. 229432785Speter 229532785Speter Last modified: _6/13/1997_ 229632785Speter 229732785Speter 10. Is it OK to remove anything from the Repository? 229832785Speter 229932785Speter In general, removing anything from the Repository is a bad idea. The 230032785Speter information in a deleted object is lost forever. There are many ways 230132785Speter to skip over files, directories and revisions without deleting them. 230232785Speter 230332785Speter Here are some of the consequences of removing the following things 230432785Speter stored in the Repository: 230532785Speter 230632785Speter CVSROOT files (Repository control files) 230732785Speter 230832785Speter The Repository will work without any of them, but you should 230932785Speter understand what you are losing by deleting them. See 4B.2. 231032785Speter 231132785Speter Revisions 231232785Speter 231332785Speter The only way to remove revisions is to use the "admin -o" command (or 231432785Speter the equivalent RCS command "rcs -o"). 231532785Speter 231632785Speter They are lost forever. Any tags formerly attached to deleted revisions 231732785Speter are now pointing into the Phantom Zone. You'll need to contact Jor-el 231832785Speter to get them back. 231932785Speter 232032785Speter Files 232132785Speter 232232785Speter You should not remove a file unless you truly never want to see it 232332785Speter again. If you want to be able to check out an old revision of this 232432785Speter file, use "cvs remove" instead. 232532785Speter 232632785Speter Tags 232732785Speter 232832785Speter Tags take up little space and you can't recover from deleting them. If 232932785Speter you depend on tags for releases you will lose vital information. 233032785Speter 233132785Speter Directories 233232785Speter 233332785Speter There is no Attic for directories, so the only way to remove them is 233432785Speter to use "rm -r". They are gone forever. 233532785Speter 233632785Speter If you delete (or move) a directory, all checked-out versions of that 233732785Speter directory will cause CVS to halt. You'll have to visit each 233832785Speter checked-out directory and remove the matching working directory by 233932785Speter hand. 234032785Speter 234132785Speter Attic files 234232785Speter 234332785Speter The "remove" command sends files to the Attic. To really delete them, 234432785Speter you have to go into the Attic and use "rm". 234532785Speter 234632785Speter If a file in the Attic has a Tag on it that you might ever want to 234732785Speter check out again, you probably don't want to delete it. 234832785Speter 234932785Speter Lock files (named: "#cvs.[wr]fl.<pid>") 235032785Speter 235132785Speter These are lock files. If you are getting "lock" errors and the dates 235232785Speter on the lock files indicate that they are old, you can delete them. 235332785Speter 235432785Speter Deleting lock files still in use by a CVS process might produce 235532785Speter unusual errors. 235632785Speter 235732785Speter Last modified: _6/13/1997_ 235832785Speter 235932785Speter 11. Can I convert to CVS from RCS without losing my revision history? 236032785Speter 236132785Speter Yes, you can simply move (or copy) your RCS files into a directory 236232785Speter within the Repository, check out that directory and start working. 236332785Speter 236432785Speter Last modified: _6/13/1997_ 236532785Speter 236632785Speter 12. Can I move RCS files with branches in them into the Repository? 236732785Speter 236832785Speter Yes, but they may not work if you created branches in a way that 236932785Speter conflicts with CVS's assumptions: 237032785Speter 237132785Speter You can't use .0. branches. (They are reserved for "Magic" branch 237232785Speter tags.) 237332785Speter 237432785Speter If you use branch 1.1.1, you can't use the Vendor branch. 237532785Speter 237632785Speter You can use other RCS branches under CVS. There is no need to create 237732785Speter "magic" branch tags because the physical branch already exists. 237832785Speter 237932785Speter Last modified: _6/13/1997_ 238032785Speter 238132785Speter 13. Can I use raw RCS commands on the Repository? 238232785Speter 238332785Speter You can use raw rcs commands directly on the Repository if you take a 238432785Speter little care. The Repository itself contains no "CVS state" (as opposed 238532785Speter to RCS revision histories) outside the CVSROOT directory. 238632785Speter 238732785Speter But using raw RCS commands to change branches, tags or other things 238832785Speter that CVS depends on may render the files unusable. 238932785Speter 239032785Speter See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the 239132785Speter "admin" command. 239232785Speter 239332785Speter Last modified: _6/13/1997_ 239432785Speter 239532785Speter 14. How do I convert from SCCS to RCS? 239632785Speter 239732785Speter You'll have to execute something like "sccs2rcs" (in the CVS contrib 239832785Speter directory) on every file. Then you can move the resulting RCS files 239932785Speter into the Repository as described above. 240032785Speter 240132785Speter Last modified: _6/13/1997_ 240232785Speter 240332785Speter 15. How do I limit access to the Repository? 240432785Speter 240532785Speter There are all sorts of ways to restrict access to Repository files, 240632785Speter none of which are hooked directly into CVS. 240732785Speter 240832785Speter Techniques for limiting access include: 240932785Speter 241032785Speter Training, management and good backups. 241132785Speter 241232785Speter The best form of Repository control is a combination of: 241332785Speter 241432785Speter - A reliable backup scheme (verify it!) 241532785Speter - Enough training to ensure your developers are competent and 241632785Speter knowledgeable about all areas of your sources. 241732785Speter - Effective management of the boundaries and grey areas. 241832785Speter 241932785Speter In many cases, technical solutions to "security" problems are 242032785Speter inadequate. You should first try to avoid them. 242132785Speter 242232785Speter Personal Opinion: In an environment where "unknowns" are allowed to 242332785Speter touch important sources the "owner" of the CVS Repository must be a 242432785Speter large, loud, vigorous lout with a well-balanced truncheon and the 242532785Speter right to use it. Don't underestimate the effectiveness of letting 242632785Speter everyone know they will be strapped into the stocks on the Town Common 242732785Speter and pelted with vegetables if they break something they don't 242832785Speter understand without first asking the experts. 242932785Speter 243032785Speter Set Unix groups and permissions. See 4B.5. You can set different 243132785Speter owners, groups and permissions for each sub-directory within the 243232785Speter Repository if that helps. 243332785Speter 243432785Speter Catch invocations of "commit" by defining pre-commit programs in the 243532785Speter "commitinfo" file. This is fairly powerful, since it can block commits 243632785Speter based on anything you can program. Take a look at the programs in the 243732785Speter "contrib" directory of the CVS source tree. 243832785Speter 243932785Speter Use multiple Repositories, each with its own protection scheme. If 244032785Speter you use NFS (or AFS) you can even use "export" restrictions to various 244132785Speter groups of machines to keep (for example) the Engineering Repository 244232785Speter off the Customer Service machines. 244332785Speter 244432785Speter Try the "setgid" trick described in 4D.13. 244532785Speter 244632785Speter Try to use the RCS access control lists, though I don't think CVS 244732785Speter will handle them cleanly. 244832785Speter 244932785Speter Edit the source code to CVS to add your own access control. 245032785Speter 245132785Speter Last modified: _6/13/1997_ 245232785Speter 245332785Speter 16. What are the Repository Administrator's responsibilities? 245432785Speter 245532785Speter Generally, the Administrator should set "policy", create the 245632785Speter Repository and monitor its size and control files. 245732785Speter 245832785Speter Some specific responsibilities include: 245932785Speter 246032785Speter Examining the Repository once in a while to clean up: 246132785Speter 246232785Speter Trash files left by misguided developers who mistake the Repository 246332785Speter for a working directory. 246432785Speter 246532785Speter Non-RCS files. Other than the files CVS needs in the 246632785Speter $CVSROOT/CVSROOT directory, every file in the Repository should be an 246732785Speter RCS file. 246832785Speter 246932785Speter Lock files (both CVS '#*' and RCS ',*' files) left around after 247032785Speter crashes. 247132785Speter 247232785Speter Wrong permissions, groups and ownerships. 247332785Speter 247432785Speter Locked files. (RCS locks, that is.) 247532785Speter 247632785Speter Attic files that should never have been under CVS at all. Don't 247732785Speter blindly delete files from Attic directories -- they were mostly put 247832785Speter there (via the "cvs remove") for a reason. Files that should be 247932785Speter deleted are binary files (e.g. '*.o', 'core', executables) that were 248032785Speter mistakenly inserted by "import -I !". 248132785Speter 248232785Speter Maintaining the modules file. 248332785Speter 248432785Speter Storing site-specific ignore patterns in the 248532785Speter $CVSROOT/CVSROOT/cvsignore file. 248632785Speter 248732785Speter Storing the names of non-standard CVSROOT files (See 4B.2) in the 248832785Speter $CVSROOT/CVSROOT/checkoutlist 248932785Speter 249032785Speter Maintaining the other Repository control files: commitinfo, loginfo, 249132785Speter rcsinfo and editinfo. 249232785Speter 249332785Speter Pruning the history file every once in a while. (Try the 249432785Speter "cln_hist.pl" script in the "contrib" directory.) 249532785Speter 249632785Speter Staying aware of developments on the info-cvs mailing list and what 249732785Speter is available in the FTP and WWW archives. 249832785Speter 249932785Speter Running "ps ax" once in a while and kill off any "update" programs 250032785Speter not running as "root". It is too easy to leave the "cvs" off the front 250132785Speter of the "cvs update" command. 250232785Speter 250332785Speter Executing monitor programs to check the internal consistency of the 250432785Speter Repository files. Ideas: 250532785Speter 250632785Speter Files that have a default RCS branch that is not 1.1.1 (From an 250732785Speter abuse of "admin -b".) 250832785Speter 250932785Speter Files that have only Revisions 1.1 and 1.1.1.1, with a default 251032785Speter branch of "MAIN". (From an abuse of "admin -o".) 251132785Speter 251232785Speter Existing branch tags and various branch consistency checks. 251332785Speter 251432785Speter Last modified: _6/13/1997_ 251532785Speter 251632785Speter 17. How do I move the whole Repository? 251732785Speter 251832785Speter Copy or move the tree. (On Unix systems, a set of piped "tar" commands 251932785Speter works great. If the Repository does not contain any symlinks, which it 252032785Speter normally doesn't, you can also use "cp -r".) 252132785Speter 252232785Speter If you can avoid changing $CVSROOT (i.e. the "logical" pathname of the 252332785Speter Repository) by replacing the old location with a symbolic link to the 252432785Speter new location, you don't have to do anything else. 252532785Speter 252632785Speter (You could also mount the new location on top of the old location if 252732785Speter you are using NFS or some other filesystem that allows it.) 252832785Speter 252932785Speter If you must change $CVSROOT, you must also tell everyone to change the 253032785Speter CVSROOT environment variable in all running shells and in any personal 253132785Speter configuration files ('.' files on Unix) where it is set. 253232785Speter 253332785Speter The Repository itself contains no references to its own name, except 253432785Speter possibly in some of the files in the CVSROOT directory. If your 253532785Speter modules (or loginfo, commitinfo, etc.) file mentions helper programs 253632785Speter directly in the Repository, you'll have to change the pathnames to 253732785Speter point to the new Repository location. 253832785Speter 253932785Speter The main changes you'll have to make are to all the CVS administrative 254032785Speter files (./CVS/Repository and ./CVS/Root) in every working directory 254132785Speter ever checked out from the previous location of the Repository you just 254232785Speter moved. 254332785Speter 254432785Speter You have three choices: 254532785Speter 254632785Speter If all ./CVS/Repository files in all working directories contain 254732785Speter relative pathnames, you don't have to do anything else. 254832785Speter 254932785Speter Have everyone "release" or delete their working directories (after 255032785Speter committing, or just saving, their work) and check them all out again 255132785Speter from the new Repository after the move. 255232785Speter 255332785Speter Use "find . ( -name Repository -o -name Root )" and a PERL or shell 255432785Speter script to run through all the ./CVS/Repository and ./CVS/Root files 255532785Speter and edit the values in the files. 255632785Speter 255732785Speter Last modified: _6/13/1997_ 255832785Speter 255932785Speter 18. How do I change permissions on a file in the Repository by using a CVS 256032785Speter command? (i.e. without using "chmod 777 $CVSROOT/dir/file") 256132785Speter 256232785Speter When you first "import" or "add"/"commit" a file, the read and execute 256332785Speter bits on the Repository file are inherited from the original source 256432785Speter file, while the write bits on the Repository file are are turned off. 256532785Speter This is a standard RCS action. 256632785Speter 256732785Speter After that, there is no way to alter the permissions on a file in the 256832785Speter Repository using CVS (or RCS) commands. You have to change the 256932785Speter permissions on both your working file and on the Repository file from 257032785Speter which it was retrieved. 257132785Speter 257232785Speter Whenever you "checkout" the file or retrieve a new revision via 257332785Speter "update" (or after a "commit"), your working file is set to match the 257432785Speter permissions of the Repository file, minus any "umask" bits you have 257532785Speter set. 257632785Speter 257732785Speter Last modified: _6/13/1997_ 257832785Speter 257932785Speter Category: /Advanced_Topics_/Tricks_of_the_Trade/ 258032785Speter 258132785Speter " + Tricks of the Trade" 258232785Speter 258332785Speter 1. How can you even check in binary files, let alone allow CVS to do its 258432785Speter auto-merge trick on them? 258532785Speter 258632785Speter 258732785SpeterFirst of all, if you want to use binary files, you should get RCS 5.7 258832785Speterand CVS 1.9 or later (earlier versions had some support, but there have been 258932785Speterbug fixes). Secondly, follow the instructions for installing RCS very 259032785Spetercarefully (it is easy to get it installed so it works for everything 259132785Speterexcept binary files). 259232785Speter 259332785SpeterThen, specify 'cvs add -kb' instead of just 'cvs add' to add a binary 259432785Speterfile. If you want to set an existing file to binary, run 'cvs admin 259532785Speter-kb' (and then check in a new copy of the file). Note that old 259632785Speterversions of CVS used -ko instead of -kb for binary files, so if you 259732785Spetersee a reference to -ko in the context of binary files, you should 259832785Speterthink -kb instead. 259932785Speter 260032785SpeterOf course when 'cvs update' finds that a merge is needed, it can't 260132785Speterdo this for binary files the same way as for text files. With the 260232785Speterlatest versions (e.g. CVS 1.9.14), it should be able to give you both 260332785Speterversions and let you merge manually. Another approach is to 260432785Speterrun 'cvs admin -l' to lock files, as described in 260532785Speter"How can I lock files while I'm working on them the way RCS does?" 260632785Speterelsewhere in this FAQ. See also 260732785Speter"Is there any way to import binary files?" and 260832785Speter"How do I "add" a binary file?" elsewhere in this FAQ. 260932785Speter 261032785Speterkingdon@cyclic.com 261132785Speter 261232785Speter Last modified: _9/6/1997_ 261332785Speter 261432785Speter 2. Can I edit the RCS (",v") files in the Repository? 261532785Speter 261632785Speter Yes, but be very careful. The RCS files are not free-form files, they 261732785Speter have a structure that is easily broken by hand-editing. The only time 261832785Speter I would suggest doing this is to recover from emergency failures that 261932785Speter are difficult to deal with using CVS commands, including the "admin" 262032785Speter command, which can talk directly to RCS. 262132785Speter 262232785Speter Though no one actively encourages the editing of RCS files, many 262332785Speter people have succumbed to the urge to do so when pressed for time. The 262432785Speter reasons given, usually with evident contrition, include: 262532785Speter 262632785Speter - Editing mistakes in, or adding text to, log entries. (If you have 262732785Speter RCS 5.6 or later, you should use `cvs admin -m'.) 262832785Speter - Renaming or moving symbolic names. (You should `cvs admin -N' 262932785Speter instead.) 263032785Speter - Unlocking a file by changing the "locker" from someone else to 263132785Speter yourself. (It's safer to use `cvs admin -u -l'.) 263232785Speter - Making global changes to past history. Example: Eradicating former 263332785Speter employees names from old documents and Author entries. (And someone 263432785Speter thought the "history" command was evidence of Big Brother! I never 263532785Speter realized how much help a wide-open revision control system could have 263632785Speter provided to The Ministry of Truth.) 263732785Speter 263832785Speter Last modified: _6/13/1997_ 263932785Speter 264032785Speter 3. Can I edit the ./CVS/{Entries,Repository,Tag} files? 264132785Speter 264232785Speter Yes, but with CVS 1.3 and later, there is almost no reason to edit any 264332785Speter of the CVS administrative files. 264432785Speter 264532785Speter If you move pieces of your Repository around it can be faster to edit 264632785Speter all the ./CVS/Repository files rather than checking out a large tree. 264732785Speter But that is nearly the only reason to do so. 264832785Speter 264932785Speter Last modified: _6/13/1997_ 265032785Speter 265132785Speter 4. Someone executed "admin -o" and removed revisions to which tags/symbols 265232785Speter were attached. How do I fix them? 265332785Speter 265432785Speter It depends on what you mean by "fix". I can think of three ways to fix 265532785Speter your predicament: 265632785Speter 265732785Speter Remove the tags. 265832785Speter 265932785Speter Assuming you really wanted to get rid of the revision and its 266032785Speter associated tags, you can remove them with the "admin" command. The 266132785Speter "tag -d" command will only remove tags attached to existing revisions. 266232785Speter You can remove a tag, even if it is attached to a non-existent 266332785Speter revision, by typing: 266432785Speter 266532785Speter cvs admin -N<tag> <file> 266632785Speter 266732785Speter Retrieve the outdated revision. 266832785Speter 266932785Speter You should first look in your backup system for recent versions of the 267032785Speter file. If you can't use them, you can carefully extract each revision 267132785Speter that followed the earliest outdated revision using RCS (or "cvs 267232785Speter admin") commands and reconstruct the file with all the right 267332785Speter revisions, branches and tags. This is a lot of work. 267432785Speter 267532785Speter You *can't* insert a revision into the current RCS file. 267632785Speter 267732785Speter Move the Tags to another revision in each file. 267832785Speter 267932785Speter If you want to move the tags to another valid revision, you have two 268032785Speter choices, both of which require that you find all the revision numbers 268132785Speter of the files you want to "tag" and execute the following command 268232785Speter sequences on each <file>. 268332785Speter 268432785Speter Use "update" to grab the revision you want, then execute a normal 268532785Speter "tag" command to Tag that revision: 268632785Speter 268732785Speter cvs update -r <rev> <file> 268832785Speter cvs tag <tag> <file> 268932785Speter 269032785Speter Use "admin" to set the tag to a specific revision: 269132785Speter 269232785Speter cvs admin -N<tag>:<rev> <file> 269332785Speter 269432785Speter Last modified: _6/13/1997_ 269532785Speter 269632785Speter 5. How do I move or rename a magic branch tag? 269732785Speter 269832785Speter (To rename a non-branch <tag> see 3O.9.) 269932785Speter 270032785Speter Before reading this, read 3M.3 and 3M.4 and understand exactly how tag 270132785Speter and rtag use '-r' and why it won't do the right job here. 270232785Speter 270332785Speter First, I have to explain exactly what a magic branch tag is. 270432785Speter 270532785Speter A magic <branch_tag> is an artificial tag attached to a non-existent 270632785Speter revision on a non-existent branch number zero. It looks like this: 270732785Speter 270832785Speter TAG1:<X>.0.Y 270932785Speter 271032785Speter <X> is the "branch point revision", a normal revision with an 271132785Speter odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc) 271232785Speter 271332785Speter Y is an even number (e.g. 2, 4, 6, etc.) All CVS branches, 271432785Speter other than the Vendor branch, are even numbered. 271532785Speter 271632785Speter TAG1 is considered by CVS to be attached to revision <X>. The first 271732785Speter "update -r TAG1 <file>" after applying TAG1 will produce a copy of 271832785Speter revision <X> with a sticky tag of TAG1. The first "commit" to that 271932785Speter file will cause CVS to construct an RCS branch named <X>.Y and check 272032785Speter in revision <X>.Y.1 on the new branch. 272132785Speter 272232785Speter Note: TAG1 is *not* considered to be attached to <X> by RCS, which 272332785Speter explains why you can't refer directly to the branch point revision for 272432785Speter some CVS commands. 272532785Speter 272632785Speter Moving a magic <branch_tag> is the act of reapplying the same tag to 272732785Speter different revisions in the file: 272832785Speter 272932785Speter TAG1:<X>.0.Y 273032785Speter to 273132785Speter TAG1:<X>.0.Z or TAG1:<A>.0.B 273232785Speter 273332785Speter You can move a magic branch tag to the revisions of your choice by 273432785Speter using "update" to find the revisions you want to tag and reapplying 273532785Speter the tag to all the files with the '-F' option to force it to move the 273632785Speter existing <branch_tag>. 273732785Speter 273832785Speter cvs update -r <tag/rev> (or '-A' for the Main Branch) 273932785Speter cvs tag -F -b <branch_tag> 274032785Speter 274132785Speter If the earlier location of TAG1 refers to a physical branch within any 274232785Speter RCS file, moving it will make the existing branch in the file seem to 274332785Speter disappear from CVS's view. This is not a good idea unless you really 274432785Speter want to forget the existence of those RCS branches. 274532785Speter 274632785Speter If the "update" above retrieves the original branch point revision 274732785Speter (<X>), the "tag" command above will create the tag: 274832785Speter 274932785Speter TAG1:<X>.0.Z 275032785Speter 275132785Speter Where Z is 2 greater than the highest magic branch already on revision 275232785Speter <X>. The TAG1 branch will still have the same branch point (i.e. 275332785Speter revision <X>), but the first commit to the new TAG1 branch will create 275432785Speter a different RCS branch number (<X>.Z instead of <X>.Y). 275532785Speter 275632785Speter Renaming a magic <branch_tag> is the act of changing 275732785Speter 275832785Speter TAG1:<X>.0.Y 275932785Speter to 276032785Speter TAG2:<X>.0.Y 276132785Speter 276232785Speter There is no harm in changing a tag name as long as you forget that 276332785Speter TAG1 ever existed and you clean up any working directories with sticky 276432785Speter TAG1 tags on them by using "update -A", "update -r <other_tag>" or by 276532785Speter removing the working directories. 276632785Speter 276732785Speter On the other hand, actually changing the tag is not easy. 276832785Speter 276932785Speter See 3M.3 for why the seemingly obvious solution won't work: 277032785Speter 277132785Speter cvs tag -b -r <old_branch_tag> <new_branch_tag> 277232785Speter 277332785Speter The only direct way to rename a magic tag is to use the "admin" 277432785Speter command on each file: (You might want to use '-n'. Read "man rcs" and 277532785Speter look at the '-n' and '-N' options.) 277632785Speter 277732785Speter cvs admin -N<new_branch_tag>:<old_branch_tag> . 277832785Speter cvs tag -d <old_branch_tag> 277932785Speter 278032785Speter But you have to be careful because "admin" is different from other CVS 278132785Speter commands: 278232785Speter 278332785Speter "admin" can be used recursively, but only by specifying directory 278432785Speter names in its argument list (e.g. '.'), 278532785Speter 278632785Speter Where "rtag -r <old_branch_tag>" would interpret <old_branch_tag> as 278732785Speter a magic CVS branch tag, "admin" is a direct interface to RCS which 278832785Speter sees a magic branch tag as a simple (though non-existent) RCS revision 278932785Speter number. 279032785Speter 279132785Speter This is good for us in this particular case, but different from normal 279232785Speter CVS. 279332785Speter 279432785Speter "admin" also skips the Attic and produces different kinds of errors 279532785Speter than CVS usually does. (Because they are coming directly from RCS.) 279632785Speter 279732785Speter The other way to rename a magic <branch_tag> is to edit the Repository 279832785Speter files with a script of some kind. I've done it in the past, but I'll 279932785Speter leave it as an exercise for the reader. 280032785Speter 280132785Speter Last modified: _6/13/1997_ 280232785Speter 280332785Speter 6. Can I use RCS locally to record my changes without making them globally 280432785Speter visible by committing them? 280532785Speter 280632785Speter You can, but it will probably confuse CVS to have ",v" files in your 280732785Speter working directory. And you will lose all your log entries when you 280832785Speter finally commit it. 280932785Speter 281032785Speter Your best bet is to create your own CVS branch and work there. You can 281132785Speter commit as many revisions as you want, then merge it back into the main 281232785Speter line (or parent branch) when you are finished. 281332785Speter 281432785Speter Last modified: _6/13/1997_ 281532785Speter 281632785Speter 7. How can I allow access to the Repository by both CVS and RCS? 281732785Speter 281832785Speter The first step is to try not to. If some people are using CVS, there 281932785Speter is no reason for everyone not to. It is not hard to learn the basics 282032785Speter and CVS makes certain operations *easier* than a series of RCS 282132785Speter commands. Personal preference in what software tools can be applied to 282232785Speter a shared Repository has to take second place to system integration 282332785Speter needs. If you disagree, try writing some Lisp code for inclusion in 282432785Speter your Unix kernel and see what kind of reception you get. 282532785Speter 282632785Speter If you really must allow routine RCS access to the CVS Repository, you 282732785Speter can link an RCS sub-directory into a piece of the Repository: 282832785Speter 282932785Speter ln -s /Repository/some/directory/I/want RCS 283032785Speter 283132785Speter and RCS will work just fine. 283232785Speter 283332785Speter Those who are using RCS will have to keep the following in mind: 283432785Speter 283532785Speter If a file was originally added to the Repository by "import" and has 283632785Speter not been changed using CVS, the *RCS* default branch will remain 283732785Speter attached to the Vendor branch, causing revisions checked-in by "ci" to 283832785Speter wind up on the Vendor branch, instead of the main branch. Only CVS 283932785Speter moves the RCS default branch on first commit. 284032785Speter 284132785Speter The way around this is to checkin (using "ci") all the files first and 284232785Speter move them into the Repository. That way they won't have Vendor 284332785Speter branches. Then RCS will work OK. 284432785Speter 284532785Speter It is possible to use "rcs" and "ci" to make the files unusable by 284632785Speter CVS. The same is true of the CVS "admin" command. 284732785Speter 284832785Speter Normal RCS practice locks a file on checkout with "co -l". In such 284932785Speter an environment, RCS users should plan to keep survival gear and food 285032785Speter for at least 30 days near their desks. When faced with bizarre and 285132785Speter unexpected permission errors, howling mobs of slavering CVS users will 285232785Speter run the RCS users out of town with pitchforks and machetes. 285332785Speter 285432785Speter See 3C.8 for a way to avoid machetes aroused by lock collisions. 285532785Speter 285632785Speter Though files checked in by RCS users will correctly cause 285732785Speter "up-to-date" failures during CVS "commits" and they will be 285832785Speter auto-merged into CVS working directories during "update", the opposite 285932785Speter won't happen. 286032785Speter 286132785Speter RCS users will get no warning and will not be required to merge older 286232785Speter work into their code. They can easily checkin an old file on top of a 286332785Speter new revision added by CVS, discarding work committed earlier by CVS 286432785Speter users. 286532785Speter 286632785Speter See the howling mob scenario described above. 286732785Speter 286832785Speter RCS is great. I have used it for years. But I wouldn't mix it this 286932785Speter way. In a two-camp society, you are asking for real trouble, both in 287032785Speter technical hassles to clean up and in political hassles to soothe. 287132785Speter Branch merges will also be a major problem. 287232785Speter 287332785Speter Last modified: _6/13/1997_ 287432785Speter 287532785Speter 8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't 287632785Speter the file now have a modified date of yesterday? 287732785Speter 287832785Speter CVS restores dates from the RCS files only on first "checkout". After 287932785Speter that, it is more important to maintain a timestamp relative to the 288032785Speter other files in the working directory. 288132785Speter 288232785Speter Example: You committed a source file at 5PM. Bubba updated his copy of 288332785Speter the file, grabbing your changes, then changed and committed a new 288432785Speter revision of the file at 6PM. At 7PM, you compile your file. Then you 288532785Speter execute "update". If CVS sets the date to the one in the RCS file, the 288632785Speter file would be given a timestamp of 6PM and your Makefile wouldn't 288732785Speter rebuild anything that depended on it. Bad news. 288832785Speter 288932785Speter Note that the same logic applies to retrieving a revision out of the 289032785Speter Repository to replace a deleted file. If CVS changes your file in an 289132785Speter existing working directory, whether it was because a new revision was 289232785Speter committed by someone else or because you deleted your working file, 289332785Speter the timestamp on the retrieved working file *must* be set to the 289432785Speter current time. 289532785Speter 289632785Speter When you first retrieve a file, there is no reason to expect any 289732785Speter particular timestamp on the file within your working area. But later, 289832785Speter when dependency checking is performed during a build, it is more 289932785Speter important for the timestamps on the local files to be consistent with 290032785Speter each other than than it is for working files to match the timestamps 290132785Speter on the files in the Repository. See 4D.17 for some more about 290232785Speter timestamps. 290332785Speter 290432785Speter Last modified: _6/13/1997_ 290532785Speter 290654427Speter 9. Why do timestamps sometimes get set to the date of the revision, 290754427Speter sometimes not? The inconsistency causes unnecessary recompiles. 290854427Speter 290954427Speter The "checkout" command normally sets the timestamp of a working file 291054427Speter to match the timestamp stored on the revision in the Repository's RCS 291154427Speter file. 291254427Speter 291354427Speter The "commit" command retains the timestamp of the file, if the act of 291454427Speter checking it in didn't change it (by expanding keywords). 291554427Speter 291654427Speter The "update" command sets the time to the revision time the first time 291754427Speter it sees the file. After that, it sets the time of the file to the 291854427Speter current time. See 4D.8 for a reason why. 291954427Speter 292054427Speter Here's a two-line PERL program to set timestamps on files based on 292154427Speter other timestamps. I've found this program useful. When you are certain 292254427Speter you don't want a source file to be recompiled, you can set its 292354427Speter timestamp to the stamp on the object file. 292454427Speter 292554427Speter #!/usr/local/bin/perl 292654427Speter # 292754427Speter # Set timestamp of args 2nd-Last to that of the first arg. 292854427Speter # 292954427Speter ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime) 293054427Speter = stat(shift); 293154427Speter utime($atime,$mtime,@ARGV); 293254427Speter 293354427Speter Last modified: _6/13/1997_ 293454427Speter 293554427Speter 10. While in the middle of a large "commit", how do I run other commands, 293632785Speter like "diff" or "stat" without seeing lock errors? 293732785Speter 293832785Speter Type: 293932785Speter cvs -n <command> 294032785Speter 294132785Speter The '-n' option to the main cvs command turns off lock checking, a 294232785Speter reasonable act for read-only commands given the promise offered by 294332785Speter '-n' not to alter anything. The "diff", "log" and "stat" commands 294432785Speter provide the same information (for files that are not being committed) 294532785Speter when used with and without the '-n' option. 294632785Speter 294732785Speter Warning: Ignoring locks can produce inconsistent information across a 294832785Speter collection of files if you are looking at the revisions affected by an 294932785Speter active commit. Be careful when creating "patches" from the output of 295032785Speter "cvs -n diff". If you are looking only at your working files, tagged 295132785Speter revisions, and BASE revisions (revisions whose numbers are read from 295232785Speter your ./CVS/Entries files), you should get consistent results. Of 295332785Speter course, if you catch a single file in the middle of RCS activity, you 295432785Speter might get some strange errors. 295532785Speter 295632785Speter Note that the suggested command is "cvs -n <command>". The visually 295732785Speter similar command "cvs <command> -n" has no relation to the suggested 295832785Speter usage and has an entirely different meaning for each command. 295932785Speter 296032785Speter "cvs -n update" also works in the middle of a commit, providing 296132785Speter slightly different information from a plain "cvs update". But, of 296232785Speter course, it also avoids modifying anything. 296332785Speter 296432785Speter You could also use the RCS functions, "rlog" and "rcsdiff" to display 296532785Speter some of the information by referring directly to the Repository files. 296632785Speter 296732785Speter You need RCS version 5 or later for the commands described above to 296832785Speter work reliably. 296932785Speter 297032785Speter Last modified: _6/13/1997_ 297132785Speter 297254427Speter 11. Where did the ./CVS/Entries.Static file come from? What is it for? 297332785Speter 297432785Speter Each CVS working directory contains a ./CVS/Entries file listing the 297532785Speter files managed by CVS in that working directory. Normally, if the 297632785Speter "update" command finds a file in the Repository that is not in the 297732785Speter ./CVS/Entries file, "update" copies the appropriate revision of the 297832785Speter "new" file out of the Repository and adds the filename to the Entries 297932785Speter file. This happens for files: 298032785Speter 298132785Speter Added to the Repository from another working directory. 298232785Speter 298332785Speter Dragged out of the Attic when switching branches with "update -A" or 298432785Speter "update -r". 298532785Speter 298632785Speter Whose names were deleted from the ./CVS/Entries file. 298732785Speter 298832785Speter If the ./CVS/Entries.Static file exists, CVS will only bring out 298932785Speter revisions of files that are contained in either ./CVS/Entries or 299032785Speter ./CVS/Entries.Static. If a Repository file is found in *neither* file, 299132785Speter it is ignored. 299232785Speter 299332785Speter The ./CVS/Entries.Static file is created when you check out an 299432785Speter individual file or a module that creates working directories that 299532785Speter don't contain all files in the corresponding Repository directory. In 299632785Speter those cases, without an ./CVS/Entries.Static file, a simple "update" 299732785Speter would bring more files out of the Repository than the original 299832785Speter "checkout" wanted. 299932785Speter 300032785Speter The ./CVS/Entries.Static file can be removed by hand. It is 300132785Speter automatically removed if you run "update -d" to create new directories 300232785Speter (even if no new directories are created). (Internally, since 300332785Speter "checkout" turns on the '-d' flag and calls the "update" routine, a 300432785Speter "checkout" of a module or directory that writes into an existing 300532785Speter directory will also remove the ./CVS/Entries.Static file.) 300632785Speter 300732785Speter Last modified: _6/13/1997_ 300832785Speter 300954427Speter 12. Why did I get the wrong Repository in the loginfo message? 301032785Speter 301132785Speter You probably: 301232785Speter 301332785Speter Use multiple Repositories. 301432785Speter 301532785Speter Configured CVS to use absolute pathnames in the ./CVS/Repository 301632785Speter file. 301732785Speter 301832785Speter Configured CVS not to use the ./CVS/Root file. 301932785Speter 302032785Speter Typed the "commit" command in one Repository with your $CVSROOT 302132785Speter pointing at another. 302232785Speter 302332785Speter "commit" and all other CVS commands will heed an absolute pathname in 302432785Speter the ./CVS/Repository file (or in the "-d CVSrootdir" override), but 302532785Speter the log function doesn't take arguments -- it just looks at $CVSROOT. 302632785Speter 302732785Speter If you avoid even one of the four steps above, you won't see this 302832785Speter problem. If you configure ./CVS/Root, you won't be allowed to execute 302932785Speter the program causing the error. 303032785Speter 303132785Speter Last modified: _6/13/1997_ 303232785Speter 303354427Speter 13. How do I run CVS setuid so I can only allow access through the CVS 303432785Speter program itself? 303532785Speter 303632785Speter Setuid to root is not a great idea. Any program that modifies files 303732785Speter and is used by a widely distributed group of users is not a good 303832785Speter candidate for a setuid program. (The worst suggestion I've ever heard 303932785Speter was to make *Emacs* setuid to root.) 304032785Speter 304132785Speter Root access on Unix is too powerful. Also, it might not work in some 304232785Speter (secure?) environments. 304332785Speter 304432785Speter Running it setuid to some user other than root might work, if you add 304532785Speter this line to main.c near the beginning: 304632785Speter 304732785Speter setuid(geteuid()); 304832785Speter 304932785Speter Otherwise it uses *your* access rights, rather than the effective 305032785Speter uid's. 305132785Speter 305232785Speter Also, you have to invent a fake user whose name will show up in 305332785Speter various places. But many sites, especially those who might want a 305432785Speter setuid CVS for "security", want personal accountability -- no generic 305532785Speter accounts. I don't know whether accountability outweighs file security. 305632785Speter 305732785Speter And finally, unless you take action to limit the "admin" command, you 305832785Speter are leaving yourself unprotected anyway. 305932785Speter 306032785Speter Last modified: _6/13/1997_ 306132785Speter 306254427Speter 14. How about using groups and setgid() then? 306332785Speter 306432785Speter Here is a way to run CVS setgid in some environments: 306532785Speter 306632785Speter Stick this near the front of the main() in main.c: 306732785Speter 306832785Speter setgid(getegid()); 306932785Speter 307032785Speter This will allow "access" to work on systems where it only works on the 307132785Speter real gid. 307232785Speter 307332785Speter Create a group named "cvsg". (This example uses "cvsg". You can name 307432785Speter it as you wish.) 307532785Speter 307632785Speter Put *no* users in the "cvsg" group. You can put Repository 307732785Speter administrators in this group if you want to. 307832785Speter 307932785Speter Set the cvs executable to setgid (not setuid): 308032785Speter 308132785Speter cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs 308232785Speter 308332785Speter Make sure every file in the Repository is in group "cvsg": 308432785Speter 308532785Speter chown -R root.cvsg $CVSROOT 308632785Speter 308732785Speter Change all directory permissions to 770. This allows all access to 308832785Speter the files by the "cvsg" group (which has no members!) and no access at 308932785Speter all to anyone else. 309032785Speter 309132785Speter find $CVSROOT -type d -exec chmod 2770 {} \; 309232785Speter 309332785Speter On some systems you might have to type: 309432785Speter 309532785Speter find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \; 309632785Speter 309732785Speter This should allow only the cvs program (or other "setgid to group 309832785Speter cvsg") programs to write into the area, but no one else. Yes the user 309932785Speter winds up owning the file, but s/he can't find it again later since 310032785Speter s/he can't traverse the tree. (If you enable the world execute bit 310132785Speter (mode 2771) on directories, users can traverse the tree and the user 310232785Speter who last wrote the file can still write to it.) 310332785Speter 310432785Speter If you want to allow read access, check out an entire tree somewhere. 310532785Speter You have to do this anyway to build it. 310632785Speter 310732785Speter Note: If you are using a stupid file system that can't inherit file 310832785Speter groups from the parent directory (even with the "setgid" (Octal 2000) 310932785Speter bit set), you might have to modify CVS (or RCS) to reset the group 311032785Speter every time you create a new file. I have not tested this. 311132785Speter 311232785Speter The setgid() method shares with the setuid() method the problem of 311332785Speter keeping "admin" from breaking things. 311432785Speter 311532785Speter Last modified: _6/13/1997_ 311632785Speter 311754427Speter 15. How do I use the "commitinfo" file? 311832785Speter 311932785Speter Go read 4B.2 first. 312032785Speter 312132785Speter The "commitinfo" file allows you to execute "sanity check" functions 312232785Speter before allowing a commit. If any function called from within the 312332785Speter commitinfo file exits with a non-zero status, the commit is denied. 312432785Speter 312532785Speter To fill out a "commitinfo" file, ask yourself (and those sharing your 312632785Speter Repository) these questions: 312732785Speter 312832785Speter - Is there anything you want to check or change before someone is 312932785Speter allowed to commit a file? If not, forget commitinfo. 313032785Speter 313132785Speter If you want to serialize binary files, you might consider something 313232785Speter like the rcslock.pl program in the contrib directory of the CVS 313332785Speter sources. 313432785Speter 313532785Speter - Do you want to execute the same exact thing before committing to 313632785Speter every file in the Repository? (This is useful if you want to program 313732785Speter the restrictions yourself.) If so, set up a single line in the 313832785Speter commitinfo: 313932785Speter 314032785Speter DEFAULT /absolute/path/to/program 314132785Speter 314232785Speter CVS executes the program once for each directory that "commit" 314332785Speter traverses, passing as arguments the directory and the files to be 314432785Speter committed within that directory. 314532785Speter 314632785Speter Write your program accordingly. Some examples exist in the contrib 314732785Speter directory. 314832785Speter 314932785Speter - Do you want a different kind of sanity check performed for different 315032785Speter directories? If so, you'll have to decide what to do for all 315132785Speter directories and enter lines like this: 315232785Speter 315332785Speter regexp1 /absolute/path/to/program-for-regexp1 315432785Speter regexp2 /absolute/path/to/program-for-regexp2 315532785Speter DEFAULT /absolute/path/to/program-for-all-else 315632785Speter 315732785Speter - Is there anything you want to happen before *all* commits, in 315832785Speter addition to other pattern matches? If so, include a line like this: 315932785Speter 316032785Speter ALL /absolute/path/to/program 316132785Speter 316232785Speter It is executed independently of all the above. And it's repeatable -- 316332785Speter you can have as many ALL lines as you like. 316432785Speter 316532785Speter Last modified: _6/13/1997_ 316632785Speter 316754427Speter 16. How do I use the "loginfo" files? 316832785Speter 316932785Speter See 4B.2 and the "commitinfo" question above. 317032785Speter 317132785Speter The "loginfo" file has the same format as the "commitinfo" file, but 317232785Speter its function is different. Where the "commitinfo" information is used 317332785Speter before a commit, the "loginfo" file is used after a commit. 317432785Speter 317532785Speter All the commands in the "loginfo" file should read data from standard 317632785Speter input, then either append it to a file or send a message to a mailing 317732785Speter list. If you want to make it simple, you can put shell (the shell used 317832785Speter by "popen(3)") command lines directly in the "loginfo" (or 317932785Speter "commitinfo") file. These seem to work: 318032785Speter 318132785Speter ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail 318232785Speter -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) > 318332785Speter /path/name/to/log/file 318432785Speter 318532785Speter Last modified: _6/13/1997_ 318632785Speter 318754427Speter 17. How can I keep people with restrictive umask values from blocking 318832785Speter access to the Repository? 318932785Speter 319032785Speter If a user creates a new file with restricted permissions (e.g. 0600), 319132785Speter and commits it, the Repository will have a file in it that is 319232785Speter unreadable by everyone. The 0600 example would be unreadable by 319332785Speter *anyone* but root and the user who created it. 319432785Speter 319532785Speter There are 3 solutions to this: 319632785Speter 319732785Speter Let it happen. This is a valid way to protect things. If everyone is 319832785Speter working alone, a umask of 077 is OK. If everyone is working only in 319932785Speter small groups, a umask of 007 is OK. 320032785Speter 320132785Speter Train your users not to create such things if you expect to share 320232785Speter them. 320332785Speter 320432785Speter See 4B.5 for a small script that will reset the umask. 320532785Speter 320632785Speter I personally don't like the idea of a program automatically 320732785Speter *loosening* security. It would be better for you all to talk about the 320832785Speter issue and decide how to work together. 320932785Speter 321032785Speter Last modified: _6/13/1997_ 321132785Speter 321232785Speter Category: /Commands_/ 321332785Speter 321432785Speter " Commands " 321532785Speter 321632785Speter Category: /Commands_/add_ad_new/ 321732785Speter 321832785Speter " + "add", "ad", "new"" 321932785Speter 322032785Speter 1. What is "add" for? 322132785Speter 322232785Speter To add a new directory to the Repository or to register the desire to 322332785Speter add a new file to the Repository. 322432785Speter 322532785Speter The directory is created immediately, while the desire to add the file 322632785Speter is recorded in the local ./CVS administrative directory. To really add 322732785Speter the file to the Repository, you must then "commit" it. 322832785Speter 322932785Speter Last modified: _6/13/1997_ 323032785Speter 323132785Speter 2. How do I add a new file to the branch I'm working on? 323232785Speter 323332785Speter The user actions for adding a file to any branch, including the Main 323432785Speter Branch, are exactly the same. 323532785Speter 323632785Speter You are in a directory checked out (or updated) with the '-A' option 323732785Speter (to place you on the Main Branch) or the "-r <branch_tag>" option (to 323832785Speter place you on a branch tagged with <branch_tag>). To add <file> to the 323932785Speter branch you are on, you type: 324032785Speter 324132785Speter cvs add <file> 324232785Speter cvs commit <file> 324332785Speter 324432785Speter If no ./CVS/Tag file exists (the '-A' option deletes it), the file 324532785Speter will be added to the Main Branch. If a ./CVS/Tag file exists (the "-r 324632785Speter <branch_tag>" option creates it), the file will be added to the branch 324732785Speter named (i.e. tagged with) <branch_tag>. 324832785Speter 324932785Speter Unless you took steps to first add the file to the Main Branch, your 325032785Speter new file ends up in the Attic. 325132785Speter 325232785Speter Last modified: _6/13/1997_ 325332785Speter 325432785Speter 3. Why did my new file end up in the Attic? 325532785Speter 325632785Speter The file is thrown into the Attic to keep it from being visible when 325732785Speter you check out the Main Branch, since it was never committed to the 325832785Speter Main Branch. 325932785Speter 326032785Speter Last modified: _6/13/1997_ 326132785Speter 326232785Speter 4. Now that it's in the Attic, how do I connect it to the Main branch? 326332785Speter 326432785Speter That can be considered a kind of "merge". See 4C.8 326532785Speter 326632785Speter Last modified: _6/13/1997_ 326732785Speter 326832785Speter 5. How do I avoid the hassle of reconnecting an Attic-only file to the Main 326932785Speter Branch? 327032785Speter 327132785Speter You create it on the Main Branch first, then branch it. 327232785Speter 327332785Speter If you haven't yet added the file or if you decided to delete the new 327432785Speter Attic file and start over, then do the following: (If you added the 327532785Speter file (or worse, the 157 files) to the Attic and don't want to start 327632785Speter over, try the procedure in 4C.8.) 327732785Speter 327832785Speter Temporarily remove the sticky branch information. Either: 327932785Speter 328032785Speter Move the whole directory back to the Main Branch. [This might not be 328132785Speter a good idea if you have modified files, since it will require a merge 328232785Speter in each direction.] 328332785Speter 328432785Speter cvs update -A 328532785Speter 328632785Speter *or* 328732785Speter 328832785Speter Move the ./CVS/Tag file out of the way. 328932785Speter 329032785Speter mv ./CVS/Tag HOLD_Tag 329132785Speter 329232785Speter Add and branch the file "normally": 329332785Speter 329432785Speter cvs add <file> 329532785Speter cvs commit <file> 329632785Speter cvs tag -b <branch_tag> <file> 329732785Speter 329832785Speter [<branch_tag> is the same Branch Tag as you used on all the other 329932785Speter files. Look at ./CVS/Entries or the output from "cvs stat" for sticky 330032785Speter tags.] 330132785Speter 330232785Speter Clean up the temporary step. 330332785Speter 330432785Speter If you moved the ./CVS/Tag file, put it back. Then move the new file 330532785Speter onto the branch where you are working. 330632785Speter 330732785Speter mv HOLD_Tag ./CVS/Tag 330832785Speter cvs update -r <branch_tag> <file> 330932785Speter 331032785Speter If you ran "update -A" rather than moving the ./CVS/Tag file, move 331132785Speter the whole directory (including the new file) back onto the branch 331232785Speter where you were working: 331332785Speter 331432785Speter cvs update -r <branch_tag> 331532785Speter 331632785Speter Last modified: _6/13/1997_ 331732785Speter 331832785Speter 6. How do I cancel an "add"? 331932785Speter 332032785Speter If you want to remove the file entirely and cancel the "add" at the 332132785Speter same time, type: 332232785Speter 332332785Speter cvs remove -f <file> 332432785Speter 332532785Speter If you want to cancel the "add", but leave the file as it was before 332632785Speter you typed "cvs add", then you have to fake it: 332732785Speter 332832785Speter mv <file> <file>.hold 332932785Speter cvs remove <file> 333032785Speter mv <file>.hold <file> 333132785Speter 333232785Speter Last modified: _6/13/1997_ 333332785Speter 333432785Speter 7. What are the ./CVS/file,p and ./CVS/file,t files for? 333532785Speter 333632785Speter The ./CVS/file,p and ./CVS/file,t files are created by the "add" 333732785Speter command to hold command line options and message text between the time 333832785Speter of the "add" command and the expected "commit". 333932785Speter 334032785Speter The ./CVS/file,p file is always null, since its function was absorbed 334132785Speter by the "options" field in the ./CVS/Entries file. If you put something 334232785Speter in this file it will be used as arguments to the RCS "ci" command that 334332785Speter commit uses to check the file in, but CVS itself doesn't put anything 334432785Speter there. 334532785Speter 334632785Speter The ./CVS/file,t file is null unless you specify an initial message in 334732785Speter an "add -m 'message'" command. The text is handed to "rcs -i 334832785Speter -t./CVS/file,t" to create the initial RCS file container. 334932785Speter 335032785Speter Both files must exist to commit a newly added file. If the 335132785Speter ./CVS/file,p file doesn't exist, CVS prints an error and aborts the 335232785Speter commit. If the ./CVS/file,t file doesn't exist, RCS prints an error 335332785Speter and CVS gets confused, but does no harm. 335432785Speter 335532785Speter To recover from missing ,p and ,t files, just create two zero-length 335632785Speter files and rerun the "commit". 335732785Speter 335832785Speter Last modified: _6/13/1997_ 335932785Speter 336032785Speter 8. How do I "add" a binary file? 336132785Speter 336232785Speter If you configured CVS to use the GNU version of "diff" and "diff3", 336332785Speter you only need to turn off RCS keyword expansion. 336432785Speter 336532785Speter First you turn off RCS keyword expansion for the initial checkin by 336632785Speter using "add -ko". It works like "update -ko" in creating a "sticky" 336732785Speter option only for the copy of the file in the current working directory. 336832785Speter 336932785Speter cvs add -ko <file> 337032785Speter 337132785Speter Commit the file normally. The sticky -ko option will be used. 337232785Speter 337332785Speter cvs commit <file> 337432785Speter 337532785Speter Then mark the RCS file in the Repository so that keyword expansion is 337632785Speter turned off for all checked out versions of the file. 337732785Speter 337832785Speter cvs admin -ko <file> 337932785Speter 338032785Speter Since "admin -ko" records the keyword substitution value in the 338132785Speter Repository's RCS file, you no longer need the sticky option. You can 338232785Speter turn it off with the "update -A" command, but if you were on a branch, 338332785Speter you'll have to follow it "update -r <branch_tag>" to put yourself back 338432785Speter on the branch. 338532785Speter 338632785Speter Managing that binary file is another problem. See 4D.1. 338732785Speter 338832785Speter Last modified: _6/13/1997_ 338932785Speter 339032785Speter Category: /Commands_/admin_adm_rcs/ 339132785Speter 339232785Speter " + "admin", "adm", "rcs"" 339332785Speter 339432785Speter 1. What is "admin" for? 339532785Speter 339632785Speter To provide direct access to the underlying "rcs" command (which is not 339732785Speter documented in this FAQ) bypassing all safeguards and CVS assumptions. 339832785Speter 339932785Speter Last modified: _6/13/1997_ 340032785Speter 340132785Speter 2. Wow! Isn't that dangerous? 340232785Speter 340332785Speter Yes. 340432785Speter 340532785Speter Though you can't hurt the internal structure of an RCS file using its 340632785Speter own "rcs" command, you *can* change the underlying RCS files using 340732785Speter "admin" in ways that CVS can't handle. 340832785Speter 340932785Speter If you feel the need to use "admin", create some test files with the 341032785Speter RCS "ci" command and experiment on them with "rcs" before blasting any 341132785Speter CVS files. 341232785Speter 341332785Speter Last modified: _6/13/1997_ 341432785Speter 341532785Speter 3. What would I normally use "admin" for? 341632785Speter 341732785Speter Normally, you wouldn't use admin at all. In unusual circumstances, 341832785Speter experts can use it to set up or restore the internal RCS state that 341932785Speter CVS requires. 342032785Speter 342132785Speter You can use "admin -o" (for "outdate") to remove revisions you don't 342232785Speter care about. This has its own problems, such as leaving dangling Tags 342332785Speter and confusing the "update" command. 342432785Speter 342532785Speter There is some feeling among manipulators of binary files that "admin 342632785Speter -l" should be used to serialize access. See 3C.8. 342732785Speter 342832785Speter An interesting use for "admin" came up while maintaining CVS itself. I 342932785Speter import versions of CVS onto the Vendor branch of my copy of CVS, make 343032785Speter changes to some files and ship the diffs (created by "cvs diff -c -r 343132785Speter TO_BRIAN") off to Brian Berliner. After creating the diff, I retag 343232785Speter ("cvs tag -F TO_BRIAN") the working directory, which is then ready to 343332785Speter produce the next patch. 343432785Speter 343532785Speter I'll use "add.c" as an example (only because the name is short). 343632785Speter 343732785Speter When the next release came out, I discovered that the released "add.c" 343832785Speter (version 1.1.1.3 on the Vendor branch) was exactly the same as my 343932785Speter modified file (version 1.3). I didn't care about the changelog on 344032785Speter versions 1.2 and 1.3 (or the evidence of having done the work), so I 344132785Speter decided to revert the file to the state where it looked like I had not 344232785Speter touched the file -- where I was just using the latest on the vendor 344332785Speter branch after a sequence of imports. 344432785Speter 344532785Speter To do that, I removed all the revisions on the main branch, except for 344632785Speter the original 1.1 from which the Vendor branch sprouts: 344732785Speter 344832785Speter cvs admin -o1.2: add.c 344932785Speter 345032785Speter Then I set the RCS "default branch" back to the Vendor branch, the way 345132785Speter import would have created it: 345232785Speter 345332785Speter cvs admin -b1.1.1 add.c 345432785Speter 345532785Speter And I moved the "TO_BRIAN" Tag to the latest revision on the Vendor 345632785Speter branch, since that is the base from which further patches would be 345732785Speter created (if I made any): 345832785Speter 345932785Speter cvs admin -NTO_BRIAN:1.1.1.3 add.c 346032785Speter 346132785Speter Instead of 1.1.1.3, I could have used one of the "Release Tags" last 346232785Speter applied by "import" (3rd through Nth arguments). 346332785Speter 346432785Speter Suggestion: Practice on non-essential files. 346532785Speter 346632785Speter Last modified: _6/13/1997_ 346732785Speter 346832785Speter 4. What should I avoid when using "admin"? 346932785Speter 347032785Speter If you know exactly what you are doing, hack away. But under normal 347132785Speter circumstances: 347232785Speter 347332785Speter Never use "admin" to alter branches (using the '-b' option), which CVS 347432785Speter takes very seriously. If you change the default branch, CVS will not 347532785Speter work as expected. If you create new branches without using the "tag 347632785Speter -b" command, you may not be able to treat them as CVS branches. 347732785Speter 347832785Speter See 3C.8 for a short discussion of how to use "admin -l" for 347932785Speter serializing access to binary files. 348032785Speter 348132785Speter The "admin -o <file>" allows you to delete revisions, usually a bad 348232785Speter idea. You should commit a correction rather than back out a revision. 348332785Speter Outdating a revision is prone to all sorts of problems: 348432785Speter 348532785Speter Discarding data is always a bad idea. Unless something in the 348632785Speter revision you just committed is a threat to your job or your life, 348732785Speter (like naming a function "<boss's name>_is_a_dweeb", or including the 348832785Speter combination to the local Mafioso's safe in a C comment), just leave it 348932785Speter there. No one cares about simple mistakes -- just commit a corrected 349032785Speter revision. 349132785Speter 349232785Speter The time travel paradoxes you can cause by changing history are not 349332785Speter worth the trouble. Even if CVS can't interfere with your parents' 349432785Speter introduction, it *can* log commits in at least two ways (history and 349532785Speter loginfo). The reports now lie -- the revision referred to in the logs 349632785Speter no longer exists. 349732785Speter 349832785Speter If you used "import" to place <file> into CVS, outdating all the 349932785Speter revisions on the Main branch back to and including revision 1.2 (or 350032785Speter worse, 1.1), will produce an invalid CVS file. 350132785Speter 350232785Speter If the <file>,v file only contains revision 1.1 (and the connected 350332785Speter branch revision 1.1.1.1), then the default branch must be set to the 350432785Speter Vendor branch as it was when you first imported the file. Outdating 350532785Speter back through 1.2 doesn't restore the branch setting. Despite the above 350632785Speter admonition against it, "admin -b" is the only way to recover: 350732785Speter 350832785Speter cvs admin -b1.1.1 <file> 350932785Speter 351032785Speter Although you can't outdate a physical (RCS) branch point without 351132785Speter removing the whole branch, you *can* outdate a revision referred to by 351232785Speter a magic branch tag. If you do so, you will invalidate the branch. 351332785Speter 351432785Speter If you "outdate" a tagged revision, you will invalidate all uses of 351532785Speter the <tag>, not just the one on <file>. A tag is supposed to be 351632785Speter attached to a consistent set of files, usually a set built as a unit. 351732785Speter By discarding one of the files in the set, you have destroyed the 351832785Speter utility of the <tag>. And it leaves a dangling tag, which points to 351932785Speter nothing. 352032785Speter 352132785Speter And even worse, if you commit a revision already tagged, you will 352232785Speter alter what the <tag> pointed to without using the "tag" command. For 352332785Speter example, if revision 1.3 has <tag> attached to it and you "outdate" 352432785Speter the 1.3 revision, <tag> will point to a nonexistent revision. Although 352532785Speter this is annoying, it is nowhere near as much trouble as the problem 352632785Speter that will occur when you commit to this file again, recreating 352732785Speter revision 1.3. The old tag will point to the new revision, a file that 352832785Speter was not in existence when the <tag> was applied. And the discrepancy 352932785Speter is nearly undetectable. 353032785Speter 353132785Speter If you don't understand the above, you should not use the admin 353232785Speter command at all. 353332785Speter 353432785Speter Last modified: _6/13/1997_ 353532785Speter 353632785Speter 5. How do I restrict the "admin" command? The -i flag in the modules file 353732785Speter can restrict commits. What's the equivalent for "admin"? 353832785Speter 353932785Speter At this writing, to disable the "admin" command, you will have to 354032785Speter change the program source code, recompile and reinstall. 354132785Speter 354232785Speter Last modified: _6/13/1997_ 354332785Speter 354432785Speter 6. I backed out a revision with "admin -o" and committed a replacement. Why 354532785Speter doesn't "update" retrieve the new revision? 354632785Speter 354732785Speter CVS is confused because the revision in the ./CVS/Entries file matches 354832785Speter the latest revision in the Repository *and* the timestamp in the 354932785Speter ./CVS/Entries file matches your working file. CVS believes that your 355032785Speter file is "up-to-date" and doesn't need to be updated. 355132785Speter 355232785Speter You can cause CVS to notice the change by "touch"ing the file. 355332785Speter Unfortunately what CVS will tell you is that you have a "Modified" 355432785Speter file. If you then "commit" the file, you will bypass the normal CVS 355532785Speter check for "up-to-date" and will probably commit the revision that was 355632785Speter originally removed by "admin -o". 355732785Speter 355832785Speter Changing a file without changing the revision number confuses CVS no 355932785Speter matter whether you did it by replacing the revision (using "admin -o" 356032785Speter and "commit" or raw RCS commands) or by applying an editor directly to 356132785Speter a Repository (",v") file. Don't do it unless you are absolutely 356232785Speter certain no one has the latest revision of the file checked out. 356332785Speter 356432785Speter The best solution to this is to institute a program of deterrent 356532785Speter flogging of abusers of "admin -o". 356632785Speter 356732785Speter The "admin" command has other problems." See 3B.4 above. 356832785Speter 356932785Speter Last modified: _6/13/1997_ 357032785Speter 357132785Speter Category: /Commands_/checkout_co_get/ 357232785Speter 357332785Speter " + "checkout", "co", "get"" 357432785Speter 357532785Speter 1. What is "checkout" for? 357632785Speter 357732785Speter To acquire a copy of a module (or set of files) to work on. 357832785Speter 357932785Speter All work on files controlled by CVS starts with a "checkout". 358032785Speter 358132785Speter Last modified: _6/13/1997_ 358232785Speter 358332785Speter 2. What is the "module" that "checkout" takes on the command line? 358432785Speter 358532785Speter It is a name for a directory or a collection of files in the 358632785Speter Repository. It provides a compact name space and the ability to 358732785Speter execute before and after helper functions based on definitions in the 358832785Speter modules file. 358932785Speter 359032785Speter See 1D.11. 359132785Speter 359232785Speter Last modified: _6/13/1997_ 359332785Speter 359432785Speter 3. Isn't a CVS "checkout" just a bunch of RCS checkouts? 359532785Speter 359632785Speter Like much of CVS, a similar RCS concept is used to support a CVS 359732785Speter function. But a CVS checkout is *not* the same as an RCS checkout. 359832785Speter 359932785Speter Differences include: 360032785Speter 360132785Speter CVS does not lock the files. Others may access them at the same 360232785Speter time. 360332785Speter 360432785Speter CVS works best when you provide a name for a collection of files (a 360532785Speter module or a directory) rather than an explicit list of files to work 360632785Speter on. 360732785Speter 360832785Speter CVS remembers what revisions you checked out and what branch you are 360932785Speter on, simplifying later commands. 361032785Speter 361132785Speter Last modified: _6/13/1997_ 361232785Speter 361332785Speter 4. What's the difference between "update" and "checkout"? 361432785Speter 361532785Speter The "checkout" and "update" commands are nearly equivalent in how they 361632785Speter treat individual files. They differ in the following ways: 361732785Speter 361832785Speter The "checkout" command always creates a directory, moves into it, 361932785Speter then becomes equivalent to "update -d". 362032785Speter 362132785Speter The "update" command does not create directories unless you add the 362232785Speter '-d' option. 362332785Speter 362432785Speter "Update" is intended to be executed within a working directory 362532785Speter created by "checkout". It doesn't take a module or directory argument, 362632785Speter but figures out what Repository files to look at by reading the files 362732785Speter in the ./CVS administrative directory. 362832785Speter 362932785Speter The two commands generate completely different types of records in 363032785Speter the "history" file. 363132785Speter 363232785Speter Last modified: _6/13/1997_ 363332785Speter 363432785Speter 5. Why can't I check out a file from within my working directory? 363532785Speter 363632785Speter Though you *can* check out a file, you normally check out a module or 363732785Speter directory. And you normally do it only once at the beginning of a 363832785Speter project. 363932785Speter 364032785Speter After the initial "checkout", you can use the "update" command to 364132785Speter retrieve any file you want within the checked-out directory. There is 364232785Speter no need for further "checkout" commands. 364332785Speter 364432785Speter If you want to retrieve another module or directory to work on, you 364532785Speter must provide two pathnames: where to find it in the Repository and 364632785Speter where to put it on disk. The "modules" file and your current directory 364732785Speter supply two pieces of naming information. While inside a checked-out 364832785Speter working directory, the CVS administrative information provides most of 364932785Speter the rest. 365032785Speter 365132785Speter You should be careful not to confuse CVS with RCS and use "checkout" 365232785Speter in the RCS sense. An RCS "checkout" (which is performed by the RCS 365332785Speter "co" command) is closer to a "cvs update" than to a "cvs checkout". 365432785Speter 365532785Speter Last modified: _6/13/1997_ 365632785Speter 365732785Speter 6. How do I avoid dealing with those long relative pathnames? 365832785Speter 365932785Speter This question has also been phrased: 366032785Speter 366132785Speter How do I avoid all those layers of directories on checkout? or Why do 366232785Speter I have to go to the top of my working directory and checkout some long 366332785Speter pathname to get a file or two? 366432785Speter 366532785Speter This type of question occurs only among groups of people who decide 366632785Speter not to use "modules". The answer is to use "modules". 366732785Speter 366832785Speter When you hand the "checkout" command a relative pathname rather than a 366932785Speter module name, all directories in the path are created, maintaining the 367032785Speter same directory hierarchy as in the Repository. The same kind of 367132785Speter environment results if you specify a "module" that is really an alias 367232785Speter expanding into a list of relative pathnames rather than a list of 367332785Speter module names. 367432785Speter 367532785Speter If you use "module" names, "checkout" creates a single directory by 367632785Speter the name of the module in your current directory. This "module" 367732785Speter directory becomes your working directory. 367832785Speter 367932785Speter The "module" concept combines the ability to "name" a collection of 368032785Speter files with the ability to structure the Repository so that consistent 368132785Speter sets of files are checked out together. It is the responsibility of 368232785Speter the Repository Administrators to set up a modules file that describes 368332785Speter the software within the Repository. 368432785Speter 368532785Speter Last modified: _6/13/1997_ 368632785Speter 368732785Speter 7. Can I move a checked-out directory? Does CVS remember where it was 368832785Speter checked out? 368932785Speter 369032785Speter Yes and Yes. 369132785Speter 369232785Speter The ./CVS/Repository file in each working directory contains a 369332785Speter pathname pointing to the matching directory within the Repository. The 369432785Speter pathname is either absolute or relative to $CVSROOT, depending on how 369532785Speter you configured CVS. 369632785Speter 369732785Speter When you move a checked-out directory, the CVS administrative files 369832785Speter will move along with it. As long as you don't move the Repository 369932785Speter itself, or alter your $CVSROOT variable, the moved directory will 370032785Speter continue to be usable. 370132785Speter 370232785Speter CVS remembers where you checked out the directory in the "history" 370332785Speter file, which can be edited, or even ignored if you don't use the 370432785Speter "working directory" information displayed by the "history" command. 370532785Speter 370632785Speter Last modified: _6/13/1997_ 370732785Speter 370832785Speter 8. How can I lock files while I'm working on them the way RCS does? 370932785Speter 371032785Speter Until the day arrives of the all-powerful merge tool, there are still 371132785Speter files that must be accessed serially. For those instances, here's a 371232785Speter potential solution: 371332785Speter 371432785Speter Install a pre-commit program in the "commitinfo" file to check for 371532785Speter RCS locks. The program "rcslock.pl" performs this function. It can be 371632785Speter found in the contrib directory of the CVS source distribution. 371732785Speter 371832785Speter When you want to make a change to a file you know can't be merged, 371932785Speter first use "cvs admin -l" to lock the file. If you can't acquire the 372032785Speter lock, use the standard "locked out" protocol: go talk to the person 372132785Speter holding the lock. 372232785Speter 372332785Speter Make sure the pre-commit program prints a message and exits with a 372432785Speter non-zero status if someone besides the user running "commit" has the 372532785Speter file locked. This non-zero exist status will cause the "commit" to 372632785Speter fail cleanly. 372732785Speter 372832785Speter Make sure the pre-commit program exits with a zero status if the 372932785Speter file is either unlocked or locked by the user running "commit". The 373032785Speter "cvs commit" command that kicked off the pre-commit program will take 373132785Speter a zero exist status as an OK and checkin the file, which has the 373232785Speter side-effect of unlocking it. 373332785Speter 373432785Speter ===> The following is opinion and context. Don't read it if you are 373532785Speter looking for a quick fix. 373632785Speter 373732785Speter The topic of locking CVS files resurfaces on the network every so 373832785Speter often, producing the same results each time: 373932785Speter 374032785Speter The Big Endians: 374132785Speter 374232785Speter CVS was designed to avoid locks, using a copy-modify-merge model. 374332785Speter Locking is not necessary and you should take the time to learn the CVS 374432785Speter model which many people find workable. So why not get with the program 374532785Speter and learn how to think the CVS way? 374632785Speter 374732785Speter The Little Endians: 374832785Speter 374932785Speter The users determine how a tool is to be used, not the designers. We, 375032785Speter the users, have always used locking, our bosses demand locking, 375132785Speter locking is good, locking is God. I don't want to hear any more 375232785Speter lectures on the CVS model. Make locking work. 375332785Speter 375432785Speter Any organization making active changes to a source base will 375532785Speter eventually face the need to do parallel development. Parallel 375632785Speter development implies merges. (If you plan to keep separate copies of 375732785Speter everything and never merge, good luck. Tell me who you work for so I 375832785Speter can buy stock in your disk suppliers this year and sell your stock 375932785Speter short next year.) 376032785Speter 376132785Speter Merges will never go away. CVS chose to make "merges" stand front and 376232785Speter center as an important, common occurrence in development. It is one 376332785Speter way of looking at things. 376432785Speter 376532785Speter For free-format text, the merge paradigm gives you a considerable 376632785Speter amount of freedom. It does take a bit of management, but any project 376732785Speter should be ready to deal with it. 376832785Speter 376932785Speter On the other hand, there are many files that can't be merged using 377032785Speter text merge techniques. Straight text merge programs like "diff3" are 377132785Speter guaranteed to fail on executables (with relative branch statements), 377232785Speter files with self-referential counts stored in the file (such as TAGS 377332785Speter files), or files with relative motion statements in them (such as 377432785Speter Frame MIF files, many postscript files). They aren't all binary files. 377532785Speter 377632785Speter For these types of files, and many others, there are only two 377732785Speter solutions: 377832785Speter 377932785Speter Complex merge tools that are intimately aware of the contents of the 378032785Speter files to be merged. (ClearCase, and probably others, allow you to 378132785Speter define your own "files types" with associated "merge tools".) 378232785Speter 378332785Speter Serialization of access to the file. The only technical solution to 378432785Speter the problem of serialization is "locking". 378532785Speter 378632785Speter Since you can call a program that offers: 378732785Speter 378832785Speter "Which one do you want? A/B?" 378932785Speter 379032785Speter a "merge tool", more and more merge tools will appear which can be 379132785Speter hooked into a merge-intensive program like CVS. Think of a bitmap 379232785Speter "merge" tool that displays the bitmaps on the screen and offers a 379332785Speter "paint" interface to allow you to cut and paste, overlay, invert or 379432785Speter fuse the two images such that the result is a "merged" file. 379532785Speter 379632785Speter My conclusion is that the need for locking is temporary, awaiting 379732785Speter better technology. For large development groups, locking is not an 379832785Speter alternative to merging for text files. 379932785Speter 380032785Speter Last modified: _6/13/1997_ 380132785Speter 380232785Speter 9. What is "checkout -s"? How is it different from "checkout -c"? 380332785Speter 380432785Speter The '-c' and '-s' options to "checkout" both cause the modules file to 380532785Speter appear on standard output, but formatted differently. 380632785Speter 380732785Speter "checkout -c" lists the modules file alphabetized by the module name. 380832785Speter It also prints all data (including options like '-a' and "-o <prog>") 380932785Speter specified in the modules file. 381032785Speter 381132785Speter "checkout -s" lists the modules file sorted by "status" field, then by 381232785Speter module name. The status field was intended to allow you to mark 381332785Speter modules with strings of your choice to get a quick sorted report based 381432785Speter on the data you chose to put in the status fields. I have used it for 381532785Speter priority ("Showstopper", etc as tied into a bug database), for porting 381632785Speter status ("Ported", "Compiled", etc. when porting a large collection of 381732785Speter modules), for "assignee" (the person responsible for maintenance), and 381832785Speter for "test suite" (which automatic test procedure to run for a 381932785Speter particular module). 382032785Speter 382132785Speter Last modified: _6/13/1997_ 382232785Speter 382332785Speter Category: /Commands_/commit_ci_com/ 382432785Speter 382532785Speter " + "commit", "ci", "com"" 382632785Speter 382732785Speter 1. What is "commit" for? 382832785Speter 382932785Speter To store new revisions in the Repository, making them visible to other 383032785Speter users. 383132785Speter 383232785Speter Last modified: _6/13/1997_ 383332785Speter 383432785Speter 2. If I edit ten files, do I have to type "commit" ten times? 383532785Speter 383632785Speter No. The "commit" command will take multiple filenames, directory names 383732785Speter and relative pathnames on the command line and commit them all with 383832785Speter the same log message. If a file is unchanged, even if it is explicitly 383932785Speter listed on the command line, CVS will skip it. 384032785Speter 384132785Speter Like all CVS commands, "commit" will work on the whole directory by 384232785Speter default. Just type "cvs commit" to tell CVS to commit all modified 384332785Speter files (i.e. the files that "update" would display preceded by 'M') in 384432785Speter the current directory and in all sub-directories. 384532785Speter 384632785Speter Last modified: _6/13/1997_ 384732785Speter 384832785Speter 3. Explain: cvs commit: Up-to-date check failed for `<file>' 384932785Speter 385032785Speter You may not "commit" a file if your BASE revision (i.e. the revision 385132785Speter you last checked out, committed or retrieved via "update") doesn't 385232785Speter match the HEAD revision (i.e the latest revision on your branch, 385332785Speter usually the Main Branch). 385432785Speter 385532785Speter In other words, someone committed a revision since you last executed 385632785Speter "checkout", "update" or "commit". You must now execute "update" to 385732785Speter merge the other person's changes into your working file before 385832785Speter "commit" will work. You are thus protected (somewhat) from a common 385932785Speter form of race condition in source control systems, where a checkin of a 386032785Speter minor alteration of a second copy of the same base file obliterates 386132785Speter the changes made in the first. 386232785Speter 386332785Speter Normally, the "update" command's auto-merge should be followed by 386432785Speter another round of building and testing before the "commit". 386532785Speter 386632785Speter Last modified: _6/13/1997_ 386732785Speter 386832785Speter 4. What happens if two people try to "commit" conflicting changes? 386932785Speter 387032785Speter Conflicts can occur only when two developers check out the same 387132785Speter revision of the same file and make changes. The first developer to 387232785Speter commit the file has no chance of seeing the conflict. Only the second 387332785Speter developer runs into it, usually when faced with the "Up-to-date" error 387432785Speter explained in the previous question. 387532785Speter 387632785Speter There are two types of conflicts: 387732785Speter 387832785Speter When two developers make changes to the same section of code, the 387932785Speter auto-merge caused by "update" will print a 'C' on your terminal and 388032785Speter leave "overlap" markers in the file. 388132785Speter 388232785Speter You are expected to examine and clean them up before committing the 388332785Speter file. (That may be obvious to *some* of you, but . . .) 388432785Speter 388532785Speter A more difficult problem arises when two developers change different 388632785Speter sections of code, but make calls to, or somehow depend on, the old 388732785Speter version of each other's code. 388832785Speter 388932785Speter The auto-merge does the "right" thing, if you view the file as a 389032785Speter series of text lines. But as a program, the two developers have 389132785Speter created a problem for themselves. 389232785Speter 389332785Speter This is no different from making cross-referential changes in 389432785Speter *separate* files. CVS can't help you. In a perfect world, you would 389532785Speter each refer to the specification and resolve it independently. In the 389632785Speter real world you have to talk/argue, read code, test and debug until the 389732785Speter combined changes work again. 389832785Speter 389932785Speter Welcome to the world of parallel development. 390032785Speter 390132785Speter Last modified: _6/13/1997_ 390232785Speter 390332785Speter 5. I committed something and I don't like it. How do I remove it? 390432785Speter 390532785Speter Though you *can* use the "admin -o" (synonym: "rcs -o") command to 390632785Speter delete revisions, unless the file you committed is so embarrassing 390732785Speter that the need to eradicate it overrides the need to be careful, you 390832785Speter should just grab an old version of the file ("update -p -r 390932785Speter <previous-rev>" might help here) and commit it on top of the offending 391032785Speter revision. 391132785Speter 391232785Speter See Section 3B on "admin". 391332785Speter 391432785Speter Last modified: _6/13/1997_ 391532785Speter 391632785Speter 6. Explain: cvs commit: sticky tag `V3' for file `X' is not a branch 391732785Speter 391832785Speter The message implies two things: 391932785Speter 392032785Speter You created your working directory by using "checkout -r V3", or you 392132785Speter recently executed "update -r V3". 392232785Speter 392332785Speter The tag named V3 is not a branch tag. 392432785Speter 392532785Speter CVS records (i.e. makes "sticky") any "-r <tag/rev>" argument handed 392632785Speter to the "checkout" or "update" commands. The <tag/rev> is recorded as 392732785Speter the CVS working branch, which is the branch to which "commit" will add 392832785Speter a new revision. 392932785Speter 393032785Speter Branch tags are created when you use the -b switch on the "tag" or 393132785Speter "rtag" commands. Branch tags are magic tags that don't create a 393232785Speter physical branch, but merely mark the revision to branch from when the 393332785Speter branch is needed. The first commit to a magic branch creates a 393432785Speter physical branch in the RCS files. 393532785Speter 393632785Speter You can commit onto the end of the Main Trunk, if you have no sticky 393732785Speter tag at all, or onto the end of a branch, if you have a sticky branch 393832785Speter tag. But you can't commit a file that has a sticky tag not pointing to 393932785Speter a branch. CVS assumes a sticky Tag or Revision that does not refer to 394032785Speter a branch is attached to the middle of a series of revisions. You can't 394132785Speter squeeze a new revision between two others. Sticky dates also block 394232785Speter commits since they never refer to a branch. 394332785Speter 394432785Speter Scenario1: 394532785Speter 394632785Speter If you don't want a branch and were just looking at an old revision, 394732785Speter then you can move back to the Main Branch by typing: 394832785Speter 394932785Speter cvs update -A {files or dirs, default is '.'} 395032785Speter 395132785Speter or you can move to the branch named <branch_tag> by: 395232785Speter 395332785Speter cvs update -r <branch_tag> {files or dirs, default is '.'} 395432785Speter 395532785Speter Scenario2: 395632785Speter 395732785Speter If you really wanted to be on a branch and made an earlier mistake by 395832785Speter tagging your branch point with a non-branch tag, you can recover by 395932785Speter adding a new branch tag to the old non-branch tag: 396032785Speter 396132785Speter cvs rtag -b -r <oldtag> <newtag> <module> 396232785Speter 396332785Speter (It was not a big mistake. Branch-point tags can be useful. But the 396432785Speter <newtag> must have a different name.) 396532785Speter 396632785Speter If you don't know the <module> name or don't use "modules", you can 396732785Speter also use "tag" this way: 396832785Speter 396932785Speter cvs update -r <oldtag> 397032785Speter cvs tag -b <newtag> . 397132785Speter 397232785Speter Then, to put your working directory onto the branch, you type: 397332785Speter 397432785Speter cvs update -r <newtag> 397532785Speter 397632785Speter You can't delete <oldtag> before adding <newtag>, and I would not 397732785Speter advise deleting the <oldtag> at all, because it is useful in referring 397832785Speter to the branch point. If you must, you can delete the non-branch tag 397932785Speter by: 398032785Speter 398132785Speter cvs rtag -d <oldtag> <module> 398232785Speter or 398332785Speter cvs tag -d <oldtag> . 398432785Speter 398532785Speter Scenario3: 398632785Speter 398732785Speter If you made the same mistake as in Scenario2 (of placing a non-branch 398832785Speter tag where you wanted a branch tag), but really want <oldtag> to be the 398932785Speter name of your branch, you can execute a slightly different series of 399032785Speter commands to rename it and move your working directory onto the branch. 399132785Speter 399232785Speter Warning: This is not a way to rename a branch tag. It is a way to turn 399332785Speter a non-branch tag into a branch tag with the same name. 399432785Speter 399532785Speter cvs rtag -r <oldtag> <branch_point_tag> <module> 399632785Speter cvs rtag -d <oldtag> <module> 399732785Speter cvs rtag -b -r <branch_point_tag> <oldtag> <module> 399832785Speter 399932785Speter Then, if you really must, delete the <branch_point_tag>: 400032785Speter 400132785Speter cvs rtag -d <branch_point_tag> <module> 400232785Speter 400332785Speter Note: The unwieldy mixture of "tag" and "rtag" is mostly because you 400432785Speter can't specify a revision (-r <tag>) to the "tag" command. 400532785Speter 400632785Speter See 4C.3 for more info on creating a branch. 400732785Speter 400832785Speter Last modified: _6/13/1997_ 400932785Speter 401032785Speter 7. Why does "commit -r <tag/rev>" put newly added files in the Attic? 401132785Speter 401232785Speter If you specify "-r <rev>" (where <rev> is a dotted numeric number like 401332785Speter 2.4), it correctly sets the initial revision to <rev>, but it also 401432785Speter attaches the numeric <rev> as a sticky tag and throws the file into 401532785Speter the Attic. This is a bug. The obvious solution is to move the file out 401632785Speter of the Attic into the associated Repository directory and "update -A" 401732785Speter the file. There are no Tags to clean up. 401832785Speter 401932785Speter If you specify "-r <tag>" to commit a newly added file, the <tag> is 402032785Speter treated like a <branch_tag>, which becomes a symbolic RCS label 402132785Speter pointing to the string '1', which can be considered to be the "Main 402232785Speter branch number" when the main branch is still at revision 1.N. The file 402332785Speter is also thrown into the Attic. See 4C.8 for a way to recover from 402432785Speter this. 402532785Speter 402632785Speter In fact, a plain "commit" without the "-r" will throw a newly added 402732785Speter file into the Attic if you added it to a directory checked out on a 402832785Speter branch. See 3A.[2-5]. 402932785Speter 403032785Speter See Section 4C, on Branching, for many more details. 403132785Speter 403232785Speter Last modified: _6/13/1997_ 403332785Speter 403432785Speter 8. Why would a "commit" of a newly added file not produce rev 1.1? 403532785Speter 403632785Speter When committing a newly added file CVS looks for the highest main 403732785Speter branch major number in all files in the ./CVS/Entries file. Normally 403832785Speter it is '1', but if you have a file of revision 3.27 in your directory, 403932785Speter CVS will find the '3' and create revision 3.1 for the first rev of 404032785Speter <file>. Normally, the first revision is 1.1. 404132785Speter 404232785Speter Last modified: _6/13/1997_ 404332785Speter 404432785Speter Category: /Commands_/diff_di_dif/ 404532785Speter 404632785Speter " + "diff", "di", "dif"" 404732785Speter 404832785Speter 1. What is "diff" for? 404932785Speter 405032785Speter To display the difference between a working file and its BASE 405132785Speter revision (the revision last checked out, updated or committed): 405232785Speter 405332785Speter cvs diff <file> 405432785Speter 405532785Speter To display the difference between a working file and a committed 405632785Speter revision of the same file: 405732785Speter 405832785Speter cvs diff -r <tag/rev> <file> 405932785Speter 406032785Speter To display the difference between two committed revisions of the 406132785Speter same file: 406232785Speter 406332785Speter cvs diff -r <tag1/rev1> -r <tag2/rev2> <file> 406432785Speter 406532785Speter You can specify any number of <file> arguments. Without any <file> 406632785Speter arguments, it compares the whole directory. 406732785Speter 406832785Speter In the examples above, "-D <date>" may be substituted wherever "-r 406932785Speter <tag/rev>" appears. The revision a <date> refers to is the revision 407032785Speter that existed on that date. 407132785Speter 407232785Speter Last modified: _6/13/1997_ 407332785Speter 407432785Speter 2. Why did "diff" display nothing when I know there are later committed 407532785Speter revisions in the Repository? 407632785Speter 407732785Speter By default, "diff" displays the difference between your working file 407832785Speter and the BASE revision. If you haven't made any changes to the file 407932785Speter since your last "checkout", "update" or "commit" there is no 408032785Speter difference to display. 408132785Speter 408232785Speter To display the difference between your working file and the latest 408332785Speter revision committed to your current branch, type: 408432785Speter 408532785Speter cvs diff -r HEAD <file> 408632785Speter 408732785Speter Last modified: _6/13/1997_ 408832785Speter 408932785Speter 3. How do I display what changed in the Repository since I last executed 409032785Speter "checkout", "update" or "commit"? 409132785Speter 409232785Speter A special tag (interpreted by CVS -- it does not appear in the Tag 409332785Speter list) named "BASE" always refers to the revision you last checked out, 409432785Speter updated or committed. Another special tag named "HEAD" always refers 409532785Speter to the latest revision on your working branch. 409632785Speter 409732785Speter To compare BASE and HEAD, you type: 409832785Speter 409932785Speter cvs diff -r BASE -r HEAD <file> 410032785Speter 410132785Speter Last modified: _6/13/1997_ 410232785Speter 410332785Speter 4. How do I display the difference between my working file and what I 410432785Speter checked in last Thursday? 410532785Speter 410632785Speter cvs diff -D "last Thursday" <file> 410732785Speter 410832785Speter where "last Thursday" is a date string. To be more precise, the 410932785Speter argument to the '-D' option is a timestamp. Many formats are accepted. 411032785Speter See the man page under "-D date_spec" for details. 411132785Speter 411232785Speter Last modified: _6/13/1997_ 411332785Speter 411432785Speter 5. Why can't I pass long options, like --unified, to "diff"? 411532785Speter 411632785Speter CVS only handles single character '-X' arguments, not the FSF long 411732785Speter options. CVS also passes through only arguments it knows about, 411832785Speter because a few arguments are captured and interpreted by CVS. 411932785Speter 412032785Speter If you didn't configure RCS and CVS to use the GNU version of diff, 412132785Speter long options wouldn't work even if future versions of CVS acquire the 412232785Speter ability to pass them through. 412332785Speter 412432785Speter Most of the long options have equivalent single-character options, 412532785Speter which do work. The "--unified" option is equivalent to '-u' in 412632785Speter revisions of GNU diff since 1.15. 412732785Speter 412832785Speter Last modified: _6/13/1997_ 412932785Speter 413032785Speter Category: /Commands_/export_exp_ex/ 413132785Speter 413232785Speter " + "export", "exp", "ex"" 413332785Speter 413432785Speter 1. What is "export" for? 413532785Speter 413632785Speter "export" checks out a copy of a module in a form intended for export 413732785Speter outside the CVS environment. The "export" command produces the same 413832785Speter directory and file structure as the "checkout" command, but it doesn't 413932785Speter create "CVS" sub-directories and it removes all the RCS keywords from 414032785Speter the files. 414132785Speter 414232785Speter Last modified: _6/13/1997_ 414332785Speter 414432785Speter 2. Why does it remove the RCS keywords so I can't use the "ident" command 414532785Speter on the source files? 414632785Speter 414732785Speter It removes the RCS keywords, so that if the recipient of the exported 414832785Speter sources checks them into another set of RCS files (with or without 414932785Speter CVS), and then makes modifications through RCS or CVS commands, the 415032785Speter revision numbers that they had when you exported them will be 415132785Speter preserved. (That ident no longer works is just an unfortunate side 415232785Speter effect.) 415332785Speter 415432785Speter The theory is that you are exporting the sources to someone else who 415532785Speter will make independent changes, and at some point you or they will want 415632785Speter to know what revisions from your Repository they started with 415732785Speter (probably to merge changes, or to try to decide whether to merge 415832785Speter changes). 415932785Speter 416032785Speter A better way to handle this situation would be to give them their own 416132785Speter branch of your Repository. They would need to remember to checkin the 416232785Speter exported sources with RCS IDs intact (ci -k) so that their changes 416332785Speter would get revision numbers from the branch, rather than starting at 416432785Speter 1.1 again. Perhaps a future version of CVS will provide a way to 416532785Speter export sources this way. 416632785Speter 416732785Speter Contributed by Dan Franklin 416832785Speter 416932785Speter Last modified: _6/13/1997_ 417032785Speter 417132785Speter 3. Can I override the '-kv' flag CVS passes to RCS? 417232785Speter 417332785Speter Not as of CVS version 1.4. 417432785Speter 417532785Speter Last modified: _6/13/1997_ 417632785Speter 417732785Speter 4. Why doesn't "export" have a '-k' flag like "import" does? 417832785Speter 417932785Speter Export is intended for a specific purpose -- to remove all trace of 418032785Speter revision control on the way *out* of CVS. 418132785Speter 418232785Speter Last modified: _6/13/1997_ 418332785Speter 418432785Speter 5. Why does "export -D" check out every file in the Attic? 418532785Speter 418632785Speter See 5B.3 for an explanation of the same problem with "update". 418732785Speter 418832785Speter Last modified: _6/13/1997_ 418932785Speter 419032785Speter Category: /Commands_/history_hi_his/ 419132785Speter 419232785Speter " + "history", "hi", "his"" 419332785Speter 419432785Speter 1. What is "history" for? 419532785Speter 419632785Speter To provide information difficult or impossible to extract out of the 419732785Speter RCS files, such as a "tag" history or a summary of module activities. 419832785Speter 419932785Speter Last modified: _6/13/1997_ 420032785Speter 420132785Speter 2. Of what use is it? 420232785Speter 420332785Speter I have found it useful in a number of ways, including: 420432785Speter 420532785Speter Providing a list of files changed since 420632785Speter 420732785Speter - A tagged release. 420832785Speter - Yesterday, last Thursday, or a specific date. 420932785Speter - Someone changed a specific file. 421032785Speter 421132785Speter Providing a list of special events: 421232785Speter 421332785Speter - Files added or removed since one of the above events. 421432785Speter - Merge failures since one of the above events. (Where did the 421532785Speter conflicts occur?) 421632785Speter - Has anyone (and who) grabbed the revision of this file I committed 421732785Speter last week, or are they still working blind? 421832785Speter 421932785Speter Telling me how often a file/directory/module has been changed. 422032785Speter 422132785Speter Dumping a summary of work done on a particular module, including who 422232785Speter last worked on it and what changed. 422332785Speter 422432785Speter Displaying the checked-out modules and where they are being worked 422532785Speter on. 422632785Speter 422732785Speter To tell me what users "joe" and "malcolm" have done this week. 422832785Speter 422932785Speter Last modified: _6/13/1997_ 423032785Speter 423132785Speter 3. What is this, Big Brother? 423232785Speter 423332785Speter War is Peace. 423432785Speter Freedom is Slavery. 423532785Speter Ignorance is Strength. 423632785Speter 423732785Speter Normally manager types and those with the power to play Big Brother 423832785Speter don't care about this information. The Software Engineer responsible 423932785Speter for integration usually wants to know who is working on what and what 424032785Speter changed. Use your imagination. 424132785Speter 424232785Speter Last modified: _6/13/1997_ 424332785Speter 424432785Speter 4. I deleted my working directory and "history" still says I have it 424532785Speter checked out. How do I fix it? 424632785Speter 424732785Speter You can use "release -f" to forcibly add a "release" record to the 424832785Speter history file for a working directory associated with a "module". If 424932785Speter your version of "release" doesn't have the '-f' option, or you checked 425032785Speter out the directory using a relative path, you have to edit the 425132785Speter $CVSROOT/CVSROOT/history file. 425232785Speter 425332785Speter You can remove the last 'O' line in the history file referring to the 425432785Speter module in question or add an 'F' record. 425532785Speter 425632785Speter Last modified: _6/13/1997_ 425732785Speter 425832785Speter 5. So I *can* edit the History file? 425932785Speter 426032785Speter Yes, but if you are using history at all, you should take a little 426132785Speter care not to lose information. I normally use Emacs on the file, since 426232785Speter it can detect that a file has changed out from under it. You could 426332785Speter also copy and zero out the history file, edit the copy and append any 426432785Speter new records to the edited copy before replacing it. 426532785Speter 426632785Speter Last modified: _6/13/1997_ 426732785Speter 426832785Speter 6. Why does the history file grow so quickly? 426932785Speter 427032785Speter It stores 'U' records, which come in handy sometimes when you are 427132785Speter tracking whether people have updated each other's code before testing. 427232785Speter There should (and probably will sometime) be a way to choose what 427332785Speter kinds of events go into the history file. 427432785Speter 427532785Speter The contributed "cln_hist.pl" script will remove all the 'U' records, 427632785Speter plus matching pairs of 'O' and 'F' records during your normal clean up 427732785Speter of the history file. 427832785Speter 427932785Speter Last modified: _6/13/1997_ 428032785Speter 428132785Speter 7. What is the difference between "cvs history -r <tag/rev>" and "cvs 428232785Speter history -t <tag>"? 428332785Speter 428432785Speter The '-t' option looks for a Tag record stored by "rtag" in the history 428532785Speter file and limits the search to dates after the last <tag> of the given 428632785Speter name was added. 428732785Speter 428832785Speter The '-r' option was intended to search all files looking for the <tag> 428932785Speter in the RCS files. It takes forever and needs to be rewritten. 429032785Speter 429132785Speter Last modified: _6/13/1997_ 429232785Speter 429332785Speter 8. Why does "cvs history -c -t <tag>" fail to print anything? 429432785Speter 429532785Speter You have been using "tag" instead of "rtag". The "tag" command 429632785Speter currently doesn't store a history record. This is another remnant of 429732785Speter CVS's earlier firm belief in "modules". But it also has a basis in how 429832785Speter "rtag" and "tag" were originally used. 429932785Speter 430032785Speter "rtag" was intended for large-scale tagging of large chunks of the 430132785Speter Repository, an event work recording. "tag" was intended for adding and 430232785Speter updating tags on a few files or directories, though it could also be 430332785Speter used to tag the entire checked-out working tree when there is no 430432785Speter module defined to match the tree or when the working tree is the only 430532785Speter place where the right collection of revisions to tag can be found. 430632785Speter 430732785Speter Last modified: _6/13/1997_ 430832785Speter 430932785Speter 9. "cvs history -a -o" only printed one line for each checked-out module. 431032785Speter Shouldn't it print all the directories where the modules are checked out? 431132785Speter 431232785Speter Not as designed. 431332785Speter 431432785Speter Command Question it is supposed to answer. 431532785Speter ---------------- ------------------------------------------ 431632785Speter cvs history -o What modules do I have checked out? 431732785Speter cvs history -a -o <same for all users> 431832785Speter 431932785Speter cvs history -o -w What working directories have I created 432032785Speter and what modules are in them? 432132785Speter cvs history -a -o -w <same for every user> 432232785Speter 432332785Speter The -o option chooses the "checked out modules" report, which is the 432432785Speter default history report. 432532785Speter 432632785Speter Last modified: _6/13/1997_ 432732785Speter 432832785Speter 10. I can't figure out "history", can you give me concrete examples? 432932785Speter 433032785Speter Default output selects records only for the user who executes the 433132785Speter "history" command. To see records for other users, add one or more "-u 433232785Speter user" options or the '-a' option to select *all* users. 433332785Speter 433432785Speter To list (for the selected users): Type "cvs history" and: 433532785Speter 433632785Speter * Checked out modules: -o (the default) 433732785Speter * Files added since creation: -x A 433832785Speter * Modified files since creation: -c 433932785Speter * Modified files since last Friday: -c -D 'last Friday' 434032785Speter * Modified files since TAG was added: -c -t <tag> 434132785Speter * Modified files since TAG on files: -c -r <tag> 434232785Speter * Last modifier of file/Repository X? -c -l -[fp] X 434332785Speter * Modified files since string "str": -c -b str 434432785Speter * Tag history: (Actually "rtag".) -T 434532785Speter * History of file/Repository/module X: -[fpn] X 434632785Speter * Module report on "module": -m module 434732785Speter 434832785Speter Last modified: _6/13/1997_ 434932785Speter 435032785Speter 11. Can we merge history files when we merge Repositories? 435132785Speter 435232785Speter Assuming that the two Repositories have different sets of pathnames, 435332785Speter it should be possible to merge two history files by sorting them 435432785Speter together by the timestamp fields. 435532785Speter 435632785Speter You should be able to run: 435732785Speter 4358128266Speter sort -k 1.2 ${dir1}/history ${dir2}/history > history 435932785Speter 436032785Speter If you "diff" a standard history file before and after such a sort, 436132785Speter you might see other differences caused by garbage (split lines, nulls, 436232785Speter etc) in the file. If your Repository is mounted through NFS onto 436332785Speter multiple machines you will also see a few differences caused by 436432785Speter different clocks on different machines. (Especially if you don't use 436532785Speter NTP to keep the clocks in sync.) 436632785Speter 436732785Speter Last modified: _6/13/1997_ 436832785Speter 436932785Speter Category: /Commands_/import_im_imp/ 437032785Speter 437132785Speter " + "import", "im", "imp"" 437232785Speter 437332785Speter 1. What is "import" for? 437432785Speter 437532785Speter The "import" command is a fast way to insert a whole tree of files 437632785Speter into CVS. 437732785Speter 437832785Speter The first "import" to a particular file within the Repository creates 437932785Speter an RCS file with a single revision on the "Vendor branch." Subsequent 438032785Speter "import"s of the same file within the Repository append a new revision 438132785Speter onto the Vendor branch. It does not, as some seem to believe, create a 438232785Speter new branch for each "import". All "imports" are appended to the single 438332785Speter Vendor branch. 438432785Speter 438532785Speter If the file hasn't changed, no new revision is created -- the new 438632785Speter "Release-Tag" is added to the previous revision. 438732785Speter 438832785Speter After the import is finished, files you have not changed locally are 438932785Speter considered to have changed in the "Main line of development". Files 439032785Speter you *have* changed locally must have the new Vendor code merged into 439132785Speter them before they are visible on the "Main line". 439232785Speter 439332785Speter See 4C.6 and 4C.15 439432785Speter 439532785Speter Last modified: _6/13/1997_ 439632785Speter 439732785Speter 2. How am I supposed to use "import"? 439832785Speter 439932785Speter Create a source directory containing only the files you want to 440032785Speter import. Make sure you clean up any cruft left over from previous 440132785Speter builds or editing. You want to make sure that the directory contains 440232785Speter only what you want to call "source" from which everything else is 440332785Speter built. 440432785Speter 440532785Speter If this is not the first import from this "Vendor", you should also 440632785Speter compare the output of "find . ! -name CVS -print | sort" executed both 440732785Speter at the head of a checked out working directory and at the head of the 440832785Speter sources to be imported. If you find any deleted or renamed files, you 440932785Speter have to deal with them by hand. (See 4B.8 on renaming.) 441032785Speter 441132785Speter "cd" into your source directory and type: 441232785Speter 441332785Speter cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag> 441432785Speter 441532785Speter where <repos> is the relative directory pathname within the Repository 441632785Speter that corresponds to the sources you are importing. 441732785Speter 441832785Speter You might also consider using the "-I !" option to avoid ignoring 441932785Speter anything. It is easier to remove bogus files from the Repository than 442032785Speter to create a sparse tree of the ignored files and rerun "import". 442132785Speter 442232785Speter For example, if the FSF, CVS, Make and I are still active in the year 442332785Speter 2015, I'll import version 89.53 of GNU make this way: 442432785Speter 442532785Speter cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53 442632785Speter 442732785Speter See 3H.13 for more details. 442832785Speter 442932785Speter Last modified: _6/13/1997_ 443032785Speter 443132785Speter 3. Why does import put files on a branch? Why can't I work on the main 443232785Speter trunk instead of a Vendor branch? 443332785Speter 443432785Speter This was a Design choice. The Vendor branch is the way "import" deals 443532785Speter with a Vendor release. It is a solution to the Engineering problem of 443632785Speter how to merge multiple external releases of Vendor-supplied sources 443732785Speter into your ongoing work. The Vendor releases are kept on a separate, 443832785Speter special, "Vendor" branch and your work is kept on the RCS trunk. New 443932785Speter Vendor releases are imported onto the Vendor branch and then merged 444032785Speter into your work, if there is any, on the trunk. 444132785Speter 444232785Speter This way, you can use CVS to find out not only about your work, but 444332785Speter you can also find out what the Vendor changed by diffing between two 444432785Speter of the Release Tags you handed to "import". 444532785Speter 444632785Speter CVS was designed to work this way. If you use CVS in some other way, 444732785Speter you should think carefully about what you are doing. 444832785Speter 444932785Speter Note that the CVS "Main Branch" and the RCS Main Trunk are not the 445032785Speter same. Placing files on the Vendor Branch doesn't keep you from 445132785Speter creating a development branch to work on. 445232785Speter 445332785Speter See Section 4C, on Branching. 445432785Speter 445532785Speter If you are not working with 3rd party (i.e. Vendor) sources, you can 445632785Speter skip the "import" and avoid the Vendor branch entirely. It works just 445732785Speter as well to move pre-existing RCS files into Repository directories. 445832785Speter 445932785Speter You can create a whole Repository tree by copying a directory 446032785Speter hierarchy of normal source files directly into the Repository and 446132785Speter applying CVS to it. Here's an idea you should *test* before using: 446232785Speter 446332785Speter cd <your source tree> 446432785Speter set source = `pwd` 446532785Speter set module = xyzzy <<== Your choice of directory name 446632785Speter mkdir $CVSROOT/$module 446732785Speter cd $CVSROOT/$module 446832785Speter (cd $source; tar cf - .) | tar xvpBf - 446932785Speter find . -type f -exec ci -t-Original. {} \; 447032785Speter 447132785Speter The RCS "ci" command, without -u or -l options, will turn your source 447232785Speter file into an RCS (",v") and delete the original source. 447332785Speter 447432785Speter Last modified: _6/13/1997_ 447532785Speter 447632785Speter 4. Is there any way to import binary files? 447732785Speter 447832785Speter If you configured CVS to use the GNU version of "diff" and "diff3", 447932785Speter then you can import any kind of file. 448032785Speter 448132785Speter Binary files with RCS keywords in them are a problem, since you don't 448232785Speter want them to expand. 448332785Speter 448432785Speter If the tree you are about to "import" is entirely filled with binary 448532785Speter files, you can use the '-ko' option on "import". Otherwise, I would 448632785Speter run the import normally, then fix the binary files as described below 448732785Speter in 3H.5. 448832785Speter 448932785Speter See 4D.1 on Binary files. 449032785Speter 449132785Speter Last modified: _6/13/1997_ 449232785Speter 449332785Speter 5. Why does "import" corrupt some binary files? 449432785Speter 449532785Speter The RCS "co" command, when it is invoked by a CVS "checkout" or 449632785Speter "update" (or after a "commit") command, searches for and expands a 449732785Speter list of keywords within the file. They are documented in the RCS "co" 449832785Speter man page. Strings such as "$\Id$" (or "$\Id:"), or "$\Revision$" (or 449932785Speter "$\Revision:") are altered to the include the indicated information. 450032785Speter 450132785Speter [[Note: The keywords should appear in the text without the '\' 450232785Speter character I have inserted to *avoid* expansion here. The only real RCS 450332785Speter keywords in this document are at the top of the file, where I store 450432785Speter the Revision and Date.]] 450532785Speter 450632785Speter If RCS keyword strings show up in a binary file, they will be altered 450732785Speter unless you set the '-ko' option on the RCS files to tell RCS to keep 450832785Speter the original keyword values and not to expand new ones. After 450932785Speter "import", you can set the '-ko' option this way: 451032785Speter 451132785Speter cvs admin -ko <file> 451232785Speter rm <file> 451332785Speter cvs update <file> 451432785Speter 451532785Speter After an import that didn't use '-ko' (because the whole tree wasn't 451632785Speter of binary files) you should fix up the binary files as described above 451732785Speter before checking out any new copies of the files and before updating 451832785Speter any working directories you checked out earlier. 451932785Speter 452032785Speter See 4D.1 on Binary files. 452132785Speter 452232785Speter Last modified: _6/13/1997_ 452332785Speter 452432785Speter 6. How do I retain the original $\Revision$ strings in the sources? 452532785Speter 452632785Speter If you want to leave old RCS keywords as they are, you can use the 452732785Speter '-ko' tricks described above. 452832785Speter 452932785Speter Last modified: _6/13/1997_ 453032785Speter 453132785Speter 7. I imported some files for the Yarg compiler that compiles files with a 453232785Speter suffix of ".yarg" and whose comment prefix is "YARG> ". When I check them 453332785Speter out, they will no longer compile because they have this junk in them. Why? 453432785Speter 453532785Speter YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG> 453632785Speter YARG> $\Log: 453732785Speter # Revision 1.3 1998/03/03 00:16:16 bubba 453832785Speter # What is 2+2 anyway? 453932785Speter # 454032785Speter # Revision 1.2 1998/03/03 00:15:15 bubba 454132785Speter # Added scorekeeping. 454232785Speter YARG> 454332785Speter YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG> 454432785Speter 454532785Speter Well bubba, "Yarg" hasn't hit the big time yet. Neither RCS nor CVS 454632785Speter know about your suffix or your comment prefix. So you have two 454732785Speter choices: 454832785Speter 454932785Speter Check out the Yarg-less module, and tell all the files about your 455032785Speter comment prefix. Visit each directory and type: 455132785Speter 455232785Speter cvs admin -c"YARG> " *.yarg 455332785Speter 455432785Speter If *all* files in the whole directory tree are Yarg files, you can use 455532785Speter this instead: 455632785Speter 455732785Speter cvs admin -c"YARG> " . 455832785Speter 455932785Speter Then save any changes you made, remove all the "*.yarg" files and grab 456032785Speter new copies from the Repository: 456132785Speter 456232785Speter rm *.yarg (or: find . -name '*.yarg' -exec rm {} ';') (or: find . 456332785Speter -name '*.yarg' -print | xargs rm) (or: find . -name '*.yarg' -print0 | 456432785Speter xargs -0 rm if you have spaces in filenames and the GNU find/xargs.) 456532785Speter cvs update 456632785Speter 456732785Speter It might be faster to remove the whole directory and check it out 456832785Speter again. 456932785Speter 457032785Speter Change the import.c file in the CVS sources and add the .yarg 457132785Speter suffix, along with the "YARG> " comment prefix to the "comtable" 457232785Speter array. 457332785Speter 457432785Speter If you ever plan to add new files with $\Log in them, you should also 457532785Speter go into the RCS sources and make the same change in the table 457632785Speter contained in the "rcsfnms.c" file. 457732785Speter 457832785Speter Then delete the imported files from the Repository and re-"import" the 457932785Speter sources. 458032785Speter 458132785Speter Last modified: _6/13/1997_ 458232785Speter 458332785Speter 8. How do I make "import" save the timestamps on the original files? 458432785Speter 458532785Speter Use "import -d" to save the current timestamps on the files as the RCS 458632785Speter revision times. 458732785Speter 458832785Speter See 4D.8 for another aspect of file timestamps. 458932785Speter 459032785Speter Last modified: _6/13/1997_ 459132785Speter 459232785Speter 9. Why can't I "import" 3 releases on different branches? 459332785Speter 459432785Speter I'll bet you typed something like this: 459532785Speter 459632785Speter cd /src/blasto.v2 459732785Speter cvs import -b 1.1.2 VENDOR2 Version2 459832785Speter cd /src/blasto.v3 459932785Speter cvs import -b 1.1.3 VENDOR3 Version3 460032785Speter cd /src/blasto.v4 460132785Speter cvs import -b 1.1.4 VENDOR4 Version4 460232785Speter 460332785Speter This is wrong, or at least it won't help you much. You have created 460432785Speter three separate Vendor branches, which is probably not what you wanted. 460532785Speter 460632785Speter Earlier versions of CVS, as described in Brian Berliner's Usenix 460732785Speter paper, tried to support multiple Vendor branches on the theory that 460832785Speter you might receive source for the *same* program from multiple vendors. 460932785Speter It turns out that this is very rare, whereas the need to branch in 461032785Speter *your* development, for releases and for project branches, is much 461132785Speter greater. 461232785Speter 461332785Speter So the model now is to use a single vendor branch to contain a series 461432785Speter of releases from the same vendor. Your work moves along on the Main 461532785Speter Trunk, or on a CVS branch to support a real "branch in development". 461632785Speter 461732785Speter To set this up, you should type this instead of the above: 461832785Speter 461932785Speter cd /src/blasto.v2 462032785Speter cvs import VENDOR Version2 462132785Speter cd /src/blasto.v3 462232785Speter cvs import VENDOR Version3 462332785Speter cd /src/blasto.v4 462432785Speter cvs import VENDOR Version4 462532785Speter 462632785Speter Last modified: _6/13/1997_ 462732785Speter 462832785Speter 10. What do I do if the Vendor adds or deletes files between releases? 462932785Speter 463032785Speter Added files show up with no extra effort. To handle "removed" files, 463132785Speter you should always compare the tree structure of the new release 463232785Speter against the one you have in your Repository. If the Vendor has removed 463332785Speter files since the previous release, go into a working directory 463432785Speter containing your current version of the sources and "cvs remove" 463532785Speter (followed by "cvs commit" to make it really take effect) each file 463632785Speter that is no longer in the latest release. 463732785Speter 463832785Speter Using this scheme will allow you to "checkout" any version of the 463932785Speter vendor's code, with the correct revisions and files, by using 464032785Speter "checkout -r Version[234]". 464132785Speter 464232785Speter Renames are harder to find, since you have to compare file contents to 464332785Speter determine that one has occurred. If you notice one, see 4B.8 on 464432785Speter renaming files. 464532785Speter 464632785Speter Last modified: _6/13/1997_ 464732785Speter 464832785Speter 11. What about if the Vendor changes the names of files or directories, or 464932785Speter rearranges the whole structure between releases? 465032785Speter 465132785Speter Currently CVS can't handle this cleanly. It requires "renaming" a 465232785Speter bunch of files or directories. 465332785Speter 465432785Speter See 4B.8 on "renaming" for more details. 465532785Speter 465632785Speter What I generally do is to close the Repository for a while and make 465732785Speter changes in both the Repository and in a copy of the vendor release 465832785Speter until the structure matches, then execute the import. 465932785Speter 466032785Speter If you ever have to check out and build an old version, you may have 466132785Speter to use the new, or completely different Makefiles. 466232785Speter 466332785Speter Last modified: _6/13/1997_ 466432785Speter 466532785Speter 12. I thought "import" was for Vendor releases, why would I use it for code 466632785Speter of my own? Do I have to use import? 466732785Speter 466832785Speter For code you produce yourself, "import" is a convenience for fast 466932785Speter insertion of whole trees. It is not necessary. You can just as easily 467032785Speter create ",v" files using the RCS "ci" command and move them directly 467132785Speter into the Repository. 467232785Speter 467332785Speter Other than the CVSROOT directory, the Repository consists entirely of 467432785Speter directories of ",v" files. The Repository contains no other state 467532785Speter information. 467632785Speter 467732785Speter See Section 4B, on Setting up and Managing the Repository. 467832785Speter 467932785Speter Last modified: _6/13/1997_ 468032785Speter 468132785Speter 13. How do I import a large Vendor release? 468232785Speter 468332785Speter When the sum of the changes made by the Vendor and the changes made by 468432785Speter local developers is small, "import" is not a big problem. But when you 468532785Speter are managing a large Repository, any care taken up front will save you 468632785Speter time later. 468732785Speter 468832785Speter First read the following, then, before executing "import", see the 468932785Speter questions in Section 4C dealing with branch merges and Vendor branch 469032785Speter merges. 469132785Speter 469232785Speter If this is not the first import of this code, before starting, rtag 469332785Speter the whole directory you will be changing. 469432785Speter 469532785Speter The first step is to make sure the structure of the new files 469632785Speter matches the structure of the current Repository. 469732785Speter 469832785Speter Run "find . -print | sort" on both trees and "diff" the output. 469932785Speter 470032785Speter Alter the "source" tree until the "diff" (of the list of filenames, 470132785Speter not of the whole trees) shows that the directory structures are 470232785Speter equivalent. 470332785Speter 470432785Speter The "comm" command, if you have it, can help figure out what has been 470532785Speter added or deleted between releases. 470632785Speter 470732785Speter If they deleted any files, you can handle them cleanly with "cvs 470832785Speter remove". The command "comm -23 files.old files.new" will show you a 470932785Speter list of files that need to be removed. 471032785Speter 471132785Speter You should examine the list first to see if any have been renamed 471232785Speter rather than simply deleted. 471332785Speter 471432785Speter If they renamed any files, see 4B.8 on renaming files. 471532785Speter 471632785Speter Remember to *SAVE* the output from the import command. 471732785Speter 471832785Speter When you have dealt with removed and renamed files, then you can 471932785Speter execute the import: 472032785Speter 472132785Speter cd <new source> 472232785Speter cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag> 472332785Speter 472432785Speter Where 472532785Speter 472632785Speter "-I !" is an optional argument that keeps "import" from ignoring 472732785Speter files. The comparison of the "find" commands above will probably avoid 472832785Speter the need for this, but it is easier to remove files from the 472932785Speter Repository than to run a subset "import" to catch just the ignored 473032785Speter files. [You might have to quote or backwhack the '!'.] 473132785Speter 473232785Speter Message is the log message to be stored in the RCS files. 473332785Speter 473432785Speter <repos> is a relative path to a directory within the 473532785Speter Repository. The directory <new source> must be at 473632785Speter the same relative level within the new sources as 473732785Speter the <repos> you give is within the Repository. (I 473832785Speter realize this is not obvious. Experiment first.) 473932785Speter 474032785Speter <VendorTag> is a Tag used to identify the Vendor who sent you 474132785Speter the files you are importing. All "imports" into 474232785Speter the same <repos> *must* use the same VendorTag. 474332785Speter You can find it later by using the "log" command. 474432785Speter 474532785Speter <ReleaseTag> is a Tag used to identify the particular release of the 474632785Speter software you are importing. It must be unique and should be mnemonic 474732785Speter -- at least include the revision number in it. (Note: you can't use 474832785Speter '.' characters in a Tag. Substitute '_' or '-'.) 474932785Speter 475032785Speter There will be six categories of files to deal with. (Actually there 475132785Speter are eight, but you have already dealt with "removed" and "renamed" 475232785Speter files.) 475332785Speter 475432785Speter If this is the first "import" into a given <repos> directory, only the 475532785Speter first three of these ('I', 'L' and 'N') can occur. 475632785Speter 475732785Speter Ignored file. 475832785Speter 475932785Speter CVS prints: I filename 476032785Speter 476132785Speter You'll need to examine it to see if it *should* have been ignored. If 476232785Speter you use "-I !", nothing will be ignored. 476332785Speter 476432785Speter Symbolic link. 476532785Speter 476632785Speter CVS prints: L linkname 476732785Speter 476832785Speter Links are "ignored", but you'll probably want to create a "checkout 476932785Speter helper" function to regenerate them. 477032785Speter 477132785Speter New file. 477232785Speter 477332785Speter CVS prints: N filename 477432785Speter 477532785Speter CVS creates a new file in the Repository. You don't have to do 477632785Speter anything to the file, but you might have to change Makefiles to refer 477732785Speter to it if this is really a new file. 477832785Speter 477932785Speter A file unchanged by the Vendor since its last release. 478032785Speter 478132785Speter CVS prints: U filename 478232785Speter 478332785Speter CVS will notice this and simply add the new ReleaseTag to the latest 478432785Speter rev on the Vendor branch. 478532785Speter 478632785Speter No work will be needed by you, whether you have changed the file or 478732785Speter not. No one will notice anything. 478832785Speter 478932785Speter A file changed by the Vendor, but not by you. 479032785Speter 479132785Speter CVS prints: U filename 479232785Speter 479332785Speter CVS should add the file onto the vendor branch and attach the Release 479432785Speter Tag to it. 479532785Speter 479632785Speter When you next execute "update" in any working directory you'll get the 479732785Speter new revision. 479832785Speter 479932785Speter A file changed by both the Vendor and by you. 480032785Speter 480132785Speter CVS prints: C filename 480232785Speter 480332785Speter These are the trouble files. For each of these files (or in groups -- 480432785Speter I usually do one directory at a time), you must execute: 480532785Speter 480632785Speter cvs update -j <PreviousReleaseTag> -j <ReleaseTag> 480732785Speter or 480832785Speter cvs update -j <VendorTag:yesterday> -j <VendorTag> 480932785Speter 481032785Speter It will print either 'M' (if no overlaps) or 'C', if overlaps. If a 481132785Speter 'C' shows up, you'll need to edit the file by hand. 481232785Speter 481332785Speter Then, for every file, you'll need to execute "cvs commit". 481432785Speter 481532785Speter See the part of Section 4C dealing with branch merges. 481632785Speter 481732785Speter If you are truly performing a large import, you will most likely 481832785Speter need help. Managing those people is another problem area. 481932785Speter 482032785Speter Since the merge of the Vendor branch is just like any other merge, you 482132785Speter should read section 4C for more info about performing and cleaning up 482232785Speter merges. 482332785Speter 482432785Speter The larger the import, and the larger the group of people involved, 482532785Speter the more often you should use "tag" and "rtag" to record even trivial 482632785Speter milestones. See 4C.14, especially the "paranoid" section. 482732785Speter 482832785Speter Before starting the import, you should install and test a "commitinfo" 482932785Speter procedure to record all commits in a file or via Email to a mail 483032785Speter archive. Along with the tags you placed on the Repository before the 483132785Speter import, this archive will help to track what was changed, if problems 483232785Speter occur 483332785Speter 483432785Speter There are four stages to the recovery: 483532785Speter 483632785Speter Parcel out the work -- Effective Emacs Engineering. 483732785Speter 483832785Speter As input to the assignment process, you might want to examine the tree 483932785Speter and record the last person who changed the file. You can also 484032785Speter research, if you don't already know, who is expert in each area of the 484132785Speter software. 484232785Speter 484332785Speter Examine the import log (you saved the output, right?), estimate how 484432785Speter much work is involved in each area and assign groups of files to 484532785Speter individual developers. Unless some directory is immense, it is easier 484632785Speter to manage if you assign whole directories to one person. 484732785Speter 484832785Speter Keep a list. Suggest a completion date/time. Tell them to "commit" the 484932785Speter file when they are finished with the merge. If you tagged the 485032785Speter Repository before starting the import, you should have no trouble 485132785Speter figuring out what happened. 485232785Speter 485332785Speter If you can, find out (or tell them) which working directory to use. 485432785Speter You should verify that the working directory they use is on the Main 485532785Speter Branch ("update -A") and without modified files. 485632785Speter 485732785Speter If you trust your crew, have them notify you by Email. Have them send 485832785Speter you the output from "cvs update" in their working directory. You might 485932785Speter have to poll some people until you are certain they have finished, or 486032785Speter have given up. (This is not an invention. I've heard a false, "Yeah, 486132785Speter sure. I finished yesterday," more times that you'd believe.) 486232785Speter 486332785Speter When all reports are in, go on to the Source Verification stage. 486432785Speter 486532785Speter Source Verification -- CVS and other Tools. 486632785Speter 486732785Speter If you didn't dictate which ones to use, find all working directories 486832785Speter and run "cvs -n update" in all of them. The history command and the 486932785Speter "commitinfo" log you set up might help to find checked out working 487032785Speter directories. 487132785Speter 487232785Speter Sticky conflict flags will help, but they can't recover from 487332785Speter sloppiness or incompetence. You might want to check everything out 487432785Speter into a tree and grep for the parts of the merge conflict markers CVS 487532785Speter doesn't look for. CVS looks for the string '^>>>>>>> '. The merge 487632785Speter operation also puts '^<<<<<<< ' and '^======= ' markers in the file 487732785Speter that careless developers might leave there. 487832785Speter 487932785Speter If you find problems simply by looking at the source files and working 488032785Speter directories, start the flogging now. Resolving the textual conflicts 488132785Speter is the easy part. Weed the turkeys out before reaching the next part 488232785Speter of the cleanup -- the resolution of logical conflicts. 488332785Speter 488432785Speter Then apply a set of post-commit tags. 488532785Speter 488632785Speter Logical Verification -- Diff and powerful eyeballs. 488732785Speter 488832785Speter No source control system can solve the problem of resolving 488932785Speter distributed conflicts in program logic. If you change the argument 489032785Speter template for function A (defined in file A.c) and add new calls to 489132785Speter function A from within function B (defined in file B.c) using the old 489232785Speter argument format, you are outside the realm of CVS's competence. 489332785Speter 489432785Speter Assign someone to understand what the Vendor changed by running "cvs 489532785Speter diff -c -r <PreviousReleaseTag> <ReleaseTag>", where the tags were 489632785Speter those handed to the last two invocations of "import". 489732785Speter 489832785Speter Then have the same person compare that output (logically or you can 489932785Speter actually diff the diffs) to the output of the similar "cvs diff -c -r 490032785Speter <pre-import-tag> <post-commit-tag>". The two sets of differences 490132785Speter should be almost identical. They should both show only the work *you* 490232785Speter have performed. 490332785Speter 490432785Speter Product Verification -- Build and Test. 490532785Speter 490632785Speter Don't let your help off the hook until you verify that the merge 490732785Speter actually produced something that can compile and pass tests. Compiling 490832785Speter should really be part of the logical verification phase, but you 490932785Speter should test the output of the build system before declaring victory 491032785Speter and releasing the troops. 491132785Speter 491232785Speter After it is all built, apply another set of tags to mark the end of 491332785Speter the "import process". You can delete the intermediate tags you added 491432785Speter during source and logic testing, but keep the "pre-import" and 491532785Speter "post-import" tags forever. 491632785Speter 491732785Speter Of course, experience can tell you when to skip a step. But I'd start 491832785Speter out by considering each one as necessary unless you can prove 491932785Speter otherwise. 492032785Speter 492132785Speter Last modified: _6/13/1997_ 492232785Speter 492332785Speter 14. Explain: ERROR: cannot create link to <file>: Permission denied 492432785Speter 492532785Speter This error appears when you try to execute a second (or later) 492632785Speter "import" into the same module from a directory to which you don't have 492732785Speter write access. 492832785Speter 492932785Speter The "link error" is caused by a feature purposely added to speed up 493032785Speter the import. 493132785Speter 493232785Speter Though the error message is somewhat strange, it indicates that 493332785Speter "import" is supposed to be executed only in writable directories. 493432785Speter 493532785Speter Last modified: _6/13/1997_ 493632785Speter 493732785Speter 15. Where does the -m <message> go when the file doesn't change? 493832785Speter 493932785Speter The <message> handed to import is used as an RCS log message, but only 494032785Speter if the imported file changed since the last version on the Vendor 494132785Speter branch. If the imported file hasn't changed, then no new revision is 494232785Speter created. The <ReleaseTag> is still applied, but to the previous 494332785Speter revision. So the Tags are still correct, but the message is lost. 494432785Speter 494532785Speter Maybe it should be appended to the previous log message. But currently 494632785Speter it isn't. 494732785Speter 494832785Speter Last modified: _6/13/1997_ 494932785Speter 495032785Speter 16. How do I "import" just the files ignored by a previous "import"? 495132785Speter 495232785Speter A real answer follows, but first, an editorial: 495332785Speter 495432785Speter I am now convinced that you should always use the "-I !" option. 495532785Speter Removing a few extraneous files from the Repository is a lot easier 495632785Speter than the recovery step described below. 495732785Speter 495832785Speter Let's assume your original import procedure was: (We assume there is 495932785Speter enough disk space in /tmp.) 496032785Speter 496132785Speter cd <head-of-vendor-tree> 496232785Speter cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP 496332785Speter 496432785Speter To import just the files ignored by "import", I would do this: 496532785Speter 496632785Speter Create a list of the ignored files to import: 496732785Speter 496832785Speter cd <head-of-vendor-tree> awk '/^I / {print $2}' /tmp/IMP | sed 496932785Speter 's|^gnu/xyz/||' > /tmp/IG [Edit the IG file to contain just the files 497032785Speter you want.] 497132785Speter 497232785Speter Then create a sparse directory by handing your list to the GNU 497332785Speter version of "tar", installed in many places as "gtar": 497432785Speter 497532785Speter mkdir /tmp/FIXUP gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf 497632785Speter -) 497732785Speter 497832785Speter Then rerun the import. Use the exact same command, but execute it in 497932785Speter the sparse directory tree you just created. And this time, tell it not 498032785Speter to ignore anything. 498132785Speter 498232785Speter cd /tmp/FIXUP 498332785Speter cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 498432785Speter 498532785Speter Last modified: _6/13/1997_ 498632785Speter 498732785Speter 17. Why did "import" ignore all the symlinks? 498832785Speter 498932785Speter This is another design choice. 499032785Speter 499132785Speter Like the Unix "tar" command, "import" could sprout an option to follow 499232785Speter symbolic links, but I don't think CVS will ever follow symbolic links 499332785Speter by default. 499432785Speter 499532785Speter Two possible future enhancements have been seriously discussed: 499632785Speter 499732785Speter Treat symbolic links as data in its parent directory (the way 499832785Speter ClearCase does) in some sort of per-directory control file. 499932785Speter 500032785Speter Treat symbolic links as version-controlled elements themselves, 500132785Speter whose data is the value of readlink(2). 500232785Speter 500332785Speter For now, they are simply ignored. 500432785Speter 500532785Speter If you want to save and reconstruct symlinks, you might want to define 500632785Speter a "checkout" or "update" program in the modules file which could 500732785Speter consult a file kept under CVS in your working directory and make sure 500832785Speter the specified links are in place. 500932785Speter 501032785Speter Last modified: _6/13/1997_ 501132785Speter 501232785Speter Category: /Commands_/log_lo_rlog/ 501332785Speter 501432785Speter " + "log", "lo", "rlog"" 501532785Speter 501632785Speter 1. What is "log" for? 501732785Speter 501832785Speter To provide an interface to the RCS "rlog" command, which displays 501932785Speter information about the underlying RCS files, including the revision 502032785Speter history and Tag (RCS calls it a "symbol") list. 502132785Speter 502232785Speter Last modified: _6/13/1997_ 502332785Speter 502432785Speter 2. How do I extract the log entries between two revisions? 502532785Speter 502632785Speter If both <rev1> and <rev2> are on the same branch, you can get what you 502732785Speter are looking for with: (If they aren't on the same branch you'll either 502832785Speter get an error or a display of the whole change log.) 502932785Speter 503032785Speter cvs log -r<rev1>:<rev2> <file> 503132785Speter 503232785Speter If you want all the revisions on the branch from <rev1> to the end of 503332785Speter the branch <rev1> is on, you can use: 503432785Speter 503532785Speter cvs log -r<rev1>: <file> 503632785Speter 503732785Speter (If <rev1> is a numeric RCS symbol attached to a branch revision with 503832785Speter an even number of '.'s in it, you get the whole branch.) 503932785Speter 504032785Speter If you want all the revisions on the branch from the beginning of the 504132785Speter branch <rev2> is on up to revision <rev2>, you can use: 504232785Speter 504332785Speter cvs log -r:<rev2> <file> 504432785Speter 504532785Speter Note: Depending on whether <rev1> and <rev2> are: 504632785Speter 504732785Speter - numeric or symbolic 504832785Speter - in the file or not 504932785Speter - on the same branch or not 505032785Speter 505132785Speter the RCS "rlog" (and therefore the "cvs log") command will 505232785Speter display some combination of: 505332785Speter 505432785Speter - error messages 505532785Speter - (intuitively correct) partial log listings 505632785Speter - a display of the entire change log. 505732785Speter 505832785Speter Last modified: _6/13/1997_ 505932785Speter 506032785Speter 3. How do I extract the log entries on a whole branch? 506132785Speter 506232785Speter cvs log -r<rev> <file> 506332785Speter 506432785Speter where <rev> must be a branch revision (one with an even number of 506532785Speter dots) or a *non-branch* tag on a branch revision. Non-branch tags on a 506632785Speter branch revision are not normally attached by CVS, to add one you will 506732785Speter have to explicitly tag a physical branch number within each file. 506832785Speter Since these branch numbers are almost never the same in different 506932785Speter files, this command is not all that useful. 507032785Speter 507132785Speter The intuitive command (at least from the CVS perspective): 507232785Speter 507332785Speter cvs log -r<branch_tag> <file> 507432785Speter 507532785Speter does not work. 507632785Speter 507732785Speter Last modified: _6/13/1997_ 507832785Speter 507932785Speter 4. How do I generate ChangeLogs from RCS logs? 508032785Speter 508132785Speter A program called rcs2log is distributed as part of GNU Emacs 19. A 508232785Speter (possibly older) version of this program appears in the contrib 508332785Speter directory of the cvs source tree. 508432785Speter 508532785Speter Last modified: _6/13/1997_ 508632785Speter 508732785Speter 5. Why does "log" tell me a file was committed exactly 5 hours later 508832785Speter 508932785Speter than I know it was? 509032785Speter 509132785Speter I can tell by this question that you were working in a time zone that 509232785Speter is 5 hours behind GMT (e.g. the U.S. East Coast in winter). 509332785Speter 509432785Speter RCS file dates are stored in GMT to allow users in different time 509532785Speter zones to agree on the meaning of a timestamp. At first glance this 509632785Speter doesn't seem necessary, but many companies use distributed file 509732785Speter systems, such as NFS or AFS, across multiple timezones. 509832785Speter 509932785Speter Some standard form must be used. GMT, as the "grid origin", is an 510032785Speter obvious candidate. The only other reasonable choice is to put the 510132785Speter timezone information in all the time stamps, but that changes the RCS 510232785Speter file format incompatibly, a step which has been avoided in the last 510332785Speter few RCS releases. 510432785Speter 510532785Speter Last modified: _6/13/1997_ 510632785Speter 510732785Speter Category: /Commands_/patch_pa_rdiff/ 510832785Speter 510932785Speter " + "patch", "pa", "rdiff"" 511032785Speter 511132785Speter 1. What is "patch" for? 511232785Speter 511332785Speter To produce a "diff" between tagged releases to be handed to the 511432785Speter "patch" command at other sites. This is the standard way that source 511532785Speter patches are distributed on the network. 511632785Speter 511732785Speter Last modified: _6/13/1997_ 511832785Speter 511932785Speter 2. Why does "patch" include files from the Attic when I use '-D'? 512032785Speter 512132785Speter See the explanation of the same problem with "update -D" contained in 512232785Speter section 5B. 512332785Speter 512432785Speter Last modified: _6/13/1997_ 512532785Speter 512632785Speter 3. How do I make "patch" produce a patch for one or two files? It seems to 512732785Speter work only with modules. 512832785Speter 512932785Speter Patch is intended for producing patches of whole modules between 513032785Speter releases to be distributed to remote sites. Instead of "patch", you 513132785Speter can use the "diff" command with the '-c' context option: 513232785Speter 513332785Speter cvs diff -c -r <rev/tag> -r <rev/tag> <file1> . . . 513432785Speter 513532785Speter The patch command will be able to merge such a "diff" into the remote 513632785Speter source files. 513732785Speter 513832785Speter If you configured CVS to use a version of "diff" that supports the 513932785Speter '-u' option, you can produce a more compact "patch" in "unidiff" 514032785Speter format. The latest revisions of the patch command can parse and apply 514132785Speter patches in "unidiff" format. 514232785Speter 514332785Speter Last modified: _6/13/1997_ 514432785Speter 514532785Speter Category: /Commands_/release_re_rel/ 514632785Speter 514732785Speter " + "release", "re", "rel"" 514832785Speter 514932785Speter 1. What is "release" for? 515032785Speter 515132785Speter To register that a module is no longer in use. It is intended to 515232785Speter reverse the effects of a "checkout" by adding a record to the history 515332785Speter file to balance the checkout record and by optionally allowing you to 515432785Speter delete the checked-out directory associated with the module name. 515532785Speter 515632785Speter Last modified: _6/13/1997_ 515732785Speter 515832785Speter 2. Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs 515932785Speter release path/name/subdir" without an "unknown module name"? 516032785Speter 516132785Speter A simplistic implementation. (I can say this -- I wrote it.) 516232785Speter 516332785Speter The "release" function was written for CVS 1.2 under the assumption 516432785Speter that the "module name" is a first class, unavoidable interface to the 516532785Speter Repository, allowing no way to retrieve anything other than by module 516632785Speter name. Though it is easier to program that way, many users of CVS 516732785Speter believe the modules support to be too primitive to allow such a 516832785Speter limitation. 516932785Speter 517032785Speter Since "release" was written, other parts of CVS broke that assumption. 517132785Speter It needs to be revised. 517232785Speter 517332785Speter Last modified: _6/13/1997_ 517432785Speter 517532785Speter 3. Why can't I "release" portions of a checked out directory? I should be 517632785Speter able to "release" any file or sub-directory within my working directory. 517732785Speter 517832785Speter This isn't really a limitation in "release", per se. CVS doesn't try 517932785Speter to keep track of which files in which directories are "checked out" 518032785Speter and which are just lying there. You can delete directories and 518132785Speter "update" will not bring them back unless you add a special "-d" 518232785Speter option. 518332785Speter 518432785Speter In other words, CVS doesn't keep track of how you adjust the partition 518532785Speter between files you consider part of your working set and files that 518632785Speter were checked out because they are part of the same module or 518732785Speter directory. And neither does "release". 518832785Speter 518932785Speter In future CVS releases, "release" might become sophisticated enough to 519032785Speter handle both the reversal of a "checkout" and the deletion of random 519132785Speter portions of the working directory, but it isn't that way now. 519232785Speter 519332785Speter Last modified: _6/13/1997_ 519432785Speter 519532785Speter 4. I removed the tree that I was about to start working on. How do I tell 519632785Speter cvs that I want to release it if I don't have it anymore? 519732785Speter 519832785Speter See 3G.4. 519932785Speter 520032785Speter Last modified: _6/13/1997_ 520132785Speter 520232785Speter 5. Why doesn't "release -d module" reverse a "checkout module"? 520332785Speter 520432785Speter It does, if you are using "module" in a way that "release" expects: a 520532785Speter non-alias string in the left column of the "modules" database. 520632785Speter 520732785Speter If "module" is really an alias, or if you are using a relative path in 520832785Speter the place of "module", or if you renamed the directory with the -d 520932785Speter option in the modules file or on the "checkout" command line, then the 521032785Speter current version of "release" won't work. 521132785Speter 521232785Speter Future versions of "release" will probably fix most of these. 521332785Speter 521432785Speter Last modified: _6/13/1997_ 521532785Speter 521632785Speter 6. Why can't I release a module renamed with "cvs checkout -d"? 521732785Speter 521832785Speter The current version of "release" doesn't know how to track the 521932785Speter renaming option ('-d') of the "checkout" command. It will probably be 522032785Speter fixed in the future. 522132785Speter 522232785Speter Last modified: _6/13/1997_ 522332785Speter 522432785Speter Category: /Commands_/remove_rm_delete/ 522532785Speter 522632785Speter " + "remove", "rm", "delete"" 522732785Speter 522832785Speter 1. What is "remove" for? 522932785Speter 523032785Speter To remove a file from the working branch. It removes a file from the 523132785Speter main branch by placing it in an "Attic" directory. 523232785Speter 523332785Speter Last modified: _6/13/1997_ 523432785Speter 523532785Speter 2. Why doesn't "remove" work on directories when it appears to try? 523632785Speter 523732785Speter Oversight. It should be able to delete an empty directory, but you 523832785Speter still don't have a way to remember when it was there and when it 523932785Speter disappeared to allow the "-D " option to work. 524032785Speter 524132785Speter You'll have to remove the working directory and the matching directory 524232785Speter in the Repository. 524332785Speter 524432785Speter Note that you want to do a _cvs remove dir_ in the working directory, 524532785Speter do a cvs commit, and then do a _rmdir dir_ in the Repository. 524632785Speter (msusrtsp.mark at eds dot com) 524732785Speter 524832785Speter Last modified: _12/18/1997_ 524932785Speter 525032785Speter 3. I don't like removing files. Is there another way to ignore them? 525132785Speter 525232785Speter There's no reason to be hasty in using the "remove" command. 525332785Speter 525432785Speter If there is a way to ignore files in your build procedures, I'd just 525532785Speter do that. Later, when you decide that the files are really ancient, you 525632785Speter can execute a "remove" command to clean up. 525732785Speter 525832785Speter The CVS "ignore" concept can't ignore files already in CVS. 525932785Speter 526032785Speter Last modified: _6/13/1997_ 526132785Speter 526232785Speter 4. I just removed a file. How do I resurrect it? 526332785Speter 526432785Speter If you executed "remove", but haven't typed "commit" (you can tell 526532785Speter this by the 'R' notation that "update" prints next to the file), you 526632785Speter can execute "add" to reverse the "remove". 526732785Speter 526832785Speter If you followed the "remove" with a "commit", you'll have to move it 526932785Speter back out of the Attic by hand: 527032785Speter 527132785Speter I use something like this: (csh-like syntax) 527232785Speter 527332785Speter set repos = `cat ./CVS/Repository` 527432785Speter mv $repos/Attic/filename,v $repos/filename,v 527532785Speter 527632785Speter (If you use relative paths in your Repository files, that first line 527732785Speter becomes: set repos = $CVSROOT/`cat ./CVS/Repository`) 527832785Speter 527932785Speter While a file is in the Attic, you can't "add" another file by the same 528032785Speter name. To add such a file you either have to move it by hand as in the 528132785Speter above, or delete it from the Attic. 528232785Speter 528332785Speter The main reason for the Attic is to retain files with tags in them. If 528432785Speter you execute: "update -r <oldtag>", files with <oldtag> attached to 528532785Speter some revision will be taken from the normal Repository area and from 528632785Speter the Attic. That's why you can't "add" a file with the same name. 528732785Speter "remove" only moves a file off the main branch, it doesn't obliterate 528832785Speter it. 528932785Speter 529032785Speter Last modified: _6/13/1997_ 529132785Speter 529232785Speter 5. Why doesn't "remove" delete the file? Instead, it prints an error 529332785Speter message and tells me to remove the file by hand. 529432785Speter 529532785Speter Design choice. Unix software written within last decade, usually 529632785Speter requires an extra verification step, such as answering a question or 529732785Speter adding a flag on the command line. CVS currently requires that you 529832785Speter delete the file first unless you specify the '-f' (force) option, 529932785Speter which deletes the file before performing "cvs remove". 530032785Speter 530132785Speter Last modified: _6/13/1997_ 530232785Speter 530332785Speter Category: /Commands_/rtag_rt_rfreeze/ 530432785Speter 530532785Speter " + "rtag", "rt", "rfreeze"" 530632785Speter 530732785Speter 1. What is "rtag" for? 530832785Speter 530932785Speter To add a symbolic label (a "tag") to the last committed revisions of a 531032785Speter module directly in the Repository. 531132785Speter 531232785Speter Last modified: _6/13/1997_ 531332785Speter 531432785Speter 2. Why use "rtag"? It assumes no one is changing the Repository. 531532785Speter 531632785Speter Though the "tag" command is more useful in marking the revisions you 531732785Speter have in a particular working directory, "rtag" is much handier for 531832785Speter whole-Repository actions, which occur at major release boundaries. 531932785Speter 532032785Speter Last modified: _6/13/1997_ 532132785Speter 532232785Speter 3. What revision does "rtag -r <tag1> <tag2>" actually put the tag on? 532332785Speter 532432785Speter In short, the '-r' option is another way to select the revision to 532532785Speter tag. The revision is selected the same way for all commands that 532632785Speter accept a "-r <tag/rev>" option. 532732785Speter 532832785Speter Depending on whether <tag1> is a <branch_tag>, or a non-branch <tag> 532932785Speter and on whether you use the '-b' option to "rtag", you get four 533032785Speter different results: 533132785Speter 533232785Speter rtag -r <tag1> <tag2> 533332785Speter 533432785Speter Adds the non-branch tag <tag2> to the same revision that the 533532785Speter non-branch tag <tag1> is attached to. 533632785Speter 533732785Speter Example: 533832785Speter <tag1> --> TT1 533932785Speter <tag2> --> TT2 534032785Speter <file> --> Symbols: TT1:1.4 534132785Speter After --> Symbols: TT1:1.4,TT2:1.4 534232785Speter 534332785Speter rtag -r <branch_tag1> <tag2> 534432785Speter 534532785Speter Adds the non-branch tag <tag2> to the HEAD of (the highest revision 534632785Speter number on) the branch labelled with tag <branch_tag1>. 534732785Speter 534832785Speter Example: 534932785Speter <branch_tag1> --> BR1 535032785Speter <tag2> --> TT2 535132785Speter <file> --> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD) 535232785Speter After --> Symbols: BR1:1.2.0.2,TT2:1.2.2.5 535332785Speter 535432785Speter If the branch tagged by <branch_tag1> has not been created, then the 535532785Speter tag shows up on the branch point revision: 535632785Speter 535732785Speter Example: 535832785Speter <branch_tag1> --> BR1 535932785Speter <tag2> --> TT2 536032785Speter <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.) 536132785Speter After --> Symbols: BR1:1.2.0.2,TT2:1.2 536232785Speter 536332785Speter rtag -b -r <tag1> <branch_tag2> 536432785Speter 536532785Speter Adds the magic branch tag <branch_tag2> to the revision that the 536632785Speter non-branch tag <tag1> is attached to, preparing it to be a branch 536732785Speter point. 536832785Speter 536932785Speter Example: 537032785Speter <tag1> --> TT1 537132785Speter <branch_tag2> --> BR2 537232785Speter <file> --> Symbol: TT1:1.4 537332785Speter After --> Symbol: TT1:1.4, BR2:1.4.0.2 537432785Speter 537532785Speter rtag -b -r <branch_tag1> <branch_tag2> 537632785Speter 537732785Speter Adds the magic branch tag <branch_tag2> to the revision at the HEAD of 537832785Speter (the highest revision number on) the branch labelled with 537932785Speter <branch_tag1>, preparing it to be a branch point. 538032785Speter 538132785Speter Example: 538232785Speter <branch_tag1> --> BR1 538332785Speter <branch_tag2> --> BR2 538432785Speter <file> --> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD) 538532785Speter After --> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2 538632785Speter 538732785Speter If the branch tagged by <branch_tag1> has not been created, then the 538832785Speter tag shows up as a second branch off the same branch point revision: 538932785Speter 539032785Speter Example: 539132785Speter <branch_tag1> --> BR1 539232785Speter <tag2> --> TT2 539332785Speter <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.) 539432785Speter After --> Symbols: BR1:1.2.0.2,TT2:1.2.0.4 539532785Speter 539632785Speter In all four cases above, if <tag2> already exists on the file, you get 539732785Speter an error unless you specify the '-F' option. 539832785Speter 539932785Speter In all four cases, if <tag1> does not exist on the file, <tag2> is not 540032785Speter added unless you specify the '-f' option. 540132785Speter 540232785Speter Last modified: _6/13/1997_ 540332785Speter 540432785Speter 4. What happens if the tags are the same in "rtag -r <tag> <tag>"? 540532785Speter 540632785Speter Again, there are four cases depending on whether <tag> is a branch 540732785Speter tag, or a non-branch tag and on whether you use the '-b' option to 540832785Speter "rtag": 540932785Speter 541032785Speter rtag -r <tag> <tag> 541132785Speter 541232785Speter Is a no-op. It does nothing even with '-F' specified. 541332785Speter 541432785Speter If you add the '-f' option ("rtag -f -r <tag> <tag>"), then <tag> is 541532785Speter attached to the latest revision on the Main Branch if the file does 541632785Speter *not* already have <tag> on some revision. 541732785Speter 541832785Speter If the <tag> is already on the file, using "rtag -f" is still a no-op. 541932785Speter 542032785Speter rtag -r <branch_tag> <branch_tag> 542132785Speter 542232785Speter Produces an error, since the <branch_tag> is already on some revision 542332785Speter of the file. 542432785Speter 542532785Speter But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic branch tag 542632785Speter into a non-branch tag. 542732785Speter 542832785Speter Symbols: BR1:1.4.0.2 becomes Symbols: BR1:1.4 542932785Speter 543032785Speter rtag -b -r <tag> <tag> 543132785Speter 543232785Speter Produces an error, since the <tag> is already on the file. 543332785Speter 543432785Speter But, "rtag -F -b -r <tag> <tag>" turns the non-branch tag into a magic 543532785Speter branch tag. 543632785Speter 543732785Speter Symbols: BR1:1.4 becomes Symbols: BR1:1.4.0.2 543832785Speter 543932785Speter rtag -b -r <branch_tag> <branch_tag> 544032785Speter 544132785Speter Produces an error, since the <branch_tag> is already on the file. 544232785Speter 544332785Speter But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the branch 544432785Speter number. It essentially removes the branch and creates a new one by the 544532785Speter same name. 544632785Speter 544732785Speter Symbols: BR1:1.2.0.4 becomes Symbols: BR1:1.2.0.6 544832785Speter 544932785Speter Last modified: _6/13/1997_ 545032785Speter 545132785Speter 5. Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or duplicate 545232785Speter a magic branch tag? 545332785Speter 545432785Speter None of the "tag" or "rtag" options rename anything. They only apply 545532785Speter (or, with the '-F' option, move) tags to specific revisions in the 545632785Speter file. 545732785Speter 545832785Speter See 3M.[3-4] above for details of how it works. 545932785Speter 546032785Speter To rename a non-branch tag, see 3O.9. To rename a magic branch tag, 546132785Speter see 4D.5 546232785Speter 546332785Speter Last modified: _6/13/1997_ 546432785Speter 546532785Speter Category: /Commands_/status_st_stat/ 546632785Speter 546732785Speter " + "status", "st", "stat"" 546832785Speter 546932785Speter 1. What is "status" for? 547032785Speter 547132785Speter To display the status of files, including the revision and branch you 547232785Speter are working on and the existence of "sticky" information. 547332785Speter 547432785Speter Last modified: _6/13/1997_ 547532785Speter 547632785Speter 2. Why does "status" limit the File: at the top to 17 characters? 547732785Speter 547832785Speter Designed that way to line up with other data. You can find the whole 547932785Speter filename in the line beginning with "RCS version:", which is not 548032785Speter limited in length. 548132785Speter 548232785Speter Last modified: _6/13/1997_ 548332785Speter 548432785Speter 3. Why does it print "Sticky" lines when the values are "(none)"? 548532785Speter 548632785Speter Oversight. It should probably elide lines without information. 548732785Speter 548832785Speter Last modified: _6/13/1997_ 548932785Speter 549032785Speter 4. Shouldn't the status "Needs Checkout" be "Needs Update"? 549132785Speter 549232785Speter Probably. 549332785Speter 549432785Speter [[Did this show up in CVS 1.4?]] 549532785Speter 549632785Speter Last modified: _6/13/1997_ 549732785Speter 549832785Speter Category: /Commands_/tag_ta_freeze/ 549932785Speter 550032785Speter " + "tag", "ta", "freeze"" 550132785Speter 550232785Speter 1. What is "tag" for? 550332785Speter 550432785Speter To add a symbolic label (a "tag") to the RCS files last checked out, 550532785Speter updated or committed in a working directory. 550632785Speter 550732785Speter Last modified: _6/13/1997_ 550832785Speter 550932785Speter 2. What is the difference between "tag" and "rtag"? 551032785Speter 551132785Speter The end result of both commands is that a <tag>, or symbolic name, is 551232785Speter attached to a single revision in each of a collection of files. 551332785Speter 551432785Speter The differences lie in: 551532785Speter 551632785Speter The collection of files they work on. 551732785Speter 551832785Speter "rtag" works on the collection of files referred to by a "module" name 551932785Speter as defined in the "modules" file, or a relative path within the 552032785Speter Repository. 552132785Speter 552232785Speter "tag" works on files and directories specified on the command line 552332785Speter within the user's working directory. (Default is '.') 552432785Speter 552532785Speter Both commands recursively follow directory hierarchies within the 552632785Speter named files and directories. 552732785Speter 552832785Speter The revisions they choose to tag. 552932785Speter 553032785Speter "rtag" places a tag on the latest committed revision of each file on 553132785Speter the branch specified by the '-r' option. By default it tags the Main 553232785Speter Branch. 553332785Speter 553432785Speter "tag" places a tag on the BASE (i.e. last checked out, updated or 553532785Speter committed) revision of each file found in the working directory. (The 553632785Speter BASE revision of a file is the one stored in the ./CVS/Entries file.) 553732785Speter 553832785Speter A different set of command line options. 553932785Speter 554032785Speter For example, "rtag" takes a "-r <oldtag>" option to retag an existing 554132785Speter tag. The "tag" command does not. 554232785Speter 554332785Speter How it is logged. 554432785Speter 554532785Speter Currently "rtag" records the <tag> and the module in the "history" 554632785Speter file, while "tag" does not. 554732785Speter 554832785Speter Last modified: _6/13/1997_ 554932785Speter 555032785Speter 3. Why does "tag -b" not put a tag on the Branch Point revision? How do I 555132785Speter refer to the Branch Point? 555232785Speter 555332785Speter This is probably an oversight, or a disbelief in the need for it. If 555432785Speter everything works perfectly, the "update -j" command will do the merge 555532785Speter you need and you don't need to check up on it by playing with the 555632785Speter branch point revision. 555732785Speter 555832785Speter The '-b' option attaches a magic branch tag to allow CVS later to 555932785Speter figure out the branch point. The actual revision that <tag> is 556032785Speter attached to does not exist. References to the branch tag are 556132785Speter equivalent to references to the latest revision on the branch. 556232785Speter 556332785Speter There is no way to refer to the branch point without adding a 556432785Speter non-branch tag. You might want to add non-branch tags as a habit and 556532785Speter add branch tags later, possibly immediate after adding the non-branch 556632785Speter tag. See 4C.3 on Creating a Branch. 556732785Speter 556832785Speter Last modified: _6/13/1997_ 556932785Speter 557032785Speter 4. So "{r}tag" labels a bunch of files. What do you use a Tag for? 557132785Speter 557232785Speter You use it to "checkout" the labeled collection of files as a single 557332785Speter object, referring to it by name. 557432785Speter 557532785Speter Anywhere a revision number can be used a Tag can be used. In fact tags 557632785Speter are more useful because they draw a line through a collection of 557732785Speter files, marking a development milestone. 557832785Speter 557932785Speter The way to think about a Tag is as a curve drawn through a matrix of 558032785Speter filename vs. revision number. Consider this: 558132785Speter 558232785Speter Say we have 5 files (in some arbitrary modules, some may be in 2 or 558332785Speter more modules by name, some may be in 2 or more modules because of the 558432785Speter Repository tree structure) with the following revisions: 558532785Speter 558632785Speter file1 file2 file3 file4 file5 558732785Speter 558832785Speter 1.1 1.1 1.1 1.1 /--1.1* <-*- <tag> 558932785Speter 1.2*- 1.2 1.2 -1.2*- 559032785Speter 1.3 \- 1.3*- 1.3 / 1.3 559132785Speter 1.4 \ 1.4 / 1.4 559232785Speter \-1.5*- 1.5 559332785Speter 1.6 559432785Speter 559532785Speter At some time in the past, the '*' versions were tagged. Think of the 559632785Speter <tag> as a handle attached to the curve drawn through the tagged 559732785Speter revisions. When you pull on the handle, you get all the tagged 559832785Speter revisions. Another way to look at it is that you draw a straight line 559932785Speter through the set of revisions you care about and shuffle the other 560032785Speter revisions accordingly. Like this: 560132785Speter 560232785Speter file1 file2 file3 file4 file5 560332785Speter 560432785Speter 1.1 560532785Speter 1.2 560632785Speter 1.1 1.3 _ 560732785Speter 1.1 1.2 1.4 1.1 / 560832785Speter 1.2*----1.3*----1.5*----1.2*----1.1 (--- <-- Look here 560932785Speter 1.3 1.6 1.3 \_ 561032785Speter 1.4 1.4 561132785Speter 1.5 561232785Speter 561332785Speter I find that using these visual aids, it is much easier to understand 561432785Speter what a <tag> is and what it is useful for. 561532785Speter 561632785Speter Last modified: _6/13/1997_ 561732785Speter 561832785Speter 5. How do I get "tag" and "rtag" to send mail the way "commit" does? 561932785Speter 562032785Speter The "commit" command is supported by two files ("commitinfo" and 562132785Speter "loginfo") not used by other commands. To do logging the same way for 562232785Speter "tag" and "rtag" would require another file like loginfo, which 562332785Speter currently doesn't exist. 562432785Speter 562532785Speter The "rtag" command requires a "module" entry, which can specify a 562632785Speter "tag" program using the "-t programname" option on the module line. 562732785Speter 562832785Speter There is no equivalent support for "tag". 562932785Speter 563032785Speter Last modified: _6/13/1997_ 563132785Speter 563232785Speter 6. Why can't "tag" handle the '-r' option that "rtag" takes? 563332785Speter 563432785Speter Oversight. The answer is probably "Fixed in a Future Release." 563532785Speter 563632785Speter Last modified: _6/13/1997_ 563732785Speter 563832785Speter 7. After a "tag <tag>" in my working directory, why doesn't "checkout -r 563932785Speter <tag>" somewhere else produce copies of my current files? 564032785Speter 564132785Speter The only reason this would fail, other than misspelling the <tag> 564232785Speter string, is that you didn't "commit" your work before "tagging" it. 564332785Speter Only committed revisions may be tagged. Modified files are not marked 564432785Speter for later tagging. 564532785Speter 564632785Speter Last modified: _6/13/1997_ 564732785Speter 564832785Speter 8. Why doesn't "tag" write a history record the way "rtag" does? 564932785Speter 565032785Speter The "rtag" command was originally intended to place major "release" 565132785Speter tags onto modules. The "tag" functionality was developed to *move* the 565232785Speter more significant tag when slight changes to individual files sneaked 565332785Speter in after the release tag was stamped onto the Repository. 565432785Speter 565532785Speter The significant event was the "rtag", which was recorded in the 565632785Speter "history" file for the "history -T" option to work. 565732785Speter 565832785Speter It turns out that "tag" is generally more useful than "rtag", so the 565932785Speter model has changed. Future revisions of CVS will probably store both 566032785Speter kinds of tags in the history file. 566132785Speter 566232785Speter Last modified: _6/13/1997_ 566332785Speter 566432785Speter 9. How do I rename a <tag>? 566532785Speter 566632785Speter For a procedure to rename a branch tag, See section 4D.5 The following 566732785Speter covers only non-branch tags. 566832785Speter 566932785Speter First, pick a <newtag> that is not in use. You could reuse (i.e. move) 567032785Speter an existing tag to the new revisions using the '-F' option, but that 567132785Speter will confuse matters when both tags are not already on a file. (It 567232785Speter will probably confuse "rtag -f" too.) 567332785Speter 567432785Speter Use "rtag" to place <newtag> only on revisions attached to <oldtag> in 567532785Speter the whole Repository, then delete the old one. 567632785Speter 567732785Speter cvs rtag -r <oldtag> <newtag> world 567832785Speter cvs rtag -d <oldtag> world. 567932785Speter 568032785Speter You can also checkout or update your working directory to the <oldtag> 568132785Speter and "tag" rather than "rtag" the result. But that will take longer and 568232785Speter it has the chance of producing conflicts. 568332785Speter 568432785Speter cvs update -r <oldtag> 568532785Speter cvs tag <newtag> 568632785Speter cvs tag -d <oldtag> 568732785Speter cvs update -A (or cvs update -r <previous_tag>) 568832785Speter 568932785Speter Last modified: _6/13/1997_ 569032785Speter 569132785Speter Category: /Commands_/update_up_upd/ 569232785Speter 569332785Speter " + "update", "up", "upd"" 569432785Speter 569532785Speter 1. What is "update" for? 569632785Speter 569732785Speter The "update" command is by far the most important command and is 569832785Speter probably also the most used command. 569932785Speter 570032785Speter It has five purposes: (And many options.) 570132785Speter 570232785Speter To display the status of your working files. 570332785Speter 570432785Speter Though a plain "update" also displays the status, it does so after 570532785Speter possibly altering your working directory. To see the status of your 570632785Speter working files without changing anything, type: 570732785Speter 570832785Speter cvs -n update {optional list of files} 570932785Speter 571032785Speter To merge changes made by others to the branch you are working on 571132785Speter into your working files. 571232785Speter 571332785Speter Each working directory is attached to a branch, usually the Main 571432785Speter branch. To merge changes made on your working branch since your last 571532785Speter checkout, update or commit, type: 571632785Speter 571732785Speter cvs update {optional list of files} 571832785Speter 571932785Speter To merge changes made on another branch into the branch you are 572032785Speter working on (your "working branch"). 572132785Speter 572232785Speter If you want to grab a whole branch, from the branch point, which is 572332785Speter assumed to be on the Main Branch, to the end of the branch, you type: 572432785Speter 572532785Speter cvs update -j <branch_tag> {optional files} 572632785Speter 572732785Speter If you want to grab the changes made between two tags or revisions, 572832785Speter you type: 572932785Speter 573032785Speter cvs update -j <tag1> -j <tag2> {optional files} 573132785Speter 573232785Speter (If you are working with a single file, the Tags could also be 573332785Speter revisions numbers. Unless you take great care to match revision 573432785Speter numbers across different files (a waste of time given the way Tags 573532785Speter work), using revision numbers in place of the Tags for multiple files 573632785Speter would be meaningless.) 573732785Speter 573832785Speter To move your working directory to another branch. 573932785Speter 574032785Speter A working directory is presumed to be attached to (or working on) a 574132785Speter particular branch, usually the Main branch. To alter what CVS believes 574232785Speter to be your working branch, you "move" to that branch. 574332785Speter 574432785Speter To move to a tagged branch, type: 574532785Speter 574632785Speter cvs update -r <branch_tag> {optional files} 574732785Speter 574832785Speter To move to the Main Branch, type: 574932785Speter 575032785Speter cvs update -A {optional files} 575132785Speter 575232785Speter If you have modified files in your working directory, this is not a 575332785Speter clean move. CVS will attempt to merge the changes necessary to make it 575432785Speter look like you made the same changes to the new branch as you made in 575532785Speter the old one. But if you do this twice without resolving the merge 575632785Speter conflicts each time, you can lose work. 575732785Speter 575832785Speter To retrieve old revisions of files. 575932785Speter 576032785Speter This option is similar to 4 above but you are not restricted to using 576132785Speter a <branch_tag>. You may specify any revision or <tag> with '-r' and 576232785Speter get the specified revision or the tagged revision: 576332785Speter 576432785Speter cvs update -r <tag/rev> {optional files} 576532785Speter 576632785Speter Or you may specify any date with '-D': 576732785Speter 576832785Speter cvs update -D <date> {optional files} 576932785Speter 577032785Speter The '-p' option sends the revisions to standard output (normally your 577132785Speter terminal) rather than setting the "sticky" tag and changing the files. 577232785Speter 577332785Speter Last modified: _6/13/1997_ 577432785Speter 577532785Speter 2. What do 'U', 'M' and 'C' mean when I type "update"? Are they different 577632785Speter for "cvs -n update"? 577732785Speter 577832785Speter "cvs update" merges changes made to the Repository, since your last 577932785Speter "checkout", "update" or "commit", into your working files. You can 578032785Speter think of it as changing your BASE revision. 578132785Speter 578232785Speter "cvs update" prints lines beginning with: 578332785Speter 578432785Speter 'U' after replacing your unmodified file with a different 578532785Speter revision from the Repository. 578632785Speter 578732785Speter 'M' for two different reasons: 578832785Speter 578932785Speter for files you have modified that have not changed in the Repository. 579032785Speter 579132785Speter after a merge, if it detected no conflicts. 579232785Speter 579332785Speter 'C' after a merge, if it detected conflicts. See 2D.7 and 3P.6 for 579432785Speter more info on conflict resolution and "sticky conflicts." 579532785Speter 579632785Speter "cvs -n update" shows what it *would* do, rather than doing it. Or, 579732785Speter another way of looking at it, "cvs -n update" displays the 579832785Speter relationship between your current BASE revisions (identified in your 579932785Speter ./CVS/Entries file) and the HEAD revisions (the latest revisions in 580032785Speter the Repository). 580132785Speter 580232785Speter "cvs -n update" prints lines beginning with: 580332785Speter 580432785Speter 'U' for files you have not modified that have changed in the 580532785Speter Repository. 580632785Speter 580732785Speter 'M' for files you have modified that have not changed in the 580832785Speter Repository. 580932785Speter 581032785Speter 'C' for files you have modified that have also been changed in the 581132785Speter Repository. 581232785Speter 581332785Speter See 4C.6 for what the letters mean when merging in from another 581432785Speter branch. The output is almost the same for a normal update if you 581532785Speter consider the Repository as the branch and your working directory as 581632785Speter the "trunk". 581732785Speter 581832785Speter Last modified: _6/13/1997_ 581932785Speter 582032785Speter 3. What's the difference between "update" and "checkout"? 582132785Speter 582232785Speter See 3C.4 above. 582332785Speter 582432785Speter Last modified: _6/13/1997_ 582532785Speter 582632785Speter 4. Why don't I get new files when I execute "update"? 582732785Speter 582832785Speter There are six reasons for nothing to happen during an "update": 582932785Speter 583032785Speter Nothing on your branch changed in the Repository. 583132785Speter 583232785Speter If no one has committed anything to the branch you are working on 583332785Speter (normally the Main branch) since the last time you executed 583432785Speter "checkout", "update" or "commit", nothing will happen. 583532785Speter 583632785Speter It's like shouting "xyzzy" or "plugh" in the wrong room. 583732785Speter 583832785Speter You have a "sticky" non-branch <tag> or <date> attached to the 583932785Speter working files you are trying to "update". 584032785Speter 584132785Speter At some time in the past you checked out or updated your directory 584232785Speter with the "-r <tag>" or "-D <date>" option. Until you do it again with 584332785Speter a different tag or date, or go back to the Main Branch with "update 584432785Speter -A", you will never again see any updates. 584532785Speter 584632785Speter The ./CVS/Entries.Static file exists and you are expecting a new 584732785Speter file. 584832785Speter 584932785Speter If your ./CVS administrative directory contains a file named 585032785Speter Entries.Static, no files will be checked out that aren't already in 585132785Speter the Entries or Entries.Static file. 585232785Speter 585332785Speter You forgot to use the '-d' option and are looking for new 585432785Speter directories. 585532785Speter 585632785Speter If you execute "update" without the '-d' option, it will not create 585732785Speter new directories that have been added to the Repository. 585832785Speter 585932785Speter You typed "update" instead of "cvs update". 586032785Speter 586132785Speter On most Unix systems, your disk caches are now furiously being flushed 586232785Speter by multiple update daemons, destroying performance and proving to 586332785Speter management that you need more CPU power. :-) 586432785Speter 586532785Speter On HP systems you might be asked what package you want to install from 586632785Speter the "update server". 586732785Speter 586832785Speter Someone removed (using "admin -o") your BASE revision (the revision 586932785Speter CVS thought you had in your working directory), then committed a 587032785Speter "replacement". CVS is now confused because the revision in the 587132785Speter Repository matches your BASE revision when the files themselves don't 587232785Speter match. See 3B.6. 587332785Speter 587432785Speter Last modified: _6/13/1997_ 587532785Speter 587632785Speter 5. Why does "update" say 'M' both for plain modified files and for 587732785Speter successful (i.e. conflict-free) merges? Aren't they different? 587832785Speter 587932785Speter A design choice. Yes, they are different internally, but that 588032785Speter shouldn't matter. Your files are in the same condition after the 588132785Speter "update" as they were before -- a "diff" will display only your 588232785Speter modifications. And you are expected to continue onward with parts two 588332785Speter and three of the normal development cycle: "emacs" (a synonym for 588432785Speter "edit" in most of the civilized world) and "commit". 588532785Speter 588632785Speter Last modified: _6/13/1997_ 588732785Speter 588832785Speter 6. What's a "sticky conflict"? How does it know a conflict occurred? 588932785Speter 589032785Speter When a "cvs update" (or an "update -j") creates a conflict, it prints 589132785Speter a 'C' and stores the timestamp of the file after the merge in a 589232785Speter special field in the ./CVS/Entries file. 589332785Speter 589432785Speter This conflict indication implies that the merge command altered your 589532785Speter working file to contain conflict markers surrounding the overlapping 589632785Speter code segments. For example, say that 589732785Speter 589832785Speter - Two developers acquire revision 1.2 of <file> via "checkout" or 589932785Speter "update". 590032785Speter 590132785Speter - Developer A changes line 1 from "9999" to "5555", then commits the 590232785Speter file, creating revision 1.3. 590332785Speter 590432785Speter - Developer B changes line 1 from "9999" to "7777", then tries to 590532785Speter commit the file, but is blocked because the file is not up to date. 590632785Speter Developer B then runs "update" and sees the conflict marker 'C'. The 590732785Speter beginning of the file would look like this: 590832785Speter 590932785Speter <<<<<<< <file> The working <file> in question. 591032785Speter 7777 Change made to the working <file>. 591132785Speter ======= 591232785Speter 5555 Change made in the first commit (1.3) 591332785Speter >>>>>>> 1.3 The revision created by the first commit. 591432785Speter 591532785Speter The conflict is "sticky", which means that until the conflict is 591632785Speter cleared, the "update" command will continue to display the file's 591732785Speter status as 'C' and the "status" command will show the file's status as 591832785Speter "Unresolved Conflict". 591932785Speter 592032785Speter Until the conflict is cleared, "commit" is blocked for this file. 592132785Speter 592232785Speter The sticky conflict indicator can be cleared by: 592332785Speter 592432785Speter Resolving the conflict by editing the file. Two things must happen 592532785Speter before the conflict is considered resolved: 592632785Speter 592732785Speter The timestamp of the file must change. *and* The file must contain no 592832785Speter conflict markers. (The string searched for in the file is the regexp: 592932785Speter "^>>>>>>> ".) 593032785Speter 593132785Speter After clearing the sticky conflict indicator, you may then commit the 593232785Speter file normally. 593332785Speter 593432785Speter Removing the file and running "update". This throws away the local 593532785Speter changes and accepts the latest committed file on this branch. No 593632785Speter commit is needed. 593732785Speter 593832785Speter Forcing the commit to happen by using "commit -f". This is probably 593932785Speter a mistake since there are few lines of real text that begin with 594032785Speter ">>>>>>> ". 594132785Speter 594232785Speter Last modified: _6/13/1997_ 594332785Speter 594432785Speter 7. Is there a feature to tell me what I have changed, added and removed 594532785Speter without changing anything? 594632785Speter 594732785Speter The command "cvs -n update" will do exactly that. 594832785Speter 594932785Speter Last modified: _6/13/1997_ 595032785Speter 595132785Speter 8. Why were all my files deleted when I executed "update"? 595232785Speter 595332785Speter You probably executed "update -r <tag>" some time ago, then removed 595432785Speter <tag> from the Repository files. "update -r <tag>" will delete a file 595532785Speter that doesn't contain <tag>. 595632785Speter 595732785Speter A way to fix this is to "cd" into your working directory and type: 595832785Speter 595932785Speter cvs update -A 596032785Speter 596132785Speter If you don't want the latest revisions on the Main (or Vendor) Branch, 596232785Speter then decide what Tag (normal or branch) you want and type: 596332785Speter 596432785Speter cvs update -r <the_tag_you_want> 596532785Speter 596632785Speter Another way to make a file disappear is to execute "update -D <date>" 596732785Speter where <date> is before the date stamped onto the first revision in the 596832785Speter RCS file. 596932785Speter 597032785Speter Last modified: _6/13/1997_ 597132785Speter 597232785Speter Category: /Past__Future_/ 597332785Speter 597432785Speter " Past & Future " 597532785Speter 597632785Speter Category: /Past__Future_/Bugs_and_Patches/ 597732785Speter 597832785Speter " + Bugs and Patches" 597932785Speter 598032785Speter 1. Why can't CVS handle deletion of directories? 598132785Speter 598232785Speter An oversight, probably. [[Fixed in a future release?]] 598332785Speter 598432785Speter Last modified: _6/13/1997_ 598532785Speter 598632785Speter 2. Why can't CVS handle the moving of sources from one place in the 598732785Speter 598832785Speter directory hierarchy to another? 598932785Speter 599032785Speter A "renaming database" has been proposed to track the history of 599132785Speter pathname changes in the Repository. A general solution is a difficult 599232785Speter problem. See 4B.8. 599332785Speter 599432785Speter Last modified: _6/13/1997_ 599532785Speter 599632785Speter 3. When I typed "cvs update -D <date>", why did it check out all 599732785Speter 599832785Speter sorts of ancient files from the Attic? Shouldn't it just create the 599932785Speter set of files and revisions that existed at that date? 600032785Speter 600132785Speter This seems to be a bug, but is really the lack of any obvious place to 600232785Speter store the date when a file is "removed". 600332785Speter 600432785Speter There are four ranges of dates that CVS has to deal with when trying 600532785Speter to determine what revision was available on <date>: 600632785Speter 600732785Speter Dates before the earliest revision in the file. 600832785Speter 600932785Speter Dates between any two revisions in the file. 601032785Speter 601132785Speter Dates between the latest revision in the file and the date when the 601232785Speter file was moved to the Attic by "commit". 601332785Speter 601432785Speter Dates after moving the file to the Attic. 601532785Speter 601632785Speter Since the date when a file is moved to the Attic is not stored 601732785Speter anywhere, CVS can't tell the difference between #3 and #4. To avoid 601832785Speter not producing a file that should exist in case #3, it produces 601932785Speter extraneous files in case #4. 602032785Speter 602132785Speter For the above reason, if you have removed files in the Attic, it is 602232785Speter better to use "-r <tag>, or even "-r HEAD" than to use a date spec. 602332785Speter 602432785Speter If you must use "-D <date>", then you should either archive and delete 602532785Speter Attic files (losing some past history) or construct your Makefiles to 602632785Speter work with an explicit list of files and let the old source files stay 602732785Speter in the working directory. The contents of the revision-controlled 602832785Speter Makefile can then be considered to contain deletion "information". 602932785Speter 603032785Speter Last modified: _6/13/1997_ 603132785Speter 603232785Speter 4. When I typed "cvs update -D <date>" in my branch, why did it screw up 603332785Speter all my files? 603432785Speter 603532785Speter Currently, the internal routine ("version_ts") that looks up info 603632785Speter about a file, overrides both the tag and date if *either* the tag or 603732785Speter date is specified on the command line. If only the date is specified, 603832785Speter it should not override a branch tag, but it does. 603932785Speter 604032785Speter In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only works 604132785Speter with the Main Branch and the Vendor Branch. 604232785Speter 604332785Speter [[Is this fixed in CVS 1.4? This is one item I didn't check.]] 604432785Speter 604532785Speter Last modified: _6/13/1997_ 604632785Speter 604732785Speter 5. When I executed "checkout" into an existing directory I got "No such 604832785Speter file or directory" errors. Why? 604932785Speter 605032785Speter Though the man page says that "checkout" turns into an "update -d" in 605132785Speter directories that already exist, it is referring to directories that 605232785Speter already exist *and* were created by CVS. 605332785Speter 605432785Speter When you try to run "checkout" on top of an existing directory 605532785Speter structure, some of which wasn't created by CVS, it will handle 605632785Speter directories and non-CVS files within directories already under CVS, 605732785Speter but it will display the above error on non-CVS files within non-CVS 605832785Speter directories. 605932785Speter 606032785Speter Last modified: _6/13/1997_ 606132785Speter 606232785Speter 6. Why does "update" send all output to the terminal after 26 files have 606332785Speter been updated? 606432785Speter 606532785Speter CVS uses the "tmpnam()" function to generate temporary file names. The 606632785Speter ANSI standard for the "tmpnam()" function says: 606732785Speter 606832785Speter "The tmpnam function generates a different string each time it is 606932785Speter called, up to TMP_MAX times. If it is called more than TMP_MAX times, 607032785Speter the behavior is implementation defined." 607132785Speter 607232785Speter Later it says that the value of "TMP_MAX shall be at least 25." 607332785Speter 607432785Speter On some platforms, the above specification is taken literally by 607532785Speter turning "at least 25" into "exactly 26" and by doing something foolish 607632785Speter (i.e. "implementation defined") after that. Some systems return the 607732785Speter same name repeatedly, which causes one form of trouble. Others return 607832785Speter NULL or garbage, which causes a different form of trouble. 607932785Speter 608032785Speter The broken systems appear to be cycling a single character through the 608132785Speter alphabet. SunOS cycles 3 characters through the alphabet, so it won't 608232785Speter cause trouble until 26 cubed or 17576 calls to "tmpnam()". 608332785Speter 608432785Speter Since CVS doesn't depend on the exact format of the tmp files, the 608532785Speter workaround is to provide a "tmpnam()" that doesn't have a limit on the 608632785Speter number of calls to it. 608732785Speter 608832785Speter Last modified: _6/13/1997_ 608932785Speter 609032785Speter 7. Why does the merge occasionally resurrect lines of code? 609132785Speter 609232785Speter The diff3 program provided by GNU diff version 1.15 has a bug that 609332785Speter occasionally causes text to come back from the dead. 609432785Speter 609532785Speter This is an old problem which you can avoid by upgrading to the latest 609632785Speter GNU "diffutils" package. If you were using GNU diff version 1.15 and 609732785Speter plan to upgrade to the latest GNU diff program, see the next question. 609832785Speter 609932785Speter Last modified: _6/13/1997_ 610032785Speter 610132785Speter 8. Why does the merge fail when my "rcsmerge" program is configured to use 610232785Speter GNU diff version 2.1 or later? 610332785Speter 610432785Speter A change in the overlap format was introduced in GNU diff3 between 610532785Speter versions 2.0 and 2.1 that causes RCS versions before 5.6.0.1 to fail 610632785Speter during a merge. 610732785Speter 610832785Speter To get consistent rcsmerge behavior, you have four choices: 610932785Speter 611032785Speter Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or 5.6. 611132785Speter If you want to use GNU diff 2.1 or later, you'll have to pick one of 611232785Speter the other three choices in this list. 611332785Speter 611432785Speter Grab RCS version 5.6.0.1 from an FSF archive and set the DIFF3_A 611532785Speter macro to '1' as it tells you to in the Makefile: 611632785Speter 611732785Speter #define DIFF3_A 1 611832785Speter 611932785Speter Patch the RCS 5.6 source. Change line 84 in "merger.c" from: 612032785Speter 612132785Speter DIFF3, "-am", "-L", label[0], "-L", label[1], to DIFF3, "-amE", "-L", 612232785Speter label[0], "-L", "", "-L", label[1], 612332785Speter 612432785Speter Wait both for RCS version 5.7 to be released and for a new version 612532785Speter of CVS that can deal with it. 612632785Speter 612732785Speter Last modified: _6/13/1997_ 612832785Speter 612932785Speter Category: /Past__Future_/Contributors/ 613032785Speter 613132785Speter " + Contributors" 613232785Speter 613332785Speter 1. Who wrote CVS? 613432785Speter 613532785Speter Brian Berliner <berliner@sun.com> converted a collection of scripts 613632785Speter written by Dick Grune <dick@cs.vu.nl> into a C program, then added all 613732785Speter sorts of features. He continues to maintain CVS. 613832785Speter 613932785Speter Jeff Polk <polk@bsdi.com> wrote much of the code added between 614032785Speter revisions 1.2 and 1.3. Many others were involved at some level. 614132785Speter 614232785Speter david d zuhn <zoo@armadillo.com> fixed a number of bugs, added some of 614332785Speter the new features, reworked the whole thing to be more portable, and 614432785Speter provided much of the energy to push CVS 1.4 out the door. 614532785Speter 614632785Speter Jim Kingdon implemented CVS 1.5's remote repository access features, 614732785Speter fixed many bugs, and managed the release of version 1.5. 614832785Speter 614932785Speter Take a look at the README and the ChangeLog files in the CVS sources 615032785Speter for more contributors. 615132785Speter 615232785Speter Last modified: _6/13/1997_ 615332785Speter 615432785Speter 2. You didn't write all of this FAQ, did you? 615532785Speter 615632785Speter In the original hunt for questions to answer (performed in Jan/Feb, 615732785Speter 1993), I polled hundreds of people and I rephrased all sorts of text 615832785Speter found on the net. Between 2/93 and 10/93, I released about 20 615932785Speter versions, with corrections and additions from the info-cvs mailing 616032785Speter list and private correspondence. 616132785Speter 616232785Speter Between 10/93 and 10/94 I extracted frequently asked questions from 616332785Speter the 1200 mail messages to the info-cvs mailing list, turned them into 616432785Speter focused questions and tried to answer them. 616532785Speter 616632785Speter 93/02/?? ~4000 lines 93/06/?? ~5000 lines 93/10/23 7839 lines 278K 616732785Speter 94/10/29 9856 lines 360K 95/05/09 9981 lines 365K 616832785Speter 616932785Speter Because there are so many posers of questions, I will list only those 617032785Speter who contribute answers or help significantly with the content and 617132785Speter structure of this document. 617232785Speter 617332785Speter If I used someone else's text verbatim, I mentioned it in the given 617432785Speter answer. The people whose email postings have added to this document or 617532785Speter who have added to my understanding are: 617632785Speter 617732785Speter Brian Berliner <berliner@sun.com>, CVS maintainer. Paul Eggert 617832785Speter <eggert@twinsun.com>, RCS maintainer. 617932785Speter 618032785Speter Gray Watson <gray@antaire.com> Per Cederqvist <ceder@signum.se> Pete 618132785Speter Clark <pclark@is.com> 618232785Speter 618332785Speter all of whom have sent me copies of their tutorials and local CVS 618432785Speter documentation. 618532785Speter 618632785Speter Additional contributors, who have sent me ideas, text, corrections and 618732785Speter support include (in alphabetical order): 618832785Speter 618932785Speter Per Abrahamsen <amanda@iesd.auc.dk> Donald Amby 619032785Speter <amby@mixcom.mixcom.com> Mark D Baushke <mdb@cisco.com> Jim Blandy 619132785Speter <jimb@cyclic.com> Tom Cunningham <tomc@bouwsma,sps.mot.com> Graydon 619232785Speter Dodson <grdodson@lexmark.com> Joe Drumgoole 619332785Speter <joed@splatter.demon.co.uk> Don Dwiggins <dwig@markv.com> Bryant 619432785Speter Eastham <bryant@ced.utah.edu> Dan Franklin <dan@diamond.bbn.com> 619532785Speter Michael Ganzberger <ganzbergermd@ES.net> Steve Harris 619632785Speter <vsh%etnibsd@uunet.uu.net> Erik van Linstee 619732785Speter <linstee@dutecaj.et.tudelft.nl> Jeffrey M Loomis <jml@world.std.com> 619832785Speter Barry Margolin <barmar@near.net> Mark K. Mellis <mkm@ncd.com> Chris 619932785Speter Moore <Chris.Moore@src.bae.co.uk> Gary Oberbrunner <garyo@avs.com> 620032785Speter Steve Turner <stevet@carrier.sps.mot.com> Dave Wolfe 620132785Speter <dwolfe@pffft.sps.mot.com> Dale Woolridge <dwoolridge@cid.aes.doe.ca> 620232785Speter 620332785Speter Please send corrections. If I forgot you, remind me and I'll add your 620432785Speter name to the list. 620532785Speter 620632785Speter Last modified: _6/13/1997_ 620732785Speter 620832785Speter Category: /Past__Future_/Development/ 620932785Speter 621032785Speter " + Development" 621132785Speter 621232785Speter 1. Where do I send bug reports? 621332785Speter 621432785Speter First make sure it is a bug. Talk to your friends, coworkers and 621532785Speter anyone you know who uses CVS. Search this FAQ for related issues. Then 621632785Speter test it carefully. Try out variations to narrow down the problem. Make 621732785Speter sure it is repeatable. Look for workarounds so you can report them. 621832785Speter 621932785Speter If you are still sure it's a bug and you tried to fix it, skip to the 622032785Speter next question. Otherwise, send a message to the info-cvs mailing list 622132785Speter containing one of the following: 622232785Speter 622332785Speter If you have a good repeatable case and you think you know what is 622432785Speter going on, then describe the problem in detail. Include a workaround if 622532785Speter you have one. 622632785Speter 622732785Speter If you have no idea what is going on, go ahead and send a question 622832785Speter to the info-cvs mailing list. Include any information you have 622932785Speter describing the symptoms. 623032785Speter 623132785Speter Last modified: _6/13/1997_ 623232785Speter 623332785Speter 2. Where do I send fixes and patches? 623432785Speter 623532785Speter First make sure the "fix" does something useful. Have someone review 623632785Speter your fix. Spend a bit of one person's time in a detailed analysis of 623732785Speter your vast idea before displaying a half-vast idea to hundreds of 623832785Speter people. 623932785Speter 624032785Speter If you tried to fix it and the patch is small, include the patch in 624132785Speter your message. Make sure the patch is based on the latest released 624232785Speter version of CVS. 624332785Speter 624432785Speter If you tried to fix it and the patch is large, you should think about 624532785Speter why it is so large. Did you add a generally useful feature, or did it 624632785Speter grow out of hand? 624732785Speter 624832785Speter If you still believe it is solid, produce a patch file using the CVS 624932785Speter commands "patch" or "diff -c". [[You *are* keeping CVS under CVS, 625032785Speter right?]] The patch should be based on the latest released version of 625132785Speter CVS. Then use the "cvsbug" program (provided with the CVS sources) to 625232785Speter send it to the CVS maintainers. A self-contained patch that provides a 625332785Speter single useful feature or correction might show up independently in the 625432785Speter patches directory of the FTP archive. 625532785Speter 625632785Speter If careful testing reveals an RCS bug rather than a CVS bug, you can 625732785Speter send bug reports to: rcs-bugs@cs.purdue.edu 625832785Speter 625932785Speter Last modified: _6/13/1997_ 626032785Speter 626132785Speter 3. Where do I send ideas for future development? 626232785Speter 626332785Speter If you have a bright idea, discuss it on the info-cvs mailing list. If 626432785Speter you have the time to implement something you can test, send the diffs 626532785Speter along too as described above. 626632785Speter 626732785Speter Last modified: _6/13/1997_ 626832785Speter 626932785Speter 4. What plans are there for new features? 627032785Speter 627132785Speter 627232785Speter 627332785SpeterA "rename" or "per-directory" database has been bandied about on 627432785Speterthe net for years. Many of the goals of the rename database have 627532785Speterbeen achieved by the so-called "death support" in recent versions of 627632785SpeterCVS (such as 1.9). For more information on what may remain to be 627732785Speterdone, see item #189 in the TODO file of a development version of CVS. 627832785Speter 627932785SpeterCVS version 1.5 supports remote repository access, but Paul 628032785SpeterKunz has produced another version 628132785Speter(rCVS) that also runs remotely. Note that as far as I know there 628232785Speterare no advantages to rCVS over the remote CVS in CVS 1.5 and later, 628332785Speterand the rCVS user community has migrated to remote CVS. 628432785SpeterrCVS is *not* a multisite CVS (see item #186 in TODO for more on 628532785Spetermultisite). For more on rCVS, see 628632785Speter 628732785Speterftp://ftp.slac.stanford.edu/software/rcvs 628832785Speter 628932785Speterkingdon@cyclic.com 629032785Speter 629132785Speter Last modified: _9/6/1997_ 629232785Speter 629332785Speter 5. I have some time and I'd like to help. What can I do for you? 629432785Speter 629532785Speter 629632785Speter You can review this document, correct errors and fill in any of 629732785Speter the incomplete sections. 629832785Speter 629932785Speter You can write scripts or CVS add-ons and make them available by 630032785Speter web/FTP/etc. 630132785Speter 630232785Speter You could work on the regression test suite (src/sanity.sh in the 630332785Speter CVS source distribution). 630432785Speter 630532785Speter You can write specs for new features, fix bugs, review the 630632785Speter documentation or . . . 630732785Speter 630832785Speter For more information, see the files HACKING and DEVEL-CVS in the 630932785Speter CVS source distribution or 631032785Speter http://www.cyclic.com/cyclic-pages/cvsdev.html 631132785Speter 631232785Speter kingdon@cyclic.com 631332785Speter 631432785Speter Last modified: _9/6/1997_ 631532785Speter 631632785Speter Category: /Past__Future_/Professional_Support/ 631732785Speter 631832785Speter " + Professional Support" 631932785Speter 632032785Speter 1. Doesn't Cygnus support CVS? 632132785Speter 632232785Speter 632332785Speter 632432785Speter 632532785Speter Cygnus is a company that supports free software such as the GCC 632632785Speter compiler. They have never sold support for CVS, however. They 632732785Speter do use CVS internally and have contributed much code to CVS over 632832785Speter the years (for which CVS users should be grateful). 632932785Speter 633032785Speter kingdon@cyclic.com 633132785Speter 633232785Speter Last modified: _9/6/1997_ 633332785Speter 633432785Speter 2. What is Cyclic Software doing with CVS? 633532785Speter 633632785Speter 633732785SpeterCyclic Software exists to provide support for CVS. For details such 633832785Speteras prices and what this covers, see http://www.cyclic.com or ask 633932785Speterinfo@cyclic.com. 634032785Speter 634132785Speterkingdon@cyclic.com 634232785Speter 634332785Speter Last modified: _9/6/1997_ 634432785Speter 634532785Speter Category: /User_Tasks_/ 634632785Speter 634732785Speter " User Tasks " 634832785Speter 634932785Speter Category: /User_Tasks_/Common_User_Tasks/ 635032785Speter 635132785Speter " + Common User Tasks" 635232785Speter 635332785Speter 1. What is the absolute minimum I have to do to edit a file? 635432785Speter 635532785Speter Tell your Repository Administrator to create a module covering the 635632785Speter directory or files you care about. You will be told that your module 635732785Speter name is <module>. Then type: 635832785Speter 635932785Speter cvs checkout <module> 636032785Speter cd <module> 636132785Speter emacs <file> # Isn't Emacs a synonym for edit? 636232785Speter cvs commit <file> 636332785Speter 636432785Speter If you don't use modules (in my opinion, a mistake), you can check out 636532785Speter a directory by substituting its relative path within the Repository 636632785Speter for <module> in the example above. 636732785Speter 636832785Speter To work on a single file, you'll have to change "cd <module>" to "cd 636932785Speter `dirname <module>`". 637032785Speter 637132785Speter Last modified: _6/13/1997_ 637232785Speter 637332785Speter 2. If I edit multiple files, must I type "commit" for each one? 637432785Speter 637532785Speter No. You can commit a list of files and directories, including relative 637632785Speter paths into multiple directories. You can also commit every modified 637732785Speter file in the current directory or in all directories and subdirectories 637832785Speter from your current directory downward. See 3D.2. 637932785Speter 638032785Speter Last modified: _6/13/1997_ 638132785Speter 638232785Speter 3. How do I get rid of the <module> directory that "checkout" created? 638332785Speter 638432785Speter Change your directory to be the same as when you executed the 638532785Speter "checkout" command that created <module>. 638632785Speter 638732785Speter If you want to get rid of the CVS control information, but leave the 638832785Speter files and directories, type: 638932785Speter 639032785Speter cvs release <module> 639132785Speter 639232785Speter If you want to obliterate the entire directory, type: 639332785Speter 639432785Speter cvs release -d <module> 639532785Speter 639632785Speter ("release -d" searches through the output of "cvs -n update" and 639732785Speter refuses to continue if the "update" command finds any modified files 639832785Speter or non-ignored foreign files. Foreign directories too.) 639932785Speter 640032785Speter If you don't care about keeping "history", or checking for modified 640132785Speter and foreign files, you can just remove the whole directory. That's "rm 640232785Speter -rf <module>" under Unix. 640332785Speter 640432785Speter Last modified: _6/13/1997_ 640532785Speter 640632785Speter 4. How do I find out what has changed since my last update? 640732785Speter 640832785Speter There are many ways to answer this. 640932785Speter 641032785Speter To find out what you've changed in your current working directory 641132785Speter since your last checkout, update or commit, type: 641232785Speter 641332785Speter cvs diff 641432785Speter 641532785Speter To find out what other people have added (to your branch) since you 641632785Speter last checked out or updated, type: 641732785Speter 641832785Speter cvs diff -r BASE -r HEAD 641932785Speter 642032785Speter To look at a revision history containing the comments for all changes, 642132785Speter you can use the "log" command. 642232785Speter 642332785Speter You can also use "history" to trace a wide variety of events. 642432785Speter 642532785Speter Last modified: _6/13/1997_ 642632785Speter 642732785Speter 5. I just created a new file. How do I add it to the Repository? 642832785Speter 642932785Speter The "update" command will mark files CVS doesn't know about in your 643032785Speter working directory with a '?' indicator. 643132785Speter 643232785Speter ? <file> 643332785Speter 643432785Speter To add <file> to the Repository, type: 643532785Speter 643632785Speter cvs add <file> 643732785Speter cvs commit <file> 643832785Speter 643932785Speter See 3A.[2-5] and 4C.8 for branch and merge considerations. 644032785Speter 644132785Speter Last modified: _6/13/1997_ 644232785Speter 644332785Speter 6. How do I merge changes made by others into my working directory? 644432785Speter 644532785Speter If you are asking about other branches, see Section 4C on "Branching". 644632785Speter You will have to use the "update -j" command. 644732785Speter 644832785Speter Retrieving changes made to the Repository on the *same* branch you are 644932785Speter working on is the main purpose of the "update" command. The "update" 645032785Speter command tries to merge work committed to the Repository by others 645132785Speter since you last executed "checkout", "update" or "commit" into your 645232785Speter working files. 645332785Speter 645432785Speter For a single file, there are six possible results when you type the 645532785Speter "update" command: 645632785Speter 645732785Speter If the file is lying in your working directory, but is not under 645832785Speter CVS, it will do nothing but print: 645932785Speter 646032785Speter ? <file> 646132785Speter 646232785Speter If neither you nor anyone else has committed changes to <file>, 646332785Speter since your last "checkout", "update" or "commit", "update" will print 646432785Speter nothing and do nothing. 646532785Speter 646632785Speter If you have made no changes to a working file, but you or others 646732785Speter have committed changes to the Repository since your last "checkout", 646832785Speter "update" or "commit" of this working file, CVS will remove your 646932785Speter working file and replace it with a copy of the latest revision of that 647032785Speter file in the Repository. It will print: 647132785Speter 647232785Speter U <file> 647332785Speter 647432785Speter You might want to examine the changes (using the CVS "diff" command) 647532785Speter to see if they mesh with your own in related files. 647632785Speter 647732785Speter If you have made changes to a working file, but no one has changed 647832785Speter your BASE revision (the revision you retrieved from the Repository in 647932785Speter your last "checkout", "update" or "commit"), "update" will print: 648032785Speter 648132785Speter M <file> 648232785Speter 648332785Speter Nothing changes. You were told that you have a modified file in your 648432785Speter directory. 648532785Speter 648632785Speter If you have made changes to your working file and you or others have 648732785Speter committed changes to the Repository, but in different sections of the 648832785Speter file, CVS will merge the changes stored in the Repository since your 648932785Speter last "checkout", "update" or "commit" into your working file. "update" 649032785Speter will print: 649132785Speter 649232785Speter RCS file: /Repository/module/<file> retrieving revision 1.X retrieving 649332785Speter revision 1.Y Merging differences between 1.X and 1.Y into <file> M 649432785Speter <file> 649532785Speter 649632785Speter If you execute "diff" before and after this step, you should see the 649732785Speter same output, since both the base file and your working file changed in 649832785Speter parallel. This is one of the few times the otherwise nonsensical 649932785Speter phrase "same difference" means something. 650032785Speter 650132785Speter If both you and those who committed files (since your last checkout, 650232785Speter update or commit) have made changes to the same section of a file, CVS 650332785Speter will merge the changes into your file as in #5 above, but it will 650432785Speter leave conflict indicators in the file. "update" will print: 650532785Speter 650632785Speter RCS file: /Repository/module/<file> retrieving revision 1.X retrieving 650732785Speter revision 1.Y Merging differences between 1.X and 1.Y into <file> 650832785Speter rcsmerge warning: overlaps during merge 650932785Speter cvs update: conflicts found in <file> 651032785Speter C <file> 651132785Speter 651232785Speter This is a "conflict". The file will contain markers surrounding the 651332785Speter overlapping text. The 'C' conflict indicator is sticky -- subsequent 651432785Speter "update" commands will continue to show a 'C' until you edit the file. 651532785Speter 651632785Speter You must examine the overlaps with care and resolve the problem by 651732785Speter analyzing how to retain the features of both changes. See 2D.7 and 651832785Speter 3P.6 for more details on conflict resolution. 651932785Speter 652032785Speter Last modified: _6/13/1997_ 652132785Speter 652232785Speter 7. How do I label a set of revisions so I can retrieve them later? 652332785Speter 652432785Speter To "tag" the BASE revisions (the ones you last checked out, updated, 652532785Speter or committed) you should "cd" to the head of the working directory you 652632785Speter want to tag and type: 652732785Speter 652832785Speter cvs tag <tag> 652932785Speter 653032785Speter It recursively walks through your working directory tagging the BASE 653132785Speter revisions of all files. 653232785Speter 653332785Speter To "tag" the latest revision on the Main branch in the Repository, you 653432785Speter can use the following from anywhere: (No "cd" is required -- it works 653532785Speter directly on the Repository.) 653632785Speter 653732785Speter cvs rtag <tag> <module> 653832785Speter 653932785Speter Last modified: _6/13/1997_ 654032785Speter 654132785Speter 8. How do I checkout an old release of a module, directory or file? 654232785Speter 654332785Speter Module names and directories are simply ways to name sets of files. 654432785Speter Once the names are determined, there are 6 ways to specify which 654532785Speter revision of a particular file to check out: 654632785Speter 654732785Speter By tag or symbolic name, via the "-r <tag>" option. 654832785Speter 654932785Speter By date, via the "-D <date>" option. 655032785Speter 655132785Speter By branch tag (a type of tag with a magic format), via the "-r 655232785Speter <branch_tag>" option. 655332785Speter 655432785Speter By date within a branch, via the "-r <branch_tag>:<date>" option. 655532785Speter 655632785Speter By an explicit branch revision number ("-r <rev>"), which refers to 655732785Speter the latest revision on the branch. This isn't really an "old" 655832785Speter revision, from the branch's perspective, but from the user's 655932785Speter perspective the whole branch might have been abandoned in the past. 656032785Speter 656132785Speter An explicit revision number: "-r <rev>" Though this works, it is 656232785Speter almost useless for more than one file. 656332785Speter 656432785Speter You type: 656532785Speter 656632785Speter cvs checkout <option-specified-above> <module> 656732785Speter cd <module> 656832785Speter 656932785Speter Last modified: _6/13/1997_ 657032785Speter 657132785Speter 9. What do I have to remember to do periodically? 657232785Speter 657332785Speter You should execute "cvs -n update" fairly often to keep track of what 657432785Speter you and others have changed. It won't change anything -- it will just 657532785Speter give you a report. 657632785Speter 657732785Speter Unless you are purposely delaying the inclusion of others' work, you 657832785Speter should execute "update" once in a while and resolve the conflicts. It 657932785Speter is not good to get too far out of sync with the rest of the developers 658032785Speter working on your branch. 658132785Speter 658232785Speter It is assumed that your system administrators have arranged for editor 658332785Speter backup and Unix temp files (#* and .#*) to be deleted after a few 658432785Speter weeks. But you might want to look around for anything else that is 658532785Speter ignored or hidden. Try "cvs -n update -I !" to see all the ignored 658632785Speter files. 658732785Speter 658832785Speter If you are the Repository Administrator, see 4B.16 on Administrator 658932785Speter responsibilities. 659032785Speter 659132785Speter Last modified: _6/13/1997_ 659232785Speter 659332785Speter Category: /User_Tasks_/General_Questions/ 659432785Speter 659532785Speter " + General Questions" 659632785Speter 659732785Speter 1. How do I see what CVS is trying to do? 659832785Speter 659932785Speter The '-t' option on the main "cvs" command will display every external 660032785Speter command (mostly RCS commands and file deletions) it executes. When 660132785Speter combined with the '-n' option, which prevents the execution of any 660232785Speter command that might modify a file, you can see what it will do before 660332785Speter you let it fly. The '-t' option will *not* display every internal 660432785Speter action, only calls to external programs. 660532785Speter 660632785Speter To see a harmless example, try typing: 660732785Speter 660832785Speter cvs -nt update 660932785Speter 661032785Speter Some systems offer a "trace" or "truss" command that will display all 661132785Speter system calls as they happen. This is a *very* low-level interface that 661232785Speter does not normally follow the execution of external commands, but it 661332785Speter can be useful. 661432785Speter 661532785Speter The most complete answer is to read the source, compile it with the 661632785Speter '-g' option and step through it under a debugger. 661732785Speter 661832785Speter Last modified: _6/13/1997_ 661932785Speter 662032785Speter 2. If I work with multiple modules, should I check them all out and commit 662132785Speter them occasionally? Is it OK to leave modules checked out? 662232785Speter 662332785Speter The simple answers are "Yes." 662432785Speter 662532785Speter There is no reason to remove working directories, other than to save 662632785Speter disk space. As long as you have committed the files you choose to make 662732785Speter public, your working directory is just like any other directory. 662832785Speter 662932785Speter CVS doesn't care whether you leave modules checked out or not. The 663032785Speter advantage of leaving them checked out is that you can quickly visit 663132785Speter them to make and commit changes. 663232785Speter 663332785Speter Last modified: _6/13/1997_ 663432785Speter 663532785Speter 3. What is a "sticky" tag? What makes it sticky? How do I loosen it? 663632785Speter 663732785Speter When you execute "update -r <tag>", CVS remembers the <tag>. It has 663832785Speter become "sticky" in the sense that until you change it or remove it, 663932785Speter the tag is remembered and used in references to the file as if you had 664032785Speter typed "-r <tag>" on the command line. 664132785Speter 664232785Speter It is most useful for a <branch_tag>, which is a sticky tag indicating 664332785Speter what branch you are working on. 664432785Speter 664532785Speter A revision number ("-r <rev-number>") or date ("-D <date>") can also 664632785Speter become sticky when they are specified on the command line. 664732785Speter 664832785Speter A sticky tag, revision or date remains until you specify another tag, 664932785Speter revision or date the same way. The "update -A" command moves back to 665032785Speter the Main branch, which has the side-effect of clearing all sticky 665132785Speter items on the updated files. 665232785Speter 665332785Speter The "checkout" command creates sticky tags, revisions and dates the 665432785Speter same way "update" does. 665532785Speter 665632785Speter Also, the '-k' option records a "sticky" keyword option that is used 665732785Speter in further "updates until "update -A" is specified. 665832785Speter 665932785Speter Last modified: _6/13/1997_ 666032785Speter 666132785Speter 4. How do I get an old revision without updating the "sticky tag"? 666232785Speter 666332785Speter Use the '-p' option to "pipe" data to standard output. The command 666432785Speter "update -p -r <tag/rev>" sends the selected revision to your standard 666532785Speter output (usually the terminal, unless redirected). The '-p' affects no 666632785Speter disk files, leaving a "sticky tag" unaltered and avoiding all other 666732785Speter side-effects of a normal "update". 666832785Speter 666932785Speter If you want to save the result, you can redirect "stdout" to a file 667032785Speter using your shell's redirection capability. In most shells the 667132785Speter following command works: 667232785Speter 667332785Speter cvs update -p -r <tag/rev> filename > diskfile 667432785Speter 667532785Speter Last modified: _6/13/1997_ 667632785Speter 667732785Speter 5. What operations disregard sticky tags? 667832785Speter 667932785Speter The functions that routinely disregard sticky tags are: 668032785Speter 668132785Speter Those that work directly on the Repository or its administrative 668232785Speter files: 668332785Speter 668432785Speter admin rtag log status remove history 668532785Speter 668632785Speter Those that take Tags or revisions as arguments and ignore everything 668732785Speter else: (They also never *set* a sticky tag.) 668832785Speter 668932785Speter rdiff import export 669032785Speter 669132785Speter The "release" command itself ignores sticky tags, but it calls "cvs 669232785Speter -n update" (which *does* pay attention to a sticky tag) to figure out 669332785Speter what inconsistencies exist in the working directory. If no 669432785Speter discrepancies exist between the files you originally checked out 669532785Speter (possibly marked by a sticky tag) and what is there now, "release -d" 669632785Speter will delete them all. 669732785Speter 669832785Speter The "tag" command works on the revision lying in the working 669932785Speter directory however it got there. That the revision lying there might 670032785Speter happen to have a sticky tag attached to it is not the "tag" command's 670132785Speter concern. 670232785Speter 670332785Speter The main function that *does* read and write sticky tags is the 670432785Speter "update" command. You can avoid referring to or changing the sticky 670532785Speter tag by using the '-p' option, which sends files to your terminal, 670632785Speter touching nothing else. 670732785Speter 670832785Speter The "checkout" command sets sticky tags when checking out a new module 670932785Speter and it acts like "update" when checking out a module into an existing 671032785Speter directory. 671132785Speter 671232785Speter The "diff" and "commit" commands use the sticky tags, unless 671332785Speter overridden on the command line. They do not set sticky tags. Note that 671432785Speter you can only "commit" to a file checked out with a sticky tag, if the 671532785Speter tag identifies a branch. 671632785Speter 671732785Speter There are really two types of sticky tags, one attached to individual 671832785Speter files (in the ./CVS/Entries file) and one attached to each directory 671932785Speter (in the ./CVS/Tag file). They can differ. 672032785Speter 672132785Speter The "add" command registers the desire to add a new file. If the 672232785Speter "directory tag" (./CVS/Tag) file exists at the time of the "add", the 672332785Speter value stored in ./CVS/Tag becomes the "sticky tag" on the new file. 672432785Speter The file doesn't exist in the Repository until you "commit" it, but 672532785Speter the ./CVS/Entries file holds the sticky tag name from the time of the 672632785Speter "add" forward. 672732785Speter 672832785Speter Last modified: _6/13/1997_ 672932785Speter 673032785Speter 6. Is there a way to avoid reverting my Emacs buffer after committing a 673132785Speter file? Is there a "cvs-mode" for Emacs? 673232785Speter 673332785Speter See Section 4F.1 673432785Speter 673532785Speter Last modified: _6/13/1997_ 673632785Speter 673732785Speter 7. How does conflict resolution work? What *really* happens if two of us 673832785Speter change the same file? 673932785Speter 674032785Speter While editing files, there is no conflict. You are working on separate 674132785Speter copies of the file stored in the virtual "branch" represented by your 674232785Speter working directories. After one of you commits a file, the other may 674332785Speter not commit the same file until "update" has merged the earlier 674432785Speter committed changes into the later working file. 674532785Speter 674632785Speter For example, say you both check out rev 1.2 of <file> and make change 674732785Speter to your working files. Your coworker commits revision 1.3. When you 674832785Speter try to commit your file, CVS says: 674932785Speter 675032785Speter cvs commit: Up-to-date check failed for `<file>' 675132785Speter 675232785Speter You must merge your coworker's changes into your working file by 675332785Speter typing: 675432785Speter 675532785Speter cvs update <file> 675632785Speter 675732785Speter which will produce the output described in 2B.6. 675832785Speter 675932785Speter If a conflict occurs, the filename will be shown with a status of 'C'. 676032785Speter After you resolve any overlaps caused by the merging process, you may 676132785Speter then commit the file. See 3P.6 for info on "sticky conflicts". 676232785Speter 676332785Speter Even if you get a simple 'M', you should examine the differences 676432785Speter before committing the file. A smooth, error-free text merge is still 676532785Speter no indication that the file is in proper shape. Compile and test it at 676632785Speter least. 676732785Speter 676832785Speter The answer to two obvious questions is "Yes". 676932785Speter 677032785Speter Yes, the first one who commits avoids the merge. Later developers have 677132785Speter to merge the earlier changes into their working files before 677232785Speter committing the merged result. Depending on how difficult the merge is 677332785Speter and how important the contending projects are, the order of commits 677432785Speter and updates might have to be carefully staged. 677532785Speter 677632785Speter And yes, between the time you execute "update" and "commit" (while you 677732785Speter are fixing conflicts and testing the results) someone else may commit 677832785Speter another revision of <file>. You will have to execute "update" again to 677932785Speter merge the new work before committing. Most organizations don't have 678032785Speter this problem. If you do, you might consider splitting the file. Or 678132785Speter hiring a manager. 678232785Speter 678332785Speter Last modified: _6/13/1997_ 678432785Speter 678532785Speter 8. How can I tell who has a module checked out? 678632785Speter 678732785Speter If you "checkout" module names (not relative pathnames) and you use 678832785Speter the release command, the "history" command will display active 678932785Speter checkouts, who has them and where they were checked out. It is 679032785Speter advisory only; it can be circumvented by using the '-l' option on the 679132785Speter main "cvs" command. 679232785Speter 679332785Speter Last modified: _6/13/1997_ 679432785Speter 679532785Speter 9. Where did the .#<file>.1.3 file in my working directory come from? 679632785Speter 679732785Speter It was created during an "update" when CVS merged changes from the 679832785Speter Repository into your modified working file. 679932785Speter 680032785Speter It serves the same purpose as any "backup" file: saving your bacon 680132785Speter often enough to be worth retaining. It is invaluable in recovering 680232785Speter when things go wrong. 680332785Speter 680432785Speter Say Developers A (you) and B check out rev 1.3 of file <file>. You 680532785Speter both make changes -- different changes. B commits first, so <file>,v 680632785Speter in the Repository contains revisions up through 1.4. 680732785Speter 680832785Speter At this point, there are 5 (yes, five) versions of the file of 680932785Speter interest to you: 681032785Speter 681132785Speter Revision 1.3 (What you originally checked out.) 681232785Speter 681332785Speter Revision 1.4 (What you need from developer B.) 681432785Speter 681532785Speter Your old working file. (Before the update.) 681632785Speter 681732785Speter Your new working file. (After the merge caused by "update".) 681832785Speter 681932785Speter Revision 1.5 (Which you will commit shortly.) 682032785Speter 682132785Speter In the case where your working file was not modified, #1 and #3 will 682232785Speter be the same, as will #2 and #4. In this degenerate case, there is no 682332785Speter need to create #5. The following assumes that your working file was 682432785Speter modified. 682532785Speter 682632785Speter If the merge executed by the "update" caused no overlaps, and you 682732785Speter commit the file immediately, #4 and #5 will be the same. But you can 682832785Speter make arbitrary changes before committing, so the difference between #4 682932785Speter and #5 might be more than just the correction of overlaps. In general, 683032785Speter though, you don't need #4 after a commit. 683132785Speter 683232785Speter But #3 (which is the one saved as ".#<file>.1.3") holds all of your 683332785Speter work, independent of B's work. It could represent a major effort that 683432785Speter you couldn't afford to lose. If you don't save it somewhere, the merge 683532785Speter makes #3 *disappear* under a potential blizzard of conflicts caused by 683632785Speter overlapping changes. 683732785Speter 683832785Speter I have been saved a few times, and others I support have been saved 683932785Speter hundreds of times, by the ability to "diff <original file> <original 684032785Speter file with only my work added>", which can be done in the example above 684132785Speter by the Unix shell command: 684232785Speter 684332785Speter cvs update -p -r 1.3 <file> | diff - .#<file>.1.3 684432785Speter 684532785Speter The assumption is that the ".#" files will be useful far beyond the 684632785Speter "commit" point, but not forever. You are expected to run the "normal" 684732785Speter Unix cleanup script from "cron", which removes "#*" and ".#*" files 684832785Speter older than a some period chosen by your sysadmin, usually ranging from 684932785Speter 7 to 30 days. 685032785Speter 685132785Speter A question was raised about the need for #3 after #5 has been 685232785Speter committed, under the assumption that you won't commit files until 685332785Speter everything is exactly as you like them. 685432785Speter 685532785Speter This assumes perfect humans, which violates one of the Cardinal rules 685632785Speter of Software Engineering: Never assume any form of discipline on the 685732785Speter part of the users of software. If restrictions are not bound into the 685832785Speter software, then you, the toolsmith, have to arrange a recovery path. 685932785Speter 686032785Speter In other words, I've seen every possible variety of screwup you can 686132785Speter imagine in #5. There is no way to make assumptions about what "should" 686232785Speter happen. I've seen #5 filled with zeros because of NFS failures, I've 686332785Speter seen emacs core dumps that leave #5 in an unreasonable state, I've 686432785Speter seen a foolish developer uppercase the whole file (with his "undo" 686532785Speter size set low so he couldn't undo it) and decide that it would be less 686632785Speter work to play with the uppercased file than to blow it away and start 686732785Speter over. I've even seen committed files with conflict markers still in 686832785Speter them, a sure sign of carelessness. 686932785Speter 687032785Speter There are all sorts of scenarios where having #3 is incredibly useful. 687132785Speter You can move it back into place and try again. 687232785Speter 687332785Speter Last modified: _6/13/1997_ 687432785Speter 687532785Speter 10. What is this "ignore" business? What is it ignoring? 687632785Speter 687732785Speter The "update" and "import" commands use collections of Unix wildcards 687832785Speter to skip over files and directories matching any of those patterns. 687932785Speter 688032785Speter You may add to the built-in ignore list by adding lines of 688132785Speter whitespace-separated wildcards to the following places: (They are read 688232785Speter in this order.) 688332785Speter 688432785Speter In a file named "cvsignore" in $CVSROOT/CVSROOT. 688532785Speter 688632785Speter A Repository Administrator uses this to add site-specific files and 688732785Speter patterns to the built-in ignore list. 688832785Speter 688932785Speter In a file named ".cvsignore" in your home directory. 689032785Speter 689132785Speter For user-specific files. For example, if you use "__" as your default 689232785Speter junk file prefix, you can put "__*" in your .cvsignore file. 689332785Speter 689432785Speter People who play around exclusively in directory trees where the 689532785Speter Makefiles are generated by "imake" or "configure" might want to put 689632785Speter "Makefile" in their ignore list, since they are all generated and 689732785Speter usually don't end up in the Repository. 689832785Speter 689932785Speter In the CVSIGNORE environment variable. 690032785Speter 690132785Speter For session-specific files. 690232785Speter 690332785Speter Via the '-I' option on "import" or "update" commands. 690432785Speter 690532785Speter For this-command-only files. 690632785Speter 690732785Speter In a file named ".cvsignore" within each directory. 690832785Speter 690932785Speter The contents of a ".cvsignore" file in each directory is temporarily 691032785Speter added to the ignore list. This way you can ignore files that are 691132785Speter peculiar to that directory, such as executables and other generated 691232785Speter files without known wildcard patterns. 691332785Speter 691432785Speter In any of the places listed above, a single '!' character nulls out 691532785Speter the ignore list. A Repository administrator can use this to override, 691632785Speter rather than enhance, the built-in ignore list. A user can choose to 691732785Speter override the system-wide ignore list. For example, if you place "! *.o 691832785Speter *.a" in your .cvsignore file, only *.o *.a files, plus any files a 691932785Speter local-directory .cvsignore file, are ignored. 692032785Speter 692132785Speter A variant of the ignore-file scheme is used internally during 692232785Speter checkout. "Module names" found in the modules file (or on the 692332785Speter "checkout" command line) that begin with a '!' are ignored during 692432785Speter checkout. This is useful to permanently ignore (if the '!' path is in 692532785Speter the modules file) or temporarily ignore (if the '!' path is on the 692632785Speter command line) a sub-directory within a Repository hierarchy. For 692732785Speter example: 692832785Speter 692932785Speter cvs checkout !gnu/emacs/tests gnu/emacs 693032785Speter 693132785Speter would checkout the module (or relative path within $CVSROOT) named 693232785Speter "gnu/emacs", but ignore the "tests" directory within it. 693332785Speter 693432785Speter Last modified: _6/13/1997_ 693532785Speter 693632785Speter 11. Is there a way to set user-specific configuration options? 693732785Speter 693832785Speter User-specific configuration is available through use of a ".cvsrc" 693932785Speter file in your home directory. 694032785Speter 694132785Speter CVS searches the first column of your ~/.cvsrc file for the cvs 694232785Speter command name you invoked. If the command is found, the rest of the 694332785Speter line is treated like a set of command line options, stuffed into the 694432785Speter command line before the arguments you actually typed. 694532785Speter 694632785Speter For example, if you always want to see context diffs and you never 694732785Speter want to have to delete a file before you run "cvs remove", then you 694832785Speter should create a .cvsrc file containing the following: 694932785Speter 695032785Speter diff -c 695132785Speter remove -f 695232785Speter 695332785Speter which will add the given options to every invocation of the given 695432785Speter commands. 695532785Speter 695632785Speter [[The rest of this will be removed someday, when CVS changes.]] 695732785Speter 695832785Speter I would like to stop here with a comment that the command name to use 695932785Speter is the full, canonical one. But the command that the cvsrc support 696032785Speter uses is the string you typed on the command line, not the proper 696132785Speter command. So to get the full effect of the above example, you should 696232785Speter also add all the alternate command names: 696332785Speter 696432785Speter di -c 696532785Speter dif -c 696632785Speter rm -f 696732785Speter delete -f 696832785Speter 696932785Speter There are two other limitations that will probably be fixed when CVS 697032785Speter sprouts long option names: 697132785Speter 697232785Speter It only affects options made available on the command line. 697332785Speter 697432785Speter There is a limited number of short options. With long option names, 697532785Speter there is no problem. You can have as many long options as you like, 697632785Speter affecting anything that looks malleable. 697732785Speter 697832785Speter The existing command line options do not come in on/off pairs, so 697932785Speter there is no easy way to override your ~/.cvsrc configuration for a 698032785Speter single invocation of a command. 698132785Speter 698232785Speter Choosing a good set of long option pairs would fix this. 698332785Speter 698432785Speter Last modified: _6/13/1997_ 698532785Speter 698632785Speter 12. Is it safe to interrupt CVS using Control-C? 698732785Speter 698832785Speter It depends on what you mean by "safe". ("Ah," said Arthur, "this is 698932785Speter obviously some strange usage of the word *safe* that I wasn't 699032785Speter previously aware of." -- Hitchhiker's Guide to the Galaxy) 699132785Speter 699232785Speter You won't hurt the underlying RCS files and if you are executing a 699332785Speter command that only *reads* data, you will have no cleanup to do. 699432785Speter 699532785Speter But you may have to hit Control-C repeatedly to stop it. CVS uses the 699632785Speter Unix "system" routine which blocks signals in the CVS parent process. 699732785Speter A single Control-C during "system" will only halt the child process, 699832785Speter usually some form of RCS command. 699932785Speter 700032785Speter If you don't hit another Control-C while the CVS process has control, 700132785Speter it is likely to continue onto the next task assuming that the earlier 700232785Speter one did its job. It is not enough to hit two Control-C's. You might 700332785Speter simply kill two child processes and not interrupt CVS at all. 700432785Speter Depending on the speed of your processor, your terminal and your 700532785Speter fingers, you might have to hit dozens of Control-C's to stop the damn 700632785Speter thing. 700732785Speter 700832785Speter Executing a CVS command, such as "commit" or "tag" that writes to the 700932785Speter files is a different matter. 701032785Speter 701132785Speter Since CVS is not a full-fledged database, with what database people 701232785Speter call "commit points", merely stopping the process will not back out 701332785Speter the "transaction" and place you back in the starting blocks. CVS has 701432785Speter no concept of an "atomic" transaction or of "backtracking", which 701532785Speter means that a command can be half-executed. 701632785Speter 701732785Speter Hitting Control-C will usually leave lock files that you have to go 701832785Speter clean up in the Repository. 701932785Speter 702032785Speter Example1: 702132785Speter 702232785Speter If you interrupt a multi-file "commit" in the middle of 702332785Speter an RCS checkin, RCS will leave the file either fully 702432785Speter checked-in or in its original state. But CVS might have 702532785Speter been half-way through the list of files to commit. The 702632785Speter directory or module will be inconsistent. 702732785Speter 702832785Speter To recover, you must remove the lock files, then decide 702932785Speter whether you want to back out or finish the job. 703032785Speter 703132785Speter To back out, you'll have to apply the "admin -o" 703232785Speter command, very carefully, to remove the newly committed 703332785Speter revisions. This is usually a bad idea, but is 703432785Speter occasionally necessary. 703532785Speter 703632785Speter To finish, you can simply retype the same commit command. 703732785Speter CVS will figure out what files are still modified and 703832785Speter commit them. It helps that RCS doesn't leave a file in an 703932785Speter intermediate state. 704032785Speter 704132785Speter Example2: 704232785Speter 704332785Speter If you interrupt a multi-file "tag" command, you have a 704432785Speter problem similar, but not equivalent, to interrupting a 704532785Speter "commit". The RCS file will still be consistent, but 704632785Speter unlike "commit", which only *adds* to the RCS file, "tag" 704732785Speter can *move* a tag and it doesn't keep a history of what 704832785Speter revision a tag used to be attached to. 704932785Speter 705032785Speter Normally, you have little choice but to re-execute the 705132785Speter command and allow it to tag everything consistently. 705232785Speter 705332785Speter You might be able to recover by carefully re-applying the 705432785Speter tags via the "cvs admin -N" command, but you'll still have 705532785Speter to dig up from outside sources the information you use to 705632785Speter determine what tag was on what revision in what file. 705732785Speter the Repository, or by using the equivalent: "cvs admin". 705832785Speter 705932785Speter Halting a new "checkout" should cause no harm. If you don't want it, 706032785Speter "release" (or rm -rf) it. If you do want it, re-execute the command. A 706132785Speter repeated "checkout" from above a directory acts like a repeated 706232785Speter "update -d" within it. 706332785Speter 706432785Speter Halting "update" half-way will give you an unpredictable collection of 706532785Speter files and revisions. To continue, you can rerun the update and it 706632785Speter should move you forward into in a known state. To back out, you'll 706732785Speter have to examine the output from the first "update" command, take a 706832785Speter look at each file that was modified and reconstruct the previous state 706932785Speter by editing the ./CVS/Entries file and by using "cvs admin". Good Luck. 707032785Speter 707132785Speter Last modified: _6/13/1997_ 707232785Speter 707332785Speter 13. How do I turn off the "admin" command? 707432785Speter 707532785Speter In the current revision, you'd have to edit the source code. 707632785Speter 707732785Speter Last modified: _6/13/1997_ 707832785Speter 707932785Speter 14. How do I turn off the ability to disable history via "cvs -l"? 708032785Speter 708132785Speter In the current revision, you'd have to edit the source code. 708232785Speter 708332785Speter Last modified: _6/13/1997_ 708432785Speter 708532785Speter 15. How do I keep certain people from accessing certain directories? 708632785Speter 708732785Speter If you don't try to run CVS set[ug]id, you can use Unix groups and 708832785Speter permissions to limit access to the Repository. 708932785Speter 709032785Speter If you only want to limit "commit" commands, you can write a program 709132785Speter to put in the "commitinfo" file. In the "contrib" directory, there are 709232785Speter a few scripts that might help you out. 709332785Speter 709432785Speter Last modified: _6/13/1997_ 709532785Speter 709632785Speter Category: /User_Tasks_/Getting_Started/ 709732785Speter 709832785Speter " + Getting Started" 709932785Speter 710032785Speter 1. What is the first thing I have to know? 710132785Speter 710232785Speter Your organization has most likely assigned one or more persons to 710332785Speter understand, baby-sit and administer the CVS programs and the data 710432785Speter Repository. I call these persons Repository Administrators. They 710532785Speter should have set up a Repository and "imported" files into it. 710632785Speter 710732785Speter If you don't believe anyone has this responsibility, or you are just 710832785Speter testing CVS, then *you* are the Repository Administrator. 710932785Speter 711032785Speter If you are a normal user of CVS ask your Repository Administrator what 711132785Speter module you should check out. 711232785Speter 711332785Speter Then you can work. 711432785Speter 711532785Speter If you *are* the Repository Administrator, you will want to read 711632785Speter everything you can get your hands on, including this FAQ. Source 711732785Speter control issues can be difficult, especially when you get to branches 711832785Speter and release planning. Expect to feel stupid for a few days/weeks. 711932785Speter 712032785Speter No tool in the universe avoids the need for intelligent organization. 712132785Speter In other words, there are all sorts of related issues you will 712232785Speter probably have to learn. Don't expect to dive in without any 712332785Speter preparation, stuff your 300 Megabytes of sources into CVS and expect 712432785Speter to start working. If you don't prepare first, you will probably spend 712532785Speter a few sleepless nights. 712632785Speter 712732785Speter Last modified: _6/13/1997_ 712832785Speter 712932785Speter 2. Where do I work? 713032785Speter 713132785Speter Wherever you have disk space. That's one of the advantages of CVS: you 713232785Speter use the "checkout" command to copy files from the Repository to your 713332785Speter working directory, which can be anywhere you have the space. 713432785Speter 713532785Speter Your local group might have conventions for where to work. Ask your 713632785Speter peers. 713732785Speter 713832785Speter Last modified: _6/13/1997_ 713932785Speter 714032785Speter 3. What does CVS use from my environment? 714132785Speter 714232785Speter You must set two environment variables. Some shells share these 714332785Speter variables with local shell variables using a different syntax. You'll 714432785Speter have to learn how your shell handles them. 714532785Speter 714632785Speter Variable Value (or action) 714732785Speter --------- --------------------- 714832785Speter CVSROOT Absolute pathname of the head of your Repository. 714932785Speter 715032785Speter PATH Normally set to a list of ':'-separated directory 715132785Speter pathnames searched to find executables. You must 715232785Speter make sure "cvs" is in one of the directories. 715332785Speter 715432785Speter If your CVS was built with the RCSBIN directory set 715532785Speter to null (""), and you don't set the RCSBIN 715632785Speter variable mentioned below, then the RCS commands 715732785Speter also must be somewhere in your PATH. 715832785Speter 715932785Speter Optional variables: (Used if set, but ignored otherwise.) 716032785Speter 716132785Speter Variable Value (or action) 716232785Speter --------- --------------------- 716332785Speter CVSEDITOR The name of your favorite fast-start editor 716432785Speter program. You'll be kicked into your editor to 716532785Speter supply revision comments if you don't specify them 716632785Speter via -m "Log message" on the command line. 716732785Speter 716832785Speter EDITOR Used if CVSEDITOR doesn't exist. If EDITOR 716932785Speter doesn't exist, CVS uses a configured constant, 717032785Speter usually, "vi". 717132785Speter 717232785Speter CVSREAD Sets files to read-only on "checkout". 717332785Speter 717432785Speter RCSBIN Changes where CVS finds the RCS commands. 717532785Speter 717632785Speter CVSIGNORE Adds to the ignore list. See Section 2D. 717732785Speter 717832785Speter Other variables used by CVS that are normally set upon login: 717932785Speter 718032785Speter Variable Value (or action) 718132785Speter --------- --------------------- 718232785Speter LOGNAME Used to find the real user name. 718332785Speter 718432785Speter USER Used to find the real user name if no LOGNAME. 718532785Speter 718632785Speter HOME Used to determine your home directory, if set. 718732785Speter Otherwise LOGNAME/USER/getuid() are used to find 718832785Speter your home directory from the passwd file. 718932785Speter 719032785Speter TMPDIR Used during import. It might also be used if your 719132785Speter platform's version of mktemp(3) is unusual, or 719232785Speter you have changed the source to use tmpnam(3). 719332785Speter 719432785Speter Last modified: _6/13/1997_ 719532785Speter 719632785Speter 4. OK, I've been told that CVS is set up, my module is named "ralph" and I 719732785Speter have to start editing. What do I type? 719832785Speter 719932785Speter cd <where you have some space to work> 720032785Speter cvs checkout ralph 720132785Speter cd ralph 720232785Speter 720332785Speter And hack away. 720432785Speter 720532785Speter Last modified: _6/13/1997_ 720632785Speter 720732785Speter 5. I have been using RCS for a while. Can I convert to CVS without losing 720832785Speter my revision history? How about converting from SCCS? 720932785Speter 721032785Speter If you are asking such questions, you are not a mere user of CVS, but 721132785Speter one of its Administrators! You should take a look at Section 4A, 721232785Speter "Installing CVS" and Section 4B, "Setting up and Managing the 721332785Speter Repository". 721432785Speter 721532785Speter Last modified: _6/13/1997_ 721632785Speter 721732785Speter Category: /User_Tasks_/Less_Common_User_Tas/ 721832785Speter 721932785Speter " + Less Common User Tasks" 722032785Speter 722132785Speter 1. Can I create non-CVS sub-directories in my working directory? 722232785Speter 722332785Speter Yes. Unless the directory exists in the Repository, "update" will skip 722432785Speter over them and print a '?' the way it does for files you forgot to add. 722532785Speter You can avoid seeing the '?' by adding the name of the foreign 722632785Speter directory to the ./.cvsignore file, just ask you can do with files. 722732785Speter 722832785Speter If you explicitly mention a foreign directory on the "update" command 722932785Speter line, it will traverse the directory and waste a bit of time, but if 723032785Speter any directory or sub-directory lacks the ./CVS administrative 723132785Speter directory, CVS will print an error and abort. 723232785Speter 723332785Speter Last modified: _6/13/1997_ 723432785Speter 723532785Speter 2. How do I add new sub-directories to the Repository? 723632785Speter 723732785Speter The "add" command will work on directories. You type: 723832785Speter 723932785Speter mkdir <dir> 724032785Speter cvs add <dir> 724132785Speter 724232785Speter It will respond: 724332785Speter 724432785Speter Directory /Repos/<dir> added to the repository 724532785Speter 724632785Speter and will create both a matching directory in the Repository and a 724732785Speter ./CVS administrative directory within the local <dir> directory. 724832785Speter 724932785Speter Last modified: _6/13/1997_ 725032785Speter 725132785Speter 3. How do I remove a file I don't need? 725232785Speter 725332785Speter (See the questions in Section 4B on removing files from the 725432785Speter Repository.) 725532785Speter 725632785Speter You type: 725732785Speter 725832785Speter rm <file> 725932785Speter cvs remove <file> 726032785Speter 726132785Speter CVS registers the file for removal. To complete the removal, you must 726232785Speter type: 726332785Speter 726432785Speter cvs commit <file> 726532785Speter 726632785Speter CVS moves the file to the Attic associated with your working 726732785Speter directory. Each directory in the Repository stores its deleted files 726832785Speter in an Attic sub-directory. A normal "checkout" doesn't look in the 726932785Speter Attic, but if you specify a tag, a date or a revision, the "checkout" 727032785Speter (or "update") command will retrieve files from the Attic with that 727132785Speter tag, date or revision. 727232785Speter 727332785Speter Last modified: _6/13/1997_ 727432785Speter 727532785Speter 4. How do I rename a file? 727632785Speter 727732785Speter CVS does not offer a way to rename a file in a way that CVS can track 727832785Speter later. See Section 4B for more information. 727932785Speter 728032785Speter Here is the best (to some, the only acceptable) way to get the effect 728132785Speter of renaming, while preserving the change log: 728232785Speter 728332785Speter Copy the RCS (",v") file directly in the Repository. 728432785Speter 728532785Speter cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v 728632785Speter 728732785Speter By duplicating the file, you will preserve the change history and the 728832785Speter ability to retrieve earlier revisions of the old file via the "-r 728932785Speter <tag/rev>" or "-D <date>" options to "checkout" and "update". 729032785Speter 729132785Speter Remove the old file using CVS. 729232785Speter 729332785Speter cd <working-dir>/<odir> rm <ofile> 729432785Speter cvs remove <ofile> 729532785Speter cvs commit <ofile> 729632785Speter 729732785Speter This will move the <ofile> to the Attic associated with <odir>. 729832785Speter 729932785Speter Retrieve <nfile> and remove all the Tags from it. 730032785Speter 730132785Speter By stripping off all the old Tags, "checkout -r" and "update -r" won't 730232785Speter retrieve revisions Tagged before the renaming. 730332785Speter 730432785Speter cd <working-dir>/<ndir> 730532785Speter cvs update <nfile> 730632785Speter cvs log <nfile> # Save the list of Tags 730732785Speter cvs tag -d <tag1> <nfile> 730832785Speter cvs tag -d <tag2> <nfile> 730932785Speter . . . 731032785Speter 731132785Speter This technique can be used to rename files within one directory or 731232785Speter across different directories. You can apply this idea to directories 731332785Speter too, as long as you apply the above to each file and don't delete the 731432785Speter old directory. 731532785Speter 731632785Speter Of course, you have to change your build system (e.g. Makefile) in 731732785Speter your <working-dir> to know about the name change. 731832785Speter 731932785Speter Warning: Stripping the old tags from the copied file will allow "-r 732032785Speter <tag>" to do the right thing, but you will still have problems with 732132785Speter "-D <date>" because there is no place to store the "deletion time". 732232785Speter See 5B.3 for more details. 732332785Speter 732432785Speter Last modified: _6/13/1997_ 732532785Speter 732632785Speter 5. How do I make sure that all the files and directories in my working 732732785Speter directory are really in the Repository? 732832785Speter 732932785Speter A "cvs update", or "cvs -n update" (which won't modify your working 733032785Speter directory) will display foreign elements, which have no counterpart in 733132785Speter the Repository, preceded by a '?'. To register foreign directories, 733232785Speter you can use "cvs add". To register foreign files, you can use "cvs 733332785Speter add" followed by "cvs commit". 733432785Speter 733532785Speter You could also checkout your module, or the Repository directory 733632785Speter associated with your working directory, a second time into another 733732785Speter work area and compare it to your working directory using the (non-CVS) 733832785Speter "diff -r" command. 733932785Speter 734032785Speter By default many patterns of files are ignored. If you create a file 734132785Speter named "core" or a file ending in ".o", it is usually ignored. If you 734232785Speter really want to see all the files that aren't in the Repository, you 734332785Speter can use a special "ignore" pattern to say "ignore no files". Try 734432785Speter executing: (You may have to quote or backwhack (i.e. precede by '\') 734532785Speter the '!' in your shell.) 734632785Speter 734732785Speter cvs -n update -I ! 734832785Speter 734932785Speter The above command will display not only the normal modified, update 735032785Speter and conflict indicators ('M', 'U', and 'C' respectively) on files 735132785Speter within the Repository, but it will also display each file not in the 735232785Speter Repository preceded by a '?' character. 735332785Speter 735432785Speter The '-n' option will not allow "update" to alter your working 735532785Speter directory. 735632785Speter 735732785Speter Last modified: _6/13/1997_ 735832785Speter 735932785Speter 6. How do I create a branch? 736032785Speter 736132785Speter Type this in your working directory: 736232785Speter 736332785Speter cvs tag -b <branch_tag> 736432785Speter 736532785Speter and you will create a branch. No files have real branches in them yet, 736632785Speter but if you move onto the branch by typing: 736732785Speter 736832785Speter cvs update -r <branch_tag> 736932785Speter 737032785Speter and commit a file in the normal way: 737132785Speter 737232785Speter cvs commit <file> 737332785Speter 737432785Speter then a branch will be created in the underlying <file>,v file and the 737532785Speter new revision of <file> will appear only on that branch. 737632785Speter 737732785Speter See Section 4C, on Branching. 737832785Speter 737932785Speter Last modified: _6/13/1997_ 738032785Speter 738132785Speter 7. How do I modify the modules file? How about the other files in the 738232785Speter CVSROOT administrative area? 738332785Speter 738432785Speter A module named "modules" has been provided in the default modules 738532785Speter file, so you can type: 738632785Speter 738732785Speter cvs checkout modules 738832785Speter cd modules 738932785Speter 739032785Speter Another module named CVSROOT has been provided in the default modules 739132785Speter file, covering all the administrative files. Type: 739232785Speter 739332785Speter cvs checkout CVSROOT 739432785Speter cd CVSROOT 739532785Speter 739632785Speter Then you can edit your files, followed by: 739732785Speter 739832785Speter cvs commit 739932785Speter 740032785Speter If you start with the provided template for the "modules" file, the 740132785Speter CVSROOT and the "modules" module will have the "mkmodules" program as 740232785Speter a "commit helper". After a file is committed to such a module, 740332785Speter "mkmodules" will convert a number of standard files (See 4B.2) in the 740432785Speter CVSROOT directory inside the Repository into a form that is usable by 740532785Speter CVS. 740632785Speter 740732785Speter Last modified: _6/13/1997_ 740832785Speter 740932785Speter 8. How do I split a file into pieces, retaining revision histories? 741032785Speter 741132785Speter If you and a coworker find yourselves repeatedly committing the same 741232785Speter file, but never for changes in the same area of the file, you might 741332785Speter want to split the file into two or more pieces. If you are both 741432785Speter changing the same section of code, splitting the file is of no use. 741532785Speter You should talk to each other instead. 741632785Speter 741732785Speter If you decide to split the file, here's a suggestion. In many ways, it 741832785Speter is similar to multiple "renamings" as described in 2C.4 above. 741932785Speter 742054427Speter Say you want to split , which already in the Repository, into three 742154427Speter pieces, , and . 742232785Speter 742332785Speter Copy the RCS (",v") files directly in the Repository, creating the 742432785Speter new files, then bring readable copies of the new files into the 742532785Speter working directory via "update". 742632785Speter 742754427Speter cp $CVSROOT//,v $CVSROOT//,v cp $CVSROOT//,v $CVSROOT//,v 742854427Speter cvs update 742932785Speter 743054427Speter Then remove all the from the new files, either using: 743132785Speter 743254427Speter cvs log # Save the list of 743354427Speter cvs tag -d 743454427Speter cvs tag -d 743532785Speter . . . 743632785Speter 743754427Speter (eivind@freebsd.org) or using the following little script to 743854427Speter autmatically remove the tags directly from the repository files: 743954427Speter 744054427Speter#!/bin/sh 744154427Speterfor file in $* 744254427Speterdo 744354427Speter TAGS=`rlog $file | awk '/^symbolic names:/,/^keyword subst/' | awk 'BEG 744454427SpeterIN {FS=":"} /^\t/ {print $1}'` 744554427Speter echo The tags in $file are 744654427Speter echo $TAGS 744754427Speter echo Is it OK to remove these? 744854427Speter read confirm 744954427Speter if [ "$confirm" = "y" -o "$confirm" = "yes" ] 745054427Speter then 745154427Speter for tag in $TAGS 745254427Speter do 745354427Speter echo Removing $file:$tag 745454427Speter rcs -n$tag $file 745554427Speter done 745654427Speter fi 745754427Speterdone 745854427Speter 745932785Speter Edit each file until it has the data you want in it. This is a 746032785Speter hand-editing job, not something CVS can handle. Then commit all the 746132785Speter files. 746232785Speter 746332785Speter [From experience, I'd suggest making sure that only one copy of each 746432785Speter line of code exists among the three files, except for "include" 746532785Speter statements, which must be duplicated. And make sure the code 746632785Speter compiles.] 746732785Speter 746854427Speter emacs 746954427Speter cvs commit 747032785Speter 747132785Speter As in the "rename" case, by duplicating the files, you'll preserve the 747232785Speter change history and the ability to retrieve earlier revisions. 747332785Speter 747432785Speter Of course, you have to alter your build system (e.g. Makefiles) to 747532785Speter take the new names and the change in contents into account. 747632785Speter 747754427Speter Last modified: _3/11/1998_ 747832785Speter 747932785Speter Category: /What_is_CVS_/ 748032785Speter 748132785Speter " What is CVS? " 748232785Speter 748332785Speter Category: /What_is_CVS_/How_does_CVS_differ_/ 748432785Speter 748532785Speter " + How does CVS differ from other, similar software?" 748632785Speter 748732785Speter 1. How does CVS differ from RCS? 748832785Speter 748932785Speter CVS uses RCS to do much of its work and absolutely all the work of 749032785Speter changing the underlying RCS files in the Repository. 749132785Speter 749232785Speter RCS comprises a set of programs designed to keep track of changes to 749332785Speter individual files. Of course, it also allows you to refer to multiple 749432785Speter files on the command line, but they are handled by iterating over 749532785Speter individual files. There is no pretense of coordinated interaction 749632785Speter among groups of files. 749732785Speter 749832785Speter CVS's main intent is to provide a set of grouping functions that allow 749932785Speter you to treat a collection of RCS files as a single object. Of course, 750032785Speter CVS also has to do a lot of iteration, but it tries its best to hide 750132785Speter that it is doing so. In addition, CVS has some truly group-oriented 750232785Speter facets, such as the modules file and the CVS administrative files that 750332785Speter refer to a whole directory or module. 750432785Speter 750532785Speter One group aspect that can be a bit confusing is that a CVS branch is 750632785Speter not the same as an RCS branch. To support a CVS branch, CVS uses 750732785Speter "tags" (what RCS calls "symbols") and some local state, in addition to 750832785Speter RCS branches. 750932785Speter 751032785Speter Other features offered by CVS that are not supported directly by RCS 751132785Speter are 751232785Speter 751332785Speter Automatic determination of the state of a file, (e.g. modified, 751432785Speter up-to-date with the Repository, already tagged with the same string, 751532785Speter etc.) which helps in limiting the amount of displayed text you have to 751632785Speter wade through to figure out what changed and what to do next. 751732785Speter 751832785Speter A copy-modify-merge scheme that avoids locking the files and allows 751932785Speter simultaneous development on a single file. 752032785Speter 752132785Speter Serialization of commits. CVS requires you to merge all changes 752232785Speter committed (via "update") since you checked out your working copy of 752332785Speter the file. Although it is still possible to commit a file filled with 752432785Speter old data, it is less likely than when using raw RCS. 752532785Speter 752632785Speter Relatively easy merging of releases from external Vendors. 752732785Speter 752832785Speter Last modified: _6/13/1997_ 752932785Speter 753032785Speter 2. How does CVS differ from SCCS? 753132785Speter 753232785Speter SCCS is much closer to RCS than to CVS, so some of the previous entry 753332785Speter applies. 753432785Speter 753532785Speter You might want to take a look at Walter Tichy's papers on RCS, which 753632785Speter are referred to in the RCS man pages. 753732785Speter 753832785Speter [[More info here?]] 753932785Speter 754032785Speter Last modified: _6/13/1997_ 754132785Speter 754232785Speter 3. How does CVS differ from ClearCase? 754332785Speter 754432785Speter ClearCase is a distributed client-server version control system. 754532785Speter ClearCase is a variant DSEE tools, formerly available on Apollo 754632785Speter platforms. The ClearCase tool set includes a few X-based interface 754732785Speter tools, a command-line interface, and C programmer API. It is currently 754832785Speter available on Sun, HP, SGI and OSF/1 platforms. 754932785Speter 755032785Speter ClearCase uses a special Unix filesystem type, called "mvfs" for 755132785Speter "multi-version file system". Conceptually, mvfs adds another dimension 755232785Speter to a regular Unix filesystem. The new axis is used to store the 755332785Speter different versions of files and to provide a tree-hierarchical view of 755432785Speter a collection of objects that might be scattered across any number of 755532785Speter separate hosts on your local network. 755632785Speter 755732785Speter Each user acquires a "view" into the file database by creating a 755832785Speter special mvfs mount point on their machine. Each view has a 755932785Speter "configuration spec" containing a set of selection rules that specify 756032785Speter the particular version of each file to make visible in that view. You 756132785Speter can think of a "view" as a work area in CVS, except that the files 756232785Speter don't really exist on your local disk until you modify them. This 756332785Speter technique conserves disk space because it doesn't keep private copies 756432785Speter of read-only files. 756532785Speter 756632785Speter Another advantage is that a view is "transparent" in the sense that 756732785Speter all of the files in a "view" appear to be regular Unix files to other 756832785Speter tools and Unix system calls. An extended naming convention allows 756932785Speter access to particular versions of a file directly: 757032785Speter "test.cc@@/main/bugfix/3" identifies the third version of test.c on 757132785Speter the bugfix branch. 757232785Speter 757332785Speter ClearCase supports both the copy-modify-merge model of CVS (by using 757432785Speter what are called "unreserved checkouts" and the checkin/checkout 757532785Speter development model with file locking. Directories are 757632785Speter version-controlled objects as well as files. A graphical merge tool is 757732785Speter provided. Like RCS, ClearCase supports branches, symbolic tags, and 757832785Speter delta compression. ASCII as well as binary files are supported, and 757932785Speter converters from RCS, SCCS, DSEE formats are also included. 758032785Speter 758132785Speter A make-compatible build facility is provided that can identify common 758232785Speter object code and share it among developers. A build auditing feature 758332785Speter automatically records file dependencies by tracking every file that is 758432785Speter opened when producing a derived object, thus making explicit 758532785Speter dependency lists unnecessary. Pre- and post-event triggers are 758632785Speter available for most ClearCase operations to invoke user programs or 758732785Speter shell scripts. User-defined attributes can be assigned to any version 758832785Speter or object. Hyper-links between version controlled objects can record 758932785Speter their relationship. 759032785Speter 759132785Speter For more information, contact: 759232785Speter 759332785Speter Atria Software, Inc. 24 Prime Park Way Natick, MA 01760 info@atria.com 759432785Speter 759532785Speter (508) 650-1193 (phone) (508) 650-1196 (fax) 759632785Speter 759732785Speter Originally contributed by Steve Turner 759832785Speter Edited by the author of this FAQ. 759932785Speter 760032785Speter Last modified: _6/13/1997_ 760132785Speter 760232785Speter 4. How does CVS differ from TeamWare/SparcWorks? 760332785Speter 760432785Speter TeamWare is a configuration management tool from Sun Microsystems, a 760532785Speter part of SparcWorks. It uses the same copy and merge model as CVS. The 760632785Speter central abstraction is a workspace, which corresponds to either a CVS 760732785Speter branch or a checked out module. TeamWare allows you to manipulate 760832785Speter workspaces directly, including moving and merging code between 760932785Speter workspaces. You can put your workspace on tape and continue to work 761032785Speter with it at home, just like you can with CVS. TeamWare is built upon 761132785Speter and compatible with SCCS. 761232785Speter 761332785Speter TeamWare provides both a command line interface and a graphical 761432785Speter interface. The CodeManager tool will display the project as a tree of 761532785Speter workspaces, and allows you to manipulate them with drag and drop. The 761632785Speter other tools are VersionTool that displays and manipulates a dag with a 761732785Speter version history of a single file, CheckPoint that will create symbolic 761832785Speter tags, MakeTool, a make compatible tool with a GUI, and FileMerge which 761932785Speter will interactively merge files when needed (like emerge for emacs). If 762032785Speter you have a sun, you can try /usr/old/mergetool for an old SunView 762132785Speter version of FileMerge. 762232785Speter 762332785Speter Email: sunprosig@sun.com 762432785Speter 762532785Speter Originally extracted from TeamWare 762632785Speter Marketing literature by Per Abrahamsen. 762732785Speter Edited by the author of this FAQ. 762832785Speter 762932785Speter For more information, contact: 763032785Speter 763132785Speter SunExpress, Inc. P.O. Box 4426 Bridgeton, MO 63044-9863 (800)873-7869 763232785Speter 763332785Speter Last modified: _6/13/1997_ 763432785Speter 763532785Speter 5. How does CVS differ from Aegis? 763632785Speter 763732785Speter Aegis appears to be a policy-setting tool that allows you to use other 763832785Speter sub-programs (make, RCS, etc.) to implement pieces of the imposed 763932785Speter policy. 764032785Speter 764132785Speter The initial document seems to say that most Unix tools are inadequate 764232785Speter for use under Aegis. 764332785Speter 764432785Speter It is not really similar to CVS and requires a different mindset. 764532785Speter 764632785Speter [[Need more info here.]] 764732785Speter 764832785Speter Last modified: _6/13/1997_ 764932785Speter 765032785Speter 6. How does CVS differ from Shapetools? 765132785Speter 765232785Speter Shapetools includes a build mechanism (called Shape, not surprisingly) 765332785Speter that is aware of the version mechanism, and some dependency tracking. 765432785Speter It is based on a file system extension called Attributed File System, 765532785Speter which allows arbitrary-sized "attributes" to be associated with a 765632785Speter file. Files are version controlled in a manner similar to RCS. 765732785Speter Configurations are managed through the Shapefile, an extension of the 765832785Speter Makefile syntax and functionality. Shape includes version selection 765932785Speter rules to allow sophisticated selection of component versions in a 766032785Speter build. 766132785Speter 766232785Speter Shapetools' concurrency control is pessimistic, in contrast to that of 766332785Speter CVS. Also, there's very limited support for branching and merging. It 766432785Speter has a built-in policy for transitioning a system from initial 766532785Speter development to production. 766632785Speter 766732785Speter Contributed by Don Dwiggins 766832785Speter 766932785Speter Last modified: _6/13/1997_ 767032785Speter 767132785Speter 7. How does CVS differ from TeamNet? 767232785Speter 767332785Speter TeamNet is a configuration management tool from TeamOne. 767432785Speter 767532785Speter For more information, contact: 767632785Speter 767732785Speter TeamOne 710 Lakeway Drive, Ste 100 Sunnyvale, CA 94086 (800) 442-6650 767832785Speter 767932785Speter Contributed by Steve Turner 768032785Speter 768132785Speter Last modified: _6/13/1997_ 768232785Speter 768332785Speter 8. How does CVS differ from ProFrame? 768432785Speter 768532785Speter ProFrame is a new system integration framework from IBM. ProFrame is 768632785Speter compliant with the CFI (CAD Framework Initiative) industry standards, 768732785Speter including the Scheme extension language. 768832785Speter 768932785Speter ProFrame consists of three major components: (1) the Process Manager 769032785Speter that automates your local design methodology (2) the Design Data 769132785Speter Manager handles configuration management, and (3) Inter-tool 769232785Speter Communication to provide a communication path among tools running on 769332785Speter heterogeneous servers. 769432785Speter 769532785Speter The Design Data Manager(2) is probably the appropriate component to 769632785Speter compare to CVS. The Design Data Manager provides version control with 769732785Speter checkin/checkout capability, configuration management, and data 769832785Speter dependency tracking. A graphical data selection interface is provided. 769932785Speter Using this interface, you may create and manipulate objects and 770032785Speter hierarchy structures, view the revision history for an object, and 770132785Speter view and assign attributes to a design object. 770232785Speter 770332785Speter The ProFrame server currently runs only on RS6000, but clients may be 770432785Speter a wide variety of Unix platforms. Contact IBM for the latest platform 770532785Speter information. 770632785Speter 770732785Speter For more information, contact: 770832785Speter 770932785Speter IBM EDA Marketing and Sales P.O. Box 950, M/S P121 Poughkeepsie, NY 771032785Speter 12602 (800) 332-0066 771132785Speter 771232785Speter Contributed by Steve Turner 771332785Speter [extracted from the ProFrame 1.1.0 datasheet] 771432785Speter 771532785Speter Last modified: _6/13/1997_ 771632785Speter 771732785Speter 9. How does CVS differ from CaseWare/CM? 771832785Speter 771932785Speter CaseWare/CM is a software configuration management product from 772032785Speter CaseWare, Inc. CaseWare/CM may be customized to support a wide variety 772132785Speter of methodologies, including various phases of the software lifecycle, 772232785Speter and different access rights for users. 772332785Speter 772432785Speter A GUI is provided to view version histories and configurations. A 772532785Speter merge tools is also included. CaseWare supports type-specific 772632785Speter lifecycles, which allows different types of files to move through 772732785Speter different lifecycles. Also provided is a build facility to support 772832785Speter automatic dependency analysis, parallel, distributed, and remote 772932785Speter builds, and variant releases. 773032785Speter 773132785Speter CaseWare/CM has been integrated with other CASE tools, including 773232785Speter FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP SoftBench, and 773332785Speter Software Through Pictures. CaseWare also offers CaseWare/PT, a problem 773432785Speter tracking system to integrate change requests with configuration 773532785Speter management. 773632785Speter 773732785Speter Multiple vendors and operating systems are supported. 773832785Speter 773932785Speter For more information, contact: 774032785Speter 774132785Speter CaseWare, Inc. 108 Pacifica, 2nd Floor Irvine, CA 92718-3332 (714) 774232785Speter 453-2200 (phone) (714) 453-2276 (fax) 774332785Speter 774432785Speter Contributed by Steve Turner 774532785Speter [extracted from the CaseWare/CM data sheet] 774632785Speter 774732785Speter Last modified: _6/13/1997_ 774832785Speter 774954427Speter 10. How does CVS differ from SABLIME? 775032785Speter 775132785Speter Produced by AT&T. Sablime uses SCCS as the underlying source code 775232785Speter control system. It uses some other control system (called sbcs I 775332785Speter think) for managing binary files. It uses lock, edit, comit, unlock 775432785Speter mechanism. It has a motif based GUI and curses based GUI (that works 775532785Speter only with ksh, not tcsh, or bash) to do more common tasks. It has even 775632785Speter a command line interface. 775732785Speter 775832785Speter Changing source happens as a result of MR. A testing person or a 775932785Speter developer assigns an MR (modification request) to a group of people. 776032785Speter They are allowed to take out files under that MR and change them and 776132785Speter check them back in. You can set up dependencies between and MR and do 776232785Speter release management to say "I want the sources to include these MRs" 776332785Speter etc. It is a reasonably good maintanance system. It is bit heavy 776432785Speter weight though, and the interface is not too polished and does not work 776532785Speter on windows (though that may have changed). rama@savera.com 776632785Speter 776754427Speter Last modified: _7/30/1998_ 776832785Speter 776932785Speter 11. How does CVS differ from PVCS? 777032785Speter 777132785Speter PVCS works on single files like RCS and SCCS, CVS works on complete 777232785Speter subsystems. PVCS has a make utility (called a configuration builder), 777332785Speter CVS does not. PVCS has a GUI interface for Unix, DOS, OS/2, and MS 777432785Speter Windows. 777532785Speter 777632785Speter Intersolv, Inc. 777732785Speter 1700 NW 167th Place 777832785Speter OR 97006 777932785Speter 778032785Speter Contributed by Per Abrahamsen 778132785Speter [Extracted from Intersolv Marketing literature.] 778232785Speter 778332785Speter Last modified: _6/13/1997_ 778432785Speter 778532785Speter 12. How does CVS differ from CMVC? 778632785Speter 778732785Speter CMVC is an IBM Configuration Management and Version Control system. 778832785Speter (Though I'm not certain that's the right acronym expansion.) It runs 778932785Speter on Suns, HPs, RS6000s, OS/2 and Windows. 779032785Speter 779132785Speter Other than revision control, it apparently has features to manage 779232785Speter releases, bug tracking and the connection between alterations and 779332785Speter reported bugs and feature requests. It is a client/server system, 779432785Speter based on a choice of commercial Relational Database systems, and it 779532785Speter provides a Motif or command line interface. 779632785Speter 779732785Speter Unlike CVS, it uses a strict locking protocol to serialize source code 779832785Speter alterations. 779932785Speter 780032785Speter Last modified: _6/13/1997_ 780132785Speter 780232785Speter Category: /What_is_CVS_/What_do_you_mean_by_/ 780332785Speter 780432785Speter " + What do you mean by . . .? (Definitions)" 780532785Speter 780632785Speter 1. What are "The Repository", "$CVSROOT" and "CVSROOT"? 780732785Speter 780832785Speter The Repository is a directory tree containing the CVS administrative 780932785Speter files and all the RCS files that constitute "imported" or "committed" 781032785Speter work. The Repository is kept in a shared area, separate from the 781132785Speter working areas of all developers. 781232785Speter 781332785Speter Users of CVS must set their "CVSROOT" environment variable to the 781432785Speter absolute pathname of the head of the Repository. Most command line 781532785Speter interpreters replace an instance of "$CVSROOT" with the value of the 781632785Speter "CVSROOT" environment variable. By analogy, in this document 781732785Speter "$CVSROOT" is used as shorthand for "the absolute pathname of the 781832785Speter directory at the head of the Repository". 781932785Speter 782032785Speter One of the things found in $CVSROOT is a directory named CVSROOT. It 782132785Speter contains all the "state", the administrative files, that CVS needs 782232785Speter during execution. The "modules", "history", "commitinfo", "loginfo" 782332785Speter and other files can be found there. See 4B.2 for more information 782432785Speter about CVSROOT files. 782532785Speter 782632785Speter Last modified: _6/13/1997_ 782732785Speter 782832785Speter 2. What is an RCS file? 782932785Speter 783032785Speter An RCS file is a text file containing the source text and the revision 783132785Speter history for all committed revisions of a source file. It is stored 783232785Speter separately from the working files, in a directory hierarchy, called 783332785Speter the Repository. 783432785Speter 783532785Speter RCS is the "Revision Control System" that CVS uses to manage 783632785Speter individual files. RCS file names normally end in ",v", but that can be 783732785Speter altered (via the RCS -x option) to conform to file naming standards on 783832785Speter platforms with unusual filename limitations. 783932785Speter 784032785Speter Last modified: _6/13/1997_ 784132785Speter 784232785Speter 3. What is a working file? 784332785Speter 784432785Speter A working file is a disk file containing a checked-out copy of a 784532785Speter source file that earlier had been placed under CVS. If the working 784632785Speter file has been edited, the changes since the last committed revision 784732785Speter are invisible to other users of CVS. 784832785Speter 784932785Speter Last modified: _6/13/1997_ 785032785Speter 785132785Speter 4. What is a working directory (or working area)? 785232785Speter 785332785Speter A working directory is the place where you work and the place from 785432785Speter which you "commit" files. 785532785Speter 785632785Speter The "checkout" command creates a tree of working directories, filling 785732785Speter them with working files. Each working directory contains a 785832785Speter sub-directory named ./CVS containing three administrative files, which 785932785Speter are created by "checkout" and are always present: 786032785Speter 786132785Speter ./CVS/Entries 786232785Speter contains information about working files. 786332785Speter 786432785Speter ./CVS/Repository 786532785Speter contains the location of the directory within the 786632785Speter Repository that was used to create the working directory. 786732785Speter 786832785Speter ./CVS/Root 786932785Speter contains the value of $CVSROOT at the time you created 787032785Speter the working directory. 787132785Speter 787232785Speter Other files may also appear in ./CVS depending on the state of your 787332785Speter working directory: 787432785Speter 787532785Speter ./CVS/Tag 787632785Speter contains the "sticky tag" associated with the whole 787732785Speter directory. See 3A.2 for its main purpose. 787832785Speter [Created by "checkout" or "update" when using "-r <tag>".] 787932785Speter [Deleted by "checkout" or "update" when using '-A'.] 788032785Speter 788132785Speter ./CVS/Entries.Static 788232785Speter contains a fixed list of working files. If this file 788332785Speter exists, an "update" doesn't automatically bring newly 788432785Speter added files out of the Repository. 788532785Speter [Created and maintained by hand.] 788632785Speter 788732785Speter ./CVS/Checkin.prog 788832785Speter contains a program to run whenever anything in the 788932785Speter working directory is committed. 789032785Speter [Created by checkout if "-i <prog>" appears in the 789132785Speter modules file for the checked-out module.] 789232785Speter 789332785Speter ./CVS/Update.prog 789432785Speter contains a program to run whenever anything in the 789532785Speter working directory is updated. 789632785Speter [Created by checkout if "-u <prog>" appears in the 789732785Speter modules file for the checked-out module.] 789832785Speter 789932785Speter ./CVS/<file>,p ./CVS/<file>,t 790032785Speter contain (possibly zero-length) state information about an 790132785Speter "add" that has not been committed. 790232785Speter [Created by "add".] 790332785Speter [Deleted by "commit" or "remove".] 790432785Speter 790532785Speter Last modified: _6/13/1997_ 790632785Speter 790732785Speter 5. What is "checking out"? 790832785Speter 790932785Speter "Checking out" is the act of using the "checkout" command to copy a 791032785Speter particular revision from a set of RCS files into your working area. 791132785Speter You normally execute "checkout" only once per working directory (or 791232785Speter tree of working directories), maintaining them thereafter with the 791332785Speter "update" command. 791432785Speter 791532785Speter See section 3C on the "checkout" command. 791632785Speter 791732785Speter Last modified: _6/13/1997_ 791832785Speter 791932785Speter 6. What is a revision? 792032785Speter 792132785Speter A "revision" is a version of a file that was "committed" ("checked 792232785Speter in", in RCS terms) some time in the past. CVS (and RCS) can retrieve 792332785Speter any file that was committed by specifying its revision number or its 792432785Speter "tag" ("symbolic name", in RCS terms). 792532785Speter 792632785Speter In CVS, a "tag" is more useful than a revision number. It usually 792732785Speter marks a milestone in development represented by different revision 792832785Speter numbers in different files, all available as one "tagged" collection. 792932785Speter 793032785Speter Sometimes the word "revision" is used as shorthand for "the file you 793132785Speter get if you retrieve (via "checkout" or "update") the given revision 793232785Speter from the Repository." 793332785Speter 793432785Speter Last modified: _6/13/1997_ 793532785Speter 793632785Speter 7. What is a "Tag"? 793732785Speter 793832785Speter A "Tag" is a symbolic name, a synonym or alias for a particular 793932785Speter revision number in a file. The CVS "tag" command places the same "Tag" 794032785Speter on all files in a working directory, allowing you to retrieve those 794132785Speter files by name in the future. 794232785Speter 794332785Speter The CVS "Tag" is implemented by applying RCS "symbols" to each 794432785Speter individual file. The Tags on a file (or collection of files) may be 794532785Speter displayed using the "log" command. 794632785Speter 794732785Speter Last modified: _6/13/1997_ 794832785Speter 794932785Speter 8. What are "HEAD" and "BASE"? 795032785Speter 795132785Speter HEAD and BASE are built-in tags that don't show up in the "log" or 795232785Speter "status" listings. They are interpreted directly by CVS. 795332785Speter 795432785Speter "HEAD" refers to the latest revision on the current branch in the 795532785Speter Repository. The current branch is either the main line of development, 795632785Speter or a branch in development created by placing a branch tag on a set of 795732785Speter files and checking out that branch. 795832785Speter 795932785Speter "BASE" refers to the revision on the current branch you last checked 796032785Speter out, updated, or committed. If you have not modified your working 796132785Speter file, "BASE" is the committed revision matching it. 796232785Speter 796332785Speter Most of the time BASE and HEAD refer to the same revision. They can 796432785Speter become different in two ways: 796532785Speter 796632785Speter Someone else changed HEAD by committing a new revision of your file 796732785Speter to the Repository. You can pull BASE up to equal HEAD by executing 796832785Speter "update". 796932785Speter 797032785Speter You moved BASE backward by executing "checkout" or "update" with the 797132785Speter option "-r <rev/tag>" or "-D <date>". CVS records a sticky tag and 797232785Speter moves your files to the specified earlier revision. You can clear the 797332785Speter sticky tag and pull BASE up to equal HEAD again by executing "update 797432785Speter -A". 797532785Speter 797632785Speter Last modified: _6/13/1997_ 797732785Speter 797832785Speter 9. What is a Branch? 797932785Speter 798032785Speter In general, a branch is any mechanism that allows one or more 798132785Speter developers to modify a file without affecting anyone other than those 798232785Speter working on the same branch. 798332785Speter 798432785Speter There are four kinds of "branch" CVS can manage: 798532785Speter 798632785Speter The Vendor Branch. 798732785Speter 798832785Speter A single vendor branch is supported. The "import" command takes a 798932785Speter sequence of releases from a source code vendor (called a "vendor" even 799032785Speter if no money is involved), placing them on a special "Vendor" branch. 799132785Speter The Vendor branch is considered part of the "Main line" of 799232785Speter development, though it must be merged into locally modified files on 799332785Speter the RCS Main branch before the "import" is complete. 799432785Speter 799532785Speter See Section 3H ("import"). 799632785Speter 799732785Speter Your Working directory. 799832785Speter 799932785Speter A checked-out working directory, can be treated like a private branch. 800032785Speter No one but you can touch your files. You have complete control over 800132785Speter when you include work committed by others. However, you can't commit 800232785Speter or tag intermediate versions of your work. 800332785Speter 800432785Speter A Development branch. 800532785Speter 800632785Speter A group of developers can share changes among the group, without 800732785Speter affecting the Main line of development, by creating a branch. Only 800832785Speter those who have checked-out the branch see the changes committed to 800932785Speter that branch. This kind of branch is usually temporary, collapsing 801032785Speter (i.e. merge and forget) into the Main line when the project requiring 801132785Speter the branch is completed. 801232785Speter 801332785Speter You can also create a private branch of this type, allowing an 801432785Speter individual to commit (and tag) intermediate revisions without changing 801532785Speter the Main line. It should be managed exactly like a Development Branch 801632785Speter -- collapsed into the Main line (or its parent branch, if that is not 801732785Speter the Main Branch) and forgotten when the work is done. 801832785Speter 801932785Speter A Release branch. 802032785Speter 802132785Speter At release time, a branch should be created marking what was released. 802232785Speter Later, small changes (sometimes called "patches") can be made to the 802332785Speter release without including everything else on the Main line of 802432785Speter development. You avoid forcing the customer to accept new, possibly 802532785Speter untested, features added since the release. This is also the way to 802632785Speter correct bugs found during testing in an environment where other 802732785Speter developers have continued to commit to the Main line while you are 802832785Speter testing and packaging the release. 802932785Speter 803032785Speter Although the internal format of this type of branch (branch tag and 803132785Speter RCS branches) is the same as in a development branch, its purpose and 803232785Speter the way it is managed are different. The major difference is that a 803332785Speter Release branch is normally Permanent. Once you let a release out the 803432785Speter door to customers, or to the next stage of whatever process you are 803532785Speter using, you should retain forever the branch marking that release. 803632785Speter 803732785Speter Since the branch is permanent, you cannot incorporate the branch fixes 803832785Speter into the Main line by "collapsing" (merging and forgetting) the 803932785Speter release branch. For large changes to many files on the release branch, 804032785Speter you will have to perform a branch merge using "update -j <rev> -j 804132785Speter <rev>". (See 4C.7) 804232785Speter 804332785Speter The most common way to merge small changes back into Main line 804432785Speter development is to make the change in both places simultaneously. This 804532785Speter is faster than trying to perform a selective merge. 804632785Speter 804732785Speter See 1D.12 (merges) and Section 4C, on Branching for more info. 804832785Speter 804932785Speter Last modified: _6/13/1997_ 805032785Speter 805132785Speter 10. What is "the trunk"? 805232785Speter 805332785Speter Another name for the RCS Main Branch. The RCS Main Branch is related, 805432785Speter but not equivalent, to both the CVS Main branch and what developers 805532785Speter consider to be the Main line of development. See 3H.3 and Section 4C 805632785Speter on Branching. 805732785Speter 805832785Speter Last modified: _6/13/1997_ 805932785Speter 806032785Speter 11. What is a module? 806132785Speter 806232785Speter In essence, a module is a name you hand to the "checkout" command to 806332785Speter retrieve one or more files to work on. It was originally intended to 806432785Speter be a simple, unique name in the "modules" file attached to a directory 806532785Speter or a subset of files within a directory. 806632785Speter 806732785Speter The module idea is now a somewhat slippery concept that can be defined 806832785Speter in two different ways: 806932785Speter * A module is an argument to "checkout". There are three types: 807032785Speter 1. An entry in the modules file. A "module" name as described in 807132785Speter 'B.' below. 807232785Speter 2. A relative path to a directory or file in the Repository. 807332785Speter 3. A mixed-mode string of "modulename/relative-path". Everything 807432785Speter up to the first slash ('/') is looked up as a module. The 807532785Speter relative path is appended to the directory associated with 807632785Speter the module name and the resulting path is checked out as in 807732785Speter #2 above. 807832785Speter * A module is a unique (within the file) character string in the 807932785Speter first column of the modules file. There are five types: 808032785Speter 1. A name for a directory within the Repository that allows you 808132785Speter to ignore the parent directories above it. 808232785Speter Example: 808332785Speter emacs gnu/emacs 808432785Speter 2. A name for a subset of the files within such a directory. 808532785Speter Example: 808632785Speter ls unix/bin Makefile ls.c 808732785Speter The 2nd through Nth strings in the above can be files, 808832785Speter directories or module substitutions. No relative paths. 808932785Speter A module substitution occurs when you use a '&module-name' 809032785Speter reference. The module-name referred to is logically 809132785Speter substituted for the '&module-name' string. 809232785Speter 3. A relative pathname to a directory within the Repository 809332785Speter which, when checked out, creates an image of part of the 809432785Speter Repository structure in your current directory. 809532785Speter Example: 809632785Speter gnu/emacs -o /bin/emacs.helper gnu/emacs 809732785Speter The files checked out are exactly the same as the files 809832785Speter "checkout" would retrieve if the path weren't even in the 809932785Speter modules file. The only reason to put this kind of relative 810032785Speter pathname into the modules file is to hook one of the helper 810132785Speter functions onto it. 810232785Speter 4. A relative pathname to a single file within the Repository 810332785Speter which, when checked out, creates something you probably don't 810432785Speter want: It creates a directory by the name of the file and puts 810532785Speter the file in it. 810632785Speter Example: 810732785Speter gnu/emacs/Makefile -o /bin/emacs.helper gnu/emacs Makefile 810832785Speter The file checked out is the same as what you would get if you 810932785Speter handed the relative pathname to the "checkout" command. But 811032785Speter it puts it in a strange place. The only reason to do this is 811132785Speter to hook a helper function onto a specific file name. 811232785Speter 5. An alias consisting of a list of any of the above, including 811332785Speter other aliases, plus exceptions. 811432785Speter Example: 811532785Speter my_work -a emacs !emacs/tests gnu/bison unix/bin/ls.c 811632785Speter The exception "!emacs/test" above is functionally equivalent 811732785Speter to specifying "!emacs/tests" on the "checkout" command line. 811832785Speter 811932785Speter Another way to look at it is that the modules file is simply another 812032785Speter way to "name" files. The hierarchical directory structure provides 812132785Speter another. You should use whatever turns out to be simplest for your 812232785Speter development group. 812332785Speter 812432785Speter See 4G.2 for some specific ideas about how to use the modules file. 812532785Speter 812632785Speter Last modified: _11/12/1997_ 812732785Speter 812832785Speter 12. What does "merge" mean? 812932785Speter 813032785Speter A merge is a way of combining changes made in two independent copies 813132785Speter of a common starting file. Checking out an RCS revision produces a 813232785Speter file, so for the purposes of a merge "file" and "revision" are 813332785Speter equivalent. So, we can say there are always three "files" involved in 813432785Speter a merge: 813532785Speter 813632785Speter The original, starting, "base" or "branch point" file. 813732785Speter 813832785Speter A copy of the base file modified in one way. 813932785Speter 814032785Speter Another copy of the base file modified in a different way. 814132785Speter 814232785Speter Humans aren't very good at handling three things at once, so the 814332785Speter terminology dealing with merges can become strained. One way to think 814432785Speter about it is that all merges are performed by inserting the difference 814532785Speter between a base revision and a later revision (committed by someone 814632785Speter else) into your working file. Both the "later" revision and your 814732785Speter working file are presumed to have started life as a copy of the "base" 814832785Speter revision. 814932785Speter 815032785Speter In CVS, there are three main types of "merge": 815132785Speter 815232785Speter The "update" command automatically merges revisions committed by 815332785Speter others into your working file. In this case, the three files involved 815432785Speter in the merge are: 815532785Speter 815632785Speter Base: The revision you originally checked out. Later: A revision 815732785Speter committed onto the current branch after you checked out the Base 815832785Speter revision. Working: Your working file. The one lying in the working 815932785Speter directory containing changes you have made. 816032785Speter 816132785Speter The "update -j <branch_tag> {optional files}" command merges changes 816232785Speter made on the given branch into your working files, which is presumed to 816332785Speter be on the Main line of development. 816432785Speter 816532785Speter See 4C.6 816632785Speter 816732785Speter The "update -j <rev> -j <rev> {optional files}" command merges the 816832785Speter difference between two specified revisions into files in your working 816932785Speter directory. The two revisions <rev> are usually on the same branch and, 817032785Speter when updating multiple files, they are most useful when they are Tag 817132785Speter names rather than numeric revisions. 817232785Speter 817332785Speter See 4C.7 817432785Speter 817532785Speter Last modified: _6/13/1997_ 817632785Speter 817732785Speter Category: /What_is_CVS_/What_is_CVS_Whats_it/ 817832785Speter 817932785Speter " + What is CVS? What's it for? Why CVS?" 818032785Speter 818132785Speter 1. What does CVS stand for? Can you describe it in one sentence? 818232785Speter 818332785Speter "CVS" is an acronym for the "Concurrent Versions System". 818432785Speter 818532785Speter CVS is a "Source Control" or "Revision Control" tool designed to keep 818632785Speter track of source changes made by groups of developers working on the 818732785Speter same files, allowing them to stay in sync with each other as each 818832785Speter individual chooses. 818932785Speter 819032785Speter Last modified: _6/13/1997_ 819132785Speter 819232785Speter 2. What is CVS for? What does it do for me? 819332785Speter 819432785Speter CVS is used to keep track of collections of files in a shared 819532785Speter directory called "The Repository". Each collection of files can be 819632785Speter given a "module" name, which is used to "checkout" that collection. 819732785Speter 819832785Speter After checkout, files can be modified (using your favorite editor), 819932785Speter "committed" back into the Repository and compared against earlier 820032785Speter revisions. Collections of files can be "tagged" with a symbolic name 820132785Speter for later retrieval. 820232785Speter 820332785Speter You can add new files, remove files you no longer want, ask for 820432785Speter information about sets of files in three different ways, produce patch 820532785Speter "diffs" from a base revision and merge the committed changes of other 820632785Speter developers into your working files. 820732785Speter 820832785Speter Last modified: _6/13/1997_ 820932785Speter 821032785Speter 3. How does CVS work? 821132785Speter 821232785Speter CVS saves its version-control information in RCS files stored in a 821332785Speter directory hierarchy, called the Repository, which is separate from the 821432785Speter user's working directory. 821532785Speter 821632785Speter Files in the Repository are stored in a format dictated by the RCS 821732785Speter commands CVS uses to do much of its real work. RCS files are standard 821832785Speter byte-stream files with an internal format described by keywords stored 821932785Speter in the files themselves. 822032785Speter 822132785Speter To begin work, you execute a "checkout" command, handing it a module 822232785Speter name or directory path (relative to the $CVSROOT variable) you want to 822332785Speter work on. CVS copies the latest revision of each file in the specified 822432785Speter module or directory out of the Repository and into a directory tree 822532785Speter created in your current directory. You may specify a particular branch 822632785Speter to work on by symbolic name if you don't want to work on the default 822732785Speter (main or trunk) branch. 822832785Speter 822932785Speter You may then modify files in the new directory tree, build them into 823032785Speter output files and test the results. When you want to make your changes 823132785Speter available to other developers, you "commit" them back into the 823232785Speter Repository. 823332785Speter 823432785Speter Other developers can check out the same files at the same time. To 823532785Speter merge the committed work of others into your working files you use the 823632785Speter "update" command. When your merged files build and test correctly, you 823732785Speter may commit the merged result. This method is referred to as 823832785Speter "copy-modify-merge", which does not require locks on the source files. 823932785Speter 824032785Speter At any time, usually at some milestone, you can "tag" the committed 824132785Speter files, producing a symbolic name that can be handed to a future 824232785Speter "checkout" command. A special form of "tag" produces a branch in 824332785Speter development, as usually happens at "release" time. 824432785Speter 824532785Speter When you no longer plan to modify or refer to your local copy of the 824632785Speter files, they can be removed. 824732785Speter 824832785Speter Last modified: _6/13/1997_ 824932785Speter 825032785Speter 4. What is CVS useful for? 825132785Speter 825232785Speter CVS is intended to handle source control for files in three major 825332785Speter situations: 825432785Speter 825532785Speter Multiple developers working on the same files. 825632785Speter 825732785Speter The major advantage of using CVS over the simpler tools like RCS or 825832785Speter SCCS is that it allows multiple developers to work on the same sources 825932785Speter at the same time. 826032785Speter 826132785Speter The shared Repository provides a rendezvous for committed sources that 826232785Speter allows developers a fair amount of flexibility in how often to publish 826332785Speter (via the "commit" command) changes or include work committed by others 826432785Speter (via the "update" command). 826532785Speter 826632785Speter Tracking a stream of releases from a source vendor. 826732785Speter 826832785Speter If you are making changes to sources distributed by someone else, the 826932785Speter CVS feature, called the Vendor Branch, allows you to combine local 827032785Speter modifications with repeated vendor releases. 827132785Speter 827232785Speter I have found this most useful when dealing with sources from three 827332785Speter major classes of source vendor: 827432785Speter 827532785Speter Large companies who send you tapes full of the latest release (e.g. 827632785Speter Unix OS vendors, database companies). 827732785Speter 827832785Speter Public Domain software which *always* requires work. 827932785Speter 828032785Speter Pseudo-Public sources which may require work. (e.g. GNU programs, X, 828132785Speter CVS itself, etc.) 828232785Speter 828332785Speter Branching development. 828432785Speter 828532785Speter Aside from the "Vendor Branch", there are three kinds of "branches in 828632785Speter development" that CVS can support: 828732785Speter 828832785Speter Your working directory can be treated as a private branch. 828932785Speter 829032785Speter A Development branch can be shared by one or more developers. 829132785Speter 829232785Speter At release time, a branch is usually created for bug fixes. 829332785Speter 829432785Speter (See 1D.9 and Section 4C for more info on branches.) 829532785Speter 829632785Speter CVS's branch support is a bit primitive, but it was designed to allow 829732785Speter you to create branches, work on them for while and merge them back 829832785Speter into the main line of development. You should also be able to merge 829932785Speter work performed on the main branch into the branch you are working on. 830032785Speter Arbitrary sharing and merging between branches is not currently 830132785Speter supported. 830232785Speter 830332785Speter Last modified: _6/13/1997_ 830432785Speter 830532785Speter 5. What is CVS *not* useful for? 830632785Speter 830732785Speter CVS is not a build system. 830832785Speter 830932785Speter Though the structure of your Repository and modules file interact with 831032785Speter your build system (e.g. a tree of Makefiles), they are essentially 831132785Speter independent. 831232785Speter 831332785Speter CVS does not dictate how you build anything. It merely stores files 831432785Speter for retrieval in a tree structure you devise. 831532785Speter 831632785Speter CVS does not dictate how to use disk space in the checked out working 831732785Speter directories. If you require your Makefiles or build procedures to know 831832785Speter the relative positions of everything else, you wind up requiring the 831932785Speter entire Repository to be checked out. That's simply bad planning. 832032785Speter 832132785Speter If you modularize your work, and construct a build system that will 832232785Speter share files (via links, mounts, VPATH in Makefiles, etc.), you can 832332785Speter arrange your disk usage however you like. 832432785Speter 832532785Speter But you have to remember that *any* such system is a lot of work to 832632785Speter construct and maintain. CVS does not address the issues involved. You 832732785Speter must use your brain and a collection of other tools to provide a build 832832785Speter scheme to match your plans. 832932785Speter 833032785Speter Of course, you should use CVS to maintain the tools created to support 833132785Speter such a build system (scripts, Makefiles, etc). 833232785Speter 833332785Speter CVS is not a substitute for management. 833432785Speter 833532785Speter You and your project leaders are expected to plan what you are doing. 833632785Speter Everyone involved must be aware of schedules, merge points, branch 833732785Speter names, release dates and the range of procedures needed to build 833832785Speter products. (If you produce it and someone else uses it, it is a 833932785Speter product.) CVS can't cover for a failure to manage your project. 834032785Speter 834132785Speter CVS is an instrument for making sources dance to your tune. But you 834232785Speter are the piper and the composer. No instrument plays itself or writes 834332785Speter its own music. 834432785Speter 834532785Speter CVS is not a substitute for developer communication. 834632785Speter 834732785Speter When faced with conflicts within a single file, most developers manage 834832785Speter to resolve them without too much effort. But a more general definition 834932785Speter of "conflict" includes problems too difficult to solve without 835032785Speter communication between developers. 835132785Speter 835232785Speter CVS cannot determine when simultaneous changes within a single file, 835332785Speter or across a whole collection of files, will logically conflict with 835432785Speter one another. Its concept of a "conflict" is purely textual, arising 835532785Speter when two changes to the same base file are near enough to spook the 835632785Speter merge command into dropping conflict markers into the merged file. 835732785Speter 835832785Speter CVS is not capable of figuring out distributed conflicts in program 835932785Speter logic. For example, if you change the arguments to function X defined 836032785Speter in file A and, at the same time, edit file B, adding new calls to 836132785Speter function X using the old arguments. You are outside the realm of CVS's 836232785Speter competence. 836332785Speter 836432785Speter Acquire the habit of reading specs and talking to your peers. 836532785Speter 836632785Speter CVS is not a configuration management system. 836732785Speter 836832785Speter CVS is a source control system. The phrase "configuration management" 836932785Speter is a marketing term, not an industry-recognized set of functions. 837032785Speter 837132785Speter A true "configuration management system" would contain elements of the 837232785Speter following: 837332785Speter 837432785Speter * Source control. 837532785Speter * Dependency tracking. 837632785Speter * Build systems (i.e. What to build and how to find 837732785Speter things during a build. What is shared? What is local?) 837832785Speter * Bug tracking. 837932785Speter * Automated Testing procedures. 838032785Speter * Release Engineering documentation and procedures. 838132785Speter * Tape Construction. 838232785Speter * Customer Installation. 838332785Speter * A way for users to run different versions of the same 838432785Speter software on the same host at the same time. 838532785Speter 838632785Speter CVS provides only the first. 838732785Speter 838832785Speter Last modified: _6/13/1997_ 838932785Speter 839032785Speter Category: /What_is_CVS_/Where_do_I_find_CVS_/ 839132785Speter 839232785Speter " + Where do I find CVS? Where can I find Help?" 839332785Speter 839432785Speter 1. How do I get more information about CVS? 839532785Speter 839632785Speter The first thing I would do is to read the Info file that comes with 839732785Speter the CVS sources under "doc". You can format and read the cvs.texinfo 839832785Speter file in two ways: 1. Use TeX to format it and a "dvips" command to 839932785Speter print it and 2. Install the cvs.info files that are created by the 840032785Speter Makefile and read them online using the Emacs "info-mode" or a 840132785Speter stand-alone "info" reader. 840232785Speter 840332785Speter Then I'd run "cvsinit" to set up a Repository and read the man page 840432785Speter while trying out the commands. 840532785Speter 840632785Speter Type "cvs -H" for general help or "cvs -H command" for 840732785Speter command-specific help. 840832785Speter 840932785Speter For background, you can read the original CVS paper (in the source 841032785Speter tree, under "doc"). It describes the purpose of CVS and some of how it 841132785Speter was designed. Note that the emphasis of the document (especially on 841232785Speter multiple vendors providing the same sources) is somewhat out of date. 841332785Speter 841432785Speter For more detailed information about "internals", read the man pages 841532785Speter for RCS. If you are a programmer, you can also read the source code to 841632785Speter CVS. 841732785Speter 841832785Speter Other information and tutorials may be available in the "doc" 841932785Speter directory of the FTP archive described below. 842032785Speter 842132785Speter For current information, and a fair amount of detail, join the 842232785Speter info-cvs mailing list described below. 842332785Speter 842432785Speter Last modified: _6/13/1997_ 842532785Speter 842632785Speter 2. Is there an archive of CVS material? 842732785Speter 842832785Speter An anonymous FTP area has been set up. It contains many of the CVS 842932785Speter files you might want, including extra documentation, patches and a 843032785Speter copy of the latest release. 843132785Speter 843232785Speter ftp ftp.delos.com 843332785Speter >>> User: anonymous 843454427Speter >>> Passwd: 843532785Speter cd /pub/cvs 843632785Speter get README 843732785Speter get Index 843832785Speter 843932785Speter The README has more (and more up-to-date) information. The Index 844032785Speter contains a terse list of what is in the archive. 844132785Speter 844232785Speter A WWW home page is also available at http://www.delos.com/cvs. 844332785Speter 844454427Speter This Didn't Exist 6/23/1998 844554427Speter 844654427Speter Last modified: _6/24/1998_ 844732785Speter 844832785Speter 3. How do I get files out of the archive if I don't have FTP? 844932785Speter 845032785Speter Use one of the FTP<->Email servers. These are the ones I've been told 845132785Speter about: 845232785Speter 845332785Speter FTPMAIL service is available from the same host as the FTP server 845432785Speter described above. Send mail to "ftpmail@delos.com" containing "help" in 845532785Speter the body of the message. For example, on most Unix systems, you can 845632785Speter type: 845732785Speter 845832785Speter echo help | Mail ftpmail@delos.com 845932785Speter 846032785Speter The FTPMAIL server will respond with a document describing how to use 846132785Speter the server. If the "Mail" command doesn't exist on your system, try 846232785Speter "mailx", "/usr/ucb/mail" or "/bin/mail". 846332785Speter 846432785Speter If you are on BITNET, use Princeton's BITFTP server. Type 846532785Speter 846632785Speter echo 'send help' | Mail bitftp@pucc.princeton.edu 846732785Speter 846832785Speter (It is likely that only BITNET addresses can use this one.) 846932785Speter 847032785Speter Other possibilities I've heard of from the net: (Try the one closest 847132785Speter to you.) 847232785Speter 847332785Speter ftpmail@decwrl.dec.com ftpmail@sunsite.unc.edu ftpmail@cs.arizona.edu 847432785Speter ftpmail@cs.uow.edu.au ftpmail@doc.ic.ac.uk 847532785Speter 847632785Speter Last modified: _6/13/1997_ 847732785Speter 847832785Speter 4. How do I get a copy of the latest version of CVS? 847932785Speter 848032785Speter The latest released version of CVS and all the programs it depends on 848132785Speter should be available through anonymous FTP on any FSF archive. The main 848232785Speter FSF archive is at "prep.ai.mit.edu". There are mirrors of the FSF 848332785Speter archive on UUNET and other large Internet sites. 848432785Speter 848532785Speter Program(s) Suggested revision 848632785Speter ----------- ----------------------- 848732785Speter CVS 1.5 848832785Speter RCS 5.7 (latest version available today) 848932785Speter GNU diff 2.7 (or later) [contained in diffutils-2.7] 849032785Speter GDBM 1.5 (or later) [optional] 849132785Speter 849232785Speter The GNU version of diff is suggested by both the RCS and CVS 849332785Speter configuration instructions because it works better than the standard 849432785Speter version. 849532785Speter 849632785Speter It is a good idea not to accept the versions of CVS, RCS or diff you 849732785Speter find lying on your system unless you have checked out their 849832785Speter provenance. Using inconsistent collections of tools can cause you more 849932785Speter trouble than you can probably afford. 850032785Speter 850132785Speter The FTP archive mentioned above should contain the latest official 850232785Speter release of CVS, some official and unofficial patches and possibly 850332785Speter complete patched versions of CVS in use somewhere. 850432785Speter 850532785Speter Last modified: _6/13/1997_ 850632785Speter 850732785Speter 5. Is there a mailing list devoted to CVS? How do I find it? 850832785Speter 850932785Speter An Internet mailing list named "info-cvs" grew out of the private 851032785Speter mailing list used by the CVS 1.3 alpha testers in early 1992. 851132785Speter Throughout 1994, the list received an average of 100 messages per 851232785Speter month. 851332785Speter 851432785Speter You can add yourself to the mailing list by sending an Email message 851532785Speter to: 851632785Speter 851732785Speter info-cvs-request@prep.ai.mit.edu 851832785Speter 851932785Speter (Don't forget the "-request" or you'll send a message to the whole 852032785Speter list, some of whom are capable of remote execution.) 852132785Speter 852232785Speter Mail to the whole list should be sent to: 852332785Speter 852432785Speter info-cvs@prep.ai.mit.edu 852532785Speter 852632785Speter An archive of the mailing list is maintained in the FTP archive 852732785Speter mentioned above. 852832785Speter 852932785Speter Last modified: _6/13/1997_ 853032785Speter 853132785Speter 6. What happened to the CVS Usenet newsgroup I heard about? 853232785Speter 853332785Speter 853432785Speter A Usenet newsgroup named "gnu.cvs.info" was announced in April 853532785Speter 1993, with an expected creation date of August, 1993. However, 853632785Speter nothing came of this. 853732785Speter 853832785Speter If you want to discuss CVS on usenet, the correct group is 853932785Speter comp.software.config-mgmt (which also covers other configuration 854032785Speter management systems). Someday it might be possible to create a 854132785Speter comp.software.config-mgmt.cvs, but only if there is sufficient 854232785Speter CVS traffic on comp.software.config-mgmt. 854332785Speter 854432785Speter kingdon@cyclic.com 854532785Speter 854632785Speter Last modified: _9/6/1997_ 854732785Speter _________________________________________________________________ 854854427Speter 854932785Speter [Add an answer to this category] 855032785Speter 855132785Speter [Category /] 855232785Speter _________________________________________________________________ 855354427Speter 855454427Speter _Search the FAQ-O-Matic:_ ____________________ Search 855532785Speter [matching all words] 855654427Speter Or look for questions modified in the last: [7.] Days 855732785Speter _________________________________________________________________ 855854427Speter 855932785Speter The FAQ-O-Matic lives at http://gille.loria.fr:7000/cgi-bin/faqomatic. 856032785Speter The code was written by Jon Howell, and the content by folks from all 856132785Speter over the web. 856266525Speter _________________________________________________________________ 8563