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