diff options
Diffstat (limited to 'contrib/cvs/FAQ')
| -rw-r--r-- | contrib/cvs/FAQ | 8562 |
1 files changed, 0 insertions, 8562 deletions
diff --git a/contrib/cvs/FAQ b/contrib/cvs/FAQ deleted file mode 100644 index 13feb52..0000000 --- a/contrib/cvs/FAQ +++ /dev/null @@ -1,8562 +0,0 @@ -------------------------------------------------------------------------------- - - CVS is Copyright (C) 1986-2006 The Free Software Foundation, Inc. - - CVS is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 1, or (at your option) - any later version. - - More details are available in the COPYING file but, in simplified - terms, this means that any distributed modifications you make to - this software must also be released under the GNU General Public - License. - - CVS is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - -------------------------------------------------------------------------------- - -This file contains a CVS FAQ. Until 1995 it was maintained by David -Grubbs. It was out of date and not being maintained, but it had a -certain following and in 1997 Pascal Molli decided to start -maintaining it with the FAQ-O-Matic package which allows any -contributor with a web browser to help maintain it. The following -text is (mostly automatically) extracted from the FAQ-O-Matic. The -odds are good that the file that you are currently reading is out of -date with respect to the online FAQ-O-Matic, which is part of Pascal -Molli's CVS web site at http://www.loria.fr/~molli/cvs-index.html -(currently under "Documentation"). The online version is also -somewhat better in terms of things like tables of contents (at least -until someone can write some code to extract data from a FAQ-O-Matic -and insert things like tables of contents). - -The answers which are dated "6/13/1997" below are really from the 1995 -FAQ, for the most part. Many of them are out of date. The current FAQ may -be found at <http://ximbiot.com/cvs/wiki/index.php?title=CVS_FAQ>. If you have -some time, you are encouraged to export that FAQ as text and import it here. -If you don't have such time, take the answers in this file with at least a few -grains of salt. - -Since August, 2005, many of the existing CVS resources have been centralized on -<http://cvs.nongnu.org> & <http://ximbiot.com>. - - Category: /, all questions - - Category: / - - " [INLINE] " - - 1. About FAQ-O-Matic - -This is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by -Jon Howell. - -It seems like most FAQ maintainers make a valiant initial effort, then get -a life and don't have time to keep their FAQs up to date. Also, I often -find out a solution to a problem, and feel like I could write a single -FAQ answer on it in a few minutes, but where to post it? - -Thus the FAQ-O-Matic was born. FAQ-O-Matic is a couple sleazy Perl scripts -that allow people to submit FAQ answers to this database, so it can stay -current, with just a tiny bit of work on any one person's part. - -Yes, a bad guy could come along and wipe out all the FAQ entries. Please don't. -But to give the good guys some measure of comfort, each submission is stored -in an RCS file, so if someone does tamper, we can recover the database. - -Guidelines for submissions: - -1. Please _try to be fairly unbiased in matters of opinion._ Mailing lists are -the place to start flame wars (just kidding :v), but definitely not here. - -2. Please _use HTML only conservatively_ in your entries. Links are appropriate -, -but put the URL in the plaintext also so it's useable on printed versions of -the FAQ. Inline images pointing off this site are inappropriate, as is much -fancy formatting. This is meant to be bandwidth-light and dumb-browser-friendly -. - -3. If you feel there's a place for a _new category, or a reorganization of -existing questions_, don't hesitate to mail me (molli@loria.fr). -Category changes need to be done from my end. - -4. Please _leave an email address_ at the bottom of your submission so that oth -ers -can drop you a note. - -5. _If you only have a question_, not an answer, you should probably post -it to a mailing list, not here. If there are frequently asked questions to whic -h -the answer is not forthcoming on mailing lists (or perhaps there's no -useful answer yet other than "no one knows"), then it's appropriate to -post here, in hopes that someone will see it and know the answer. - -6. Please refrain from crude or inconsiderate language. Please don't use -this as a forum for advertising. However, mention of worthy commercial -products is certainly appropriate (even if you sell said product). Just -don't overdo it. :v) - - Last modified: _6/13/1997_ - - 2. Adding a new category ? - -just send me a mail at -molli@loria.fr - - Last modified: _6/13/1997_ - - Category: /Advanced_Topics_/ - - " Advanced Topics " - - Category: /Advanced_Topics_/Branching_and_Mergin/ - - " + Branching and Merging" - - 1. What is a branch? - - Unfortunately, the word "branch" is an overloaded technical - term. It is used in too many different ways in three - categories. It might help to understand some of the issues by - going through the categories: - - How Humans use the word "branch": - - Most development starts with everyone working on the same - software, making changes and heading toward a single goal. This - is called something like "Main Line Development". Note that - though many people do main line development on CVS's "Main - Branch", that is a choice, not a requirement. - - After a release or when one or more developers want to go off - and work on some project for a while, the Software Engineers - assigned to deal with large software issues generate a "Branch - in Development" to support the release or project. (Keep in - mind that a programmer is no more a Software Engineer than a - carpenter is a Civil Engineer.) - - Essentially, the word "branch" implies a way to allow - simultaneous development on the same files by multiple people. - - The above terms are human-oriented. They refer to actions that - people would like to take. They do *not* imply any particular - implementation or set of procedures. Branches in development - can be supported in many different ways. - - How CVS uses the word "branch": - - CVS uses the word "branch" in a number of ways. The two most - important are: - - - The vendor branch holds releases from (normally) an outside - software vendor. It is implemented using a specific RCS branch - (i.e. 1.1.1). - - - The "Main Branch", which normally holds your "Main Line - Development", but is defined as the collection of revisions you - get when you "checkout" something fresh, or when you use the - '-A' option to "update". - - Important Note: The CVS "Main Branch" is *not* the same as the - RCS concept with the same name. If you are using Vendor - Branches, files you have never changed are on three branches at - the same time: - - - The RCS 1.1.1 branch. - - The CVS Vendor branch. - - The CVS "Main Branch". - - The concepts overlap, but they are not equivalent. - - In referring to CVS, "branch" can be used in four other ways: - - - A CVS working directory satisfies the definition of "branch" - for a single developer -- you are on a private "virtual branch" - that does not appear in any of the RCS files or the CVS control - files. - - - The CVS "default branch" is the Repository source for the - collection of files in your working directory. It is *not* the - same as the RCS "default branch". Normally the CVS default - branch is the same as the CVS Main branch. If you use the "-r - <branch_tag>" option to the "checkout" command, you will record - a "sticky" tag that changes your default branch to the one you - checked out. - - - A "magic" branch can be a branch that hasn't happened yet. It - is implemented by a special tag you can check out that is not - attached to a real RCS branch. When you commit a file to a - magic branch, the branch becomes real (i.e. a physical RCS - branch). - - - And, of course, CVS uses "branch" to indicate a - human-oriented "branch in development". - - How RCS uses the word "branch": - - - The RCS "Main Branch" (Synonym: "The Trunk") contains a - series of two-part revision numbers separated by a single '.' - (e.g. 1.2). It is treated specially and is the initial default - branch. (The default default?) - - - The RCS "Default" branch starts out attached to the RCS "Main - Branch". For RCS purposes, it can be changed to point to any - branch. Within CVS, you *must*not* alter the RCS default - branch. It is used to support the CVS idea of a "Main Branch" - and it must either point to the RCS Main Branch, or the Vendor - Branch (1.1.1) if you haven't made any changes to the file - since you executed "import". - - Last modified: _6/13/1997_ - - 2. Why (or when) would I want to create a branch? - - Remember that you can think of your working directory as a "branch for - one". You can consider yourself to be on a branch all the time because - you can work without interfering with others until your project (big - or small) is done. - - The four major situations when you should create a branch: - - When you expect to take a long time or make a large set of changes - that the merging process will be difficult. Both "long" and "large" - are defined in your own environment. - - When you want to be able to "commit" and "tag" your work repeatedly - without affecting others. - - If you ever think you need Source Control for your own work, but don't - want your changes to affect others, create a private branch. (Put your - username in the branch tag, to make it obvious that it is private.) - - When you need to share code among a group of developers, but not the - whole development organization working on the files. - - Rather than trying to share a working directory, you can move onto a - branch and share your work with others by "committing" your work onto - the branch. Developers not working on the branch won't see your work - unless they switch to your branch or explicitly merge your branch into - theirs. - - When you need to make minor changes to a released system. - - Normally a "release" is labeled by a branch tag, allowing later work - on the released files. If the release is labeled by a non-branch tag, - it is easy to add a branch tag to a previously tagged module with the - "rtag" command. If the release is not tagged, you made a mistake. - Recovery requires identifying all revisions involved in the release - and adding a tag to them. - - Last modified: _6/13/1997_ - - 3. How do I create and checkout a branch? - - Suggested technique: - - Attach a non-branch tag to all the revisions you want to branch - from. (i.e. the branch point revisions) - - When you decide you really need a branch, attach a branch tag to the - same revisions marked by the non-branch tag. - - "Checkout" or "update" your working directory onto the branch. - - Suggested procedure when using modules: - - cvs rtag <branch_point_tag> module - - cvs rtag -b -r <branch_point_tag> <branch_tag> <module> - - cvs checkout -r <branch_tag> module - - Suggested procedure when using your working directory, which - contains the revisions of your working files you want to branch from: - - cvs tag <branch_point_tag> - - cvs rtag -b -r <branch_point_tag> <branch_tag> <module> - - cvs update -r <branch_tag> - - In each procedure above, Step #1 applies a non-branch tag to all the - branch point revisions in the module/directory. Though this is not - strictly necessary, if you don't add a non-branch tag to the revisions - you branch from, you won't be able to refer to the branch point in the - future. - - Between steps 1 & 2 you may commit changes. The result would be same - because "rtag -r <oldtag> <newtag>" applies <newtag> to the same - revision that <oldtag> is attached to. You can use this technique to - avoid attaching *any* branch tags until you need them. - - Step B.2 has two corollaries: - - If you plan to create the branch tag before committing anything in - your working directory, you can use "cvs tag -b <branch_tag>" instead - of the "rtag" command. - - The <module> can be a relative path to a directory from which your - working directory was checked out. - - If you have trouble figuring out what <module> to use (or pathname to - use in its place), you can aim it at whatever parent directories you - believe will cover all your work. - - If you are sure the <branch_tag> is not being used anywhere else, you - can even aim it at the whole Repository ($CVSROOT), if you have to. It - might take some extra time, but assuming that your <tag> is a unique - string and you don't use the '-f' option to "rtag -r", "rtag" will - only add a <tag> to files in which it actually *finds* the earlier - <tag>. - - In each procedure above, Step #3 may occur any time after step 2. - Unless you explicitly remove them with "tag -d", a <tag> is permanent. - - The <branch_tag> is an unusual creature. It labels a branch in a way - that allows you to "checkout" the branch, to "commit" files to the end - of the branch and to refer to the end of the branch. It does not label - the base of the branch (the branch point). - - There are two obvious ways to choose the <branch_point_tag> and - <branch_tag> names. But keep in mind that the <branch_tag> is typed by - any developer who wants to work on the branch -- you should make it - mean something to them. - - Style #1 presumes that the simple version string refers to a set of - designed, documented or promised features, not to a specific set of - files. In this case, you tag the branch with the generic Version - string and assume that whenever you refer to "Version", you want the - "latest" set of files associated with that Version, including all - patches. (You can substitute whatever you like for "bp_", as long as - your <branch_point_tag> is some modification of the <branch_tag>.) - - <branch_point_tag> Matching <branch_tag> - - bp_V1_3 V1_3 - bp_Release2-3-5 Release2-3-5 - bp_Production4_5 Release4_5 - - Style #2 presumes that the simple version string refers to the - specific set of files used to construct the first release of - "version". In this case, you tag the branch-point revisions with the - generic Version string and assume that whenever you refer to this - Version, you want the original set of released revisions. To get the - latest patched revisions of the release, you refer to the branch tag - "latest_<branch_point_tag>". (You can substitute what ever you like - for "latest_", as long as your <branch_tag> is some modification of - the <branch_point_tag>.) - - <branch_point_tag> Matching <branch_tag> - - V1_3 latest_V1_3 - Release2-3-5 latest_Release2-3-5 - Release4_5 latest_Production4_5 - - In both styles you can find out what you had to change since the - original release of this Version by typing: - - cvs diff -r <branch_point_tag> -r <branch_tag> - - For Style 1, this is: - - cvs diff -r bp_<branch_tag> -r <branch_tag> - - For Style 2, this is: - - cvs diff -r <branch_point_tag> -r latest_<branch_point_tag> - - Notes on "being on a branch": - - - "update -r <tag>" tells CVS to attach a "sticky tag" to working - directory (in ./CVS/Tag) and the checked-out files (on each line of - ./CVS/Entries). - - - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands - to act as if "-r <tag>" were on the command line. - - - A "sticky" <branch_tag> indicates that the working directory (and - working files) are "on the branch". - - Last modified: _6/13/1997_ - - 4. Once created, how do I manage a branch? - - The most important thing you should know about managing a branch is - that the creation of a branch is not a lightweight act. When you - create a branch, you must also create a set of procedures to keep - track of it. - - Specifically, you must: - - - Remember that the branch exists. (This is non-trivial if you create - a lot of them.) - - - Plan when to merge it back into the main line of development. - - - Schedule the order that multiple branch merges are to be done. - - - If you ever intend to merge branches into each other, instead of - limiting merges of branch work back into the "main line", you must - keep careful track of which parts of which branches have merged into - which other branches. - - The simplest way to deal with branches is to limit their number, - "collapse" them back into the main line as quickly as is reasonable - and forget them. If a group wants to continue working, tell them to - create another branch off the fully merged main line. - - Remember that CVS is just a tool. Over time, it will probably handle - branching better, requiring less careful attendance. But no matter how - good it becomes, the whole idea of "branching" is a complicated - management problem. Don't take it lightly. - - Last modified: _6/13/1997_ - - 5. Are there any extra issues in managing multiple branches? - - If you plan to split from the "main line" and merge back after a time, - the only problem will be scheduling the order of branch merges. As - each branch is merged, the main line must be rebuilt and tested. - Merging multiple branches (i.e. "lines of development") before - building and testing creates more problems than you are ready for. - - If you plan to collapse some branches into others, then move the - combined branches back into the main line, you have to be careful with - the revisions and tags you hand to your "update -j" command, but it - shouldn't be much trouble. - - If you plan to allow every branch to incrementally take the work done - on other branches, you are creating an almost insurmountable - bookkeeping problem. Every developer will say "Hey, I can handle - taking just this little bit," but for the system as a whole it is - disaster. Try it once and see. If you are forced into this situation, - you will need to keep track of the beginning and end points of every - merge ever done. Good Luck. - - Last modified: _6/13/1997_ - - 6. How do I merge a whole branch back into the trunk? - - If you don't have a working directory, you can checkout and merge in - one command: - - cvs checkout -j <branch_tag> <module> - cd <module> - - If you already have a working directory: - - cd <working_directory> - cvs update <== Optional, to bring it up to date. - cvs update -j <branch_tag> - - CVS will print lines beginning with - - 'U' for files that you hadn't changed, but the branch did. - - 'M' for files that you changed and the branch didn't - *and* for files that you both changed that were merged - without overlaps. (This overload is unfortunate.) - - 'C' for files that you both changed in a way that conflicts - with each other. - - You need to go edit all the 'C' files and clean up the conflicts. Then - you must commit them. - - Last modified: _6/13/1997_ - - 7. How do I merge changes from the trunk into my branch or between - branches? - - The idea is similar to the above, but since CVS doesn't treat the main - branch like other branches, you'll have to be more careful. There are - 5 different ways to look at the problem. - - The way to merge *all* changes made on the trunk into a working - branch is to move to the branch you want via "checkout -r" or "update - -r": - - cvs update -r <branch_tag> {optional files} - - Then merge the changes from the trunk into your working branch using - the pseudo-tag named "HEAD": - - cvs up -j HEAD {optional files} - - You will get everything from the branch point of the branch named - <branch_tag> up to the HEAD of the main branch. This is still kind of - strange. If the file is on a branch, HEAD should be the latest thing - on the branch, not the HEAD of MAIN. But that's not the way CVS - (currently) works. - - If you run "cvs up -j HEAD" again after adding more revisions to the - trunk, you may get overlaps for the text you have already merged. It - depends on your version of your RCS "merge" command (actually the "co - -j" option, which depends on the version of "diff3" you configured RCS - to use). - - You can merge the difference between any two <tags> using two "-j" - options on "update" or "checkout". - - Identify the two tags on the branch you want to merge from. - - cvs update -j <tag1> -j <tag2> {optional files} - - This step assumes you were careful about tagging milestones. You can - use this technique for any two <tags> on the same branch, even the - trunk. It is also possible to use tags on different branches, but - you'll have to ponder the meaning of the difference between those two - tags. - - In place of one of the <tags>, you can use a <branch_tag> to refer to - the latest revision on that branch. See 4C.11 and 4C.3 for info on - branch points. - - Merges can also be performed by handing RCS revisions to the '-j' - options, but since revision numbers aren't the same in all files, - merging by number is normally limited to one file. Sets of files with - the exact same trees of branches and revision numbers would work too, - but that's a rare situation. - - To "take" revisions from other branches instead of merging them, see - 4C.19 for an idea. - - A way to gain the effect of merging the main to the branch is to - merge the branch into the main using the normal - - cvs update -A {optional files} - cvs update -j <branch_tag> {optional files} - cvs commit - cvs tag -F -b <same_branch_tag> {optional files} - - See part B of 4D.5 - - Other oddities. - - This also works, but is probably not officially supported: - - cvs update -j N {optional files} - - where N is a number. This will merge all the changes from the branch - point up to the highest revision on the main branch starting with N. - For example, if your highest trunk revision is 1.52, you can use this - to grab revisions from the trunk: - - cvs update -j 1 {optional files} - - Another example: Say you have a branch point at rev 1.2 for a branch - named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2. - Then: - - cvs update -j 1 {optional files} - - will merge the changes from 1.2 to 1.4 - - cvs update -j 2 {optional files} - - will merge the changes from 1.2 to 2.3 - - cvs update -j 3 {optional files} - - will merge the changes from 1.2 to 3.2, which in this example, is - equivalent to the use of "-j HEAD" in part A above. - - The intuitive (at least to me): - - cvs up -j MAIN (or TRUNK) {optional files} - - doesn't work. If the trunk (i.e. "main branch") had an implicit branch - named "MAIN", you could use: - - cvs up -j MAIN:10/26 -j MAIN:now {optional files} - - and refer to date-stamped revisions on the trunk using the - <branch_tag>:<date> support that works on other branches. - - You might also think you could place an explicit tag on branch 1 (or - higher) (e.g. MAINHACK:1) and use it in place of the implicit "MAIN", - but I haven't found the right combination. - - [[If you find working techniques, I'll add them here.]] - - Last modified: _6/13/1997_ - - 8. How do I merge onto the Main Branch a file that exists only on a branch - other than the Main Branch? (i.e. it is in the Attic) - - For how such a file can exist, see 3A.2 and 3A.3. - - For how to avoid creating such a file, see 3A.5. - - Though you might think that the "update -j" command could perform the - "merge" of a file from the side branch to the Main Branch, it isn't - (yet) smart enough. Unfortunately, there is no single CVS command to - do this -- it takes three steps: - - To move something onto the Main Branch from the Attic, you have to - physically move the file from the Attic to the main Repository - directory associated with your working directory. - - It is exactly like resurrecting a removed file. See 3L.4 - - I use something like this: (csh-like syntax) - - set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v - $repos/filename,v - - (If you use relative paths in your Repository files, that first line - becomes: set repos = $CVSROOT/`cat ./CVS/Repository`) - - Now that the file is physically in the right place within the - Repository, "update -A" will make it appear in your working directory - on the Main Branch. Do that now. - - You now have a choice. The act of physically moving the file has - fused together the <branch_tag> branch and the Main Branch for this - file. You can continue that way, making changes along the RCS Main - Branch which CVS will (for this type of file only) treat as both the - Main Branch and the <branch_tag> branch. - - The other choice, which I would suggest, is to re-tag the file with - <branch_tag>, restoring a normal-looking magic branch tag to the file: - - cvs tag -F -b <branch_tag> <file> - - After you have done the above, you can run "update -A" or "update -r - <branch_tag>" to resume whatever you were doing before you started - this procedure. - - Caveat: The final result is a file whose revision tree doesn't look - like it was ever on any branch but the Main Branch until the above - "tag -F -b" command was executed. CVS and RCS have no way of saving - the history of the actions you have just performed. - - Last modified: _6/13/1997_ - - 9. How do I know what branch I'm (working) on? - - Type: - cvs status - - and look at the "Sticky Tag" field for each file. If: - - The *same* tag is on *every* file in your working tree, *and* - - That tag matches the contents of the ./CVS/Tag file, *and* - - That tag is a branch tag, - - then you know what branch you are working on. You can get sticky Tag - information directly from the ./CVS/Entries file instead of "cvs - status". - - If all the sticky Tags don't agree, then your directory is temporarily - inconsistent. This is a feature allowing you to make changes (or - perform merges) to individual files on multiple branches without - checking out the whole directory. - - The sticky Tag on each file in the ./CVS/Entries file (as displayed by - the "status" command) indicates what branch the working file is on. - New files are added to the Tag stored in ./CVS/Tag. - - To force your entire working directory onto the same branch, type: - - cvs update -r <branch_tag> - - Last modified: _6/13/1997_ - - 10. Do I really have to know the name of the branch I'm working on? - - If a developer can't be relied on to know what branch of development - to work on, then either the developer's manager isn't planning - branches properly or the developer has serious problems. - - I have found that one of the hardest concepts to get across to - developers (and some managers) is that "a branch in development" (as - opposed to the use of RCS branches to support some other scheme) is a - heavyweight act. Every time you create a real branch in development, - you must spawn a set of managerial procedures and a schedule by which - you plan to merge each branch into each other branch. Unless you plan - to keep it simple and collapse (by merging and forgetting) branches - quickly, they are not to be created lightly. - - In other words, if you don't regularly attend group meetings in which - the branch to be worked on is a major topic of discussion, then the - group is not managing branches properly. - - We created a couple major branches a few months ago and even the - customer service people refer to the "XYZ branch" as a shorthand for - "continuing development on the XYZ project". - - Last modified: _6/13/1997_ - - 11. How do I refer to the revision where I branched so I can see what - changed since the Branch Point on another branch? - - Given the current <branch_tag> format, there is no direct way to refer - to the branch point, which is more useful in many ways than referring - to the branch, which always refers to the latest revision on the - branch. - - When CVS adds a branch tag, it attaches an RCS symbol to a - non-existent revision number containing the revision number of the - branch point as a prefix. (See Section 3O, on the "tag" command.) RCS - can't use the CVS magic branch tag and many of the CVS commands can't - refer to it. - - To be certain of your ability to refer to a branch point, you must - create a "branch point" tag at the same time as the Branch tag. See - 4C.3. - - Last modified: _6/13/1997_ - - 12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch? - - Because your command creates an RCS branch, not a CVS branch. See the - above discussion on branches. RCS branches are used to support CVS - branches, but they are not the same. You can't act as if you have - direct control over the RCS files. - - The "admin" command was placed there as a convenience to allow you to - execute raw "rcs" commands on the Repository, taking advantage of - CVS's ability to find the files in the Repository. - - But you have to remember that you are using RCS commands on a CVS - Repository, which is not generally safe unless you know exactly what - CVS depends on. - - For one thing, CVS insists on control of the default branch. It is set - either to the Main branch or the Vendor branch depending on whether - you have changed the Vendor's code. If you change the default branch, - you are monkeying with the internals and you will get unexpected - results. - - To set your "default CVS branch" to BRANCH1, you must use "checkout" - or "update" with the "-r BRANCH1" option. Then you have changed CVS's - idea of your "default branch", which has little to do with RCS's - default branch. - - Last modified: _6/13/1997_ - - 13. Is it possible to set the "default CVS branch" for everyone? - - No. It doesn't work that way. - - When using CVS, all administrative information (such as what branch - you checked out) is stored in CVS sub-directories, local to the user. - There is no global state, other than the description and logging files - in the $CVSROOT/CVSROOT directory. - - You tell "checkout" or "update" what branch you want to check out via - the "-r <tag>" option. The default is CVS's "Main Branch". - - I don't see a problem in *designing* a new way to indicate what branch - you get by default, instead of the main one, but that's not how it - currently works. - - Last modified: _6/13/1997_ - - 14. How do I perform a large merge? - - Large merges require a bit more planning to be able to track what has - happened in the inevitable cases where something goes wrong. No tool - can force a "merge" to make perfect sense. - - Though you can handle the details in many different ways, the two ends - of the spectrum of merge techniques are: gonzo and paranoid. - - The gonzo method assumes that you know everything about your sources - so that recovery from failures is "just a matter of typing." You - created the branch this way: - - cvs checkout <module> - cd <module> - cvs tag -b <branch_tag> - cvs update -r <branch_tag> - >>> Edit away. - cvs commit <<== Onto branch - - Now you want to merge your branch back into the Main branch, you are - certain you can make it work, or at least detect all the failures, so - you dive in and hack away: (For simplicity, we will assume you are - collapsing (i.e. merging and forgetting) a side-branch into the Main - branch from your single working directory.) - - cvs update -A - cvs update -j <branch_tag> - >>> Edit the 'C' files and remove the overlaps. - >>> Edit some more to make it all compile and work. - cvs commit - - Looks simple. For more details on the output from the "update -j" - command, see 3P.2 and 4C.6. - - Note: You could also checkout a whole new working directory and - perform the merge at the same time by replacing the two - update commands with these two commands: - - cvs checkout -j <branch_tag> <module> - cd <module> - - The paranoid way is more difficult, but it can catch all sorts of - problems. You created the branch this way: - - cvs checkout <module> - cd <module> - cvs tag <branch_point_tag> - cvs tag -b <branch_tag> - cvs update -r <branch_tag> - >>> Edit away. - cvs commit <<== Onto branch - - The extra tag command places a non-branch tag on the Branch Point, an - act that makes it easier to do "diffs" later. Now we decide to perform - the merge: - - cvs tag <latest_on_branch_tag> - cvs update -A - *1* cvs diff -r <branch_point_tag> -r <latest_on_branch_tag> - >>> *1* shows all the changes on the branch. - *2* cvs diff -r <branch_point_tag> -r HEAD - >>> *2* shows the changes on the trunk since branching. - cvs tag <premerge_tag> - cvs update -j <branch_tag> - >>> Edit the 'C' files and remove the overlaps. - *3* cvs diff - >>> Verify that *3* matches *1*, except for line numbers. - cvs commit - cvs tag <just_merge_changes_tag> - >>> Edit some more to make it all compile and work. - cvs commit - cvs tag <after_merge_cleanup_tag> - - The reason *3* and *1* match so closely is that they are the - differences between two pairs of starting points and ending points - after the same data was inserted. If they are significantly different, - you will want to figure out why. - - NOTE: You will have to tell everyone to stay the hell out of the - Repository while you do this. If they commit something while you are - in the middle of a merge, your job will be much more difficult. If - they "update" at the wrong time, their work will be randomized until - you finish. It's better to call a halt. - - See 3H.13 for some more information about dealing with merges after - import. The last part of the procedure is applicable to any large - merge. - - Last modified: _6/13/1997_ - - 15. Is a Vendor merge any different from a branch merge? - - No. In most ways, a Vendor branch is exactly the same as any other - branch. In a Vendor merge, the data is append to the branch by the - "import" command, rather than by hand-editing, but the merge process - is the same. - - See the "import" command in section 3H. - - Last modified: _6/13/1997_ - - 16. How do I go back to a previous version of the code on a branch? - - - - - You can avoid digging into RCS revision numbers (executing "update - -r (rev)" on each file) by trying one of these: - -Use non-branch tags as you normally would. Non-branch tags - attach to specific revisions, so a "tag (tag)" command would - mark the revisions you have in your working directory, which - are on your branch. If you need to retrieve them, use "update - -r (non-branch-tag)" - - Doing this overrides the sticky (branch-tag) attached to your - working directory with a non-branch tag, which means you won't - be able to commit until you again move forward to the end of - the branch with "update -r (branch-tag)". - -Use the "update -r (branch-tag):(date)" trick. - - This is almost like using the '-D' option, but it looks for - revisions extant on (date) only along the given branch. - - As in #1, you can't commit to this kind of working area, - because it has a sticky date referring to revisions in the - middle of a branch. - -[comment from the audience: You are dreaming.. -this does not work.. try it, you get -No such tag: "MYTAG:May 1" -or similar. I wish it did because I need it. julian@whistle.com] - - -You can branch a branch. - - If you add a branch tag to file in a working directory that was - checked out on a branch, you will branch the branch. This - works just fine, though you'll have to play some games to merge - everything back together again. You'll also create 6-part - revision numbers. (They'll be 8-part revision numbers if you - branch a branch that started out with some unmodified files on - the Vendor branch. Think about it. How does revision - 1.2.4.2.4.2.2.1 grab you?) - - -(fixed formatting, kingdon@cyclic.com) - - Last modified: _9/8/1997_ - - 17. Once I've found the files I want, how do I start changing them? I keep - getting warnings about sticky tags. - - What you probably did was type "cvs update -r <tag>" where <tag> is a - non-branch tag. "update" created a sticky tag for a specific revision, - not a branch. To start working right there, you have to create a - branch to work on. - - You have two choices. - - You can do it in place and keep working: - - cvs tag -b <branch_tag> <<== To tag the current files. - cvs update -r <branch_tab> <<== To move onto the branch. - - You can do it "externally" and create a new working directory: - - cvs rtag -b -r <tag> <branch_tag> <module> - cvs checkout -r <branch_tag> <module> - - <module> can be a relative path within the Repository. - - <tag> in the above is the non-branch tag you placed earlier - that caused the error in your question. Be warned that - if <tag> is not set on all the files (or all the right - revisions) you won't get exactly what you wanted. - - Last modified: _6/13/1997_ - - 18. Why do I get the latest files on the branch when I tried to "update -r - <tag>"? - - If "update -r <tag>" always retrieves the latest files on a branch, - then <tag> is really a <branch_tag>. A branch tag is supposed to be - used to grab a branch to work on. Since you can't modify a file in the - middle of a branch, checking out a <branch_tag> will give you the - latest revision on the branch. - - If you want to "checkout" a specific collection of revisions, you must - use a "non-branch" tag. See the first part of 4C.16. - - Last modified: _6/13/1997_ - - 19. How can I avoid a merge? I just want to move the latest revision on my - working branch directly onto the trunk. - - There is no direct way to do this using CVS, though the technique is - not difficult using shell commands. Here's one way: - - Move your working directory to the Main Branch. - - cvs update -A - - Use "update -p" to grab the latest revision on the branch and write - it over your working files. Make sure you don't have an modified files - -- you will lose them. The following is in "csh" syntax. Change the - wildcard to grab the files you want - - foreach i (Makefile *.cc *.hh) - cvs update -p -r <branch_tag> $i > $i - end - - Commit all the working files onto the Main Branch. - - cvs commit -m 'Moved branch <branch_tag> onto MAIN' - - You should experiment with the above before blasting everything. - - Last modified: _6/13/1997_ - - 20. How to I avoid merge collisions in the RCS $\Log$ data? - - In short, you can't. The RCS $\Log$ keyword is handled differently - from all other RCS keywords. - - On the info-cvs mailing list, there is a periodic discussion that goes - something like this: - - Question: How do I deal with $\Log$? Answer1: You can't do much with - it. Here's how it works. . . Answer2: I've found a limited way to use - it. . . Answer3: Get rid of it. $\Log$ is an abomination. - - I tend to lean toward answer #3. There are only two sets of people who - would ever have access to logs stored within sources files, developers - and source customers. - - For developers: - - Log entries within sources files are notoriously incomplete, rushed, - poorly phrased and in many cases incorrect, making them useless for - debugging or file maintenance. I remember a maxim from "Software - Tools" (I believe): "Read the code, not the comments." No managerial - order or plan for programmer discipline will affect this in the real - world. - - Log entries are usually in an unreadable mixture of styles. Many log - entries are just plain meaningless. Some are foolish. Some are even - insulting. Examples: - - "Corrected spelling of misspelling." "Bug fix." "Reversed stupid - change in previous revisions." "If Joe could do his job, this would - already have worked." - - Log entries are not managed well by the tools. Any merge can cause - conflicts in the $\Log$ data. Branch merges produce incomplete logs. - They can be edited into chaos and they are not regenerated. They waste - space duplicating information available to the developer with a single - command. - - Even if correct when originally entered, as changes are made to the - file, log entries become false over time. Humans are not good at - reading down through a list and remembering only the last change - affecting something. Over time *most* of the log is wrong. - - Even if still correct, the log data is almost useless to developers - without the code diffs. If you can get code diffs, you can display the - log. - - For source customers the problem is even worse. The last thing you - want to show customers is a hodge-podge of tiny comments about large - changes followed by a series of emergency fixes before delivery. If - you distribute sources, then you should provide documentation, or - changelogs reviewed by people who won't let comments like "Fixed for - stupid customer." out the door. - - Conclusion: Though some people would prefer to see in this FAQ - techniques for making the $\Log$ entries the best they can be, I - believe them to be a lost cause. My suggestion is to hunt down, root - out and destroy all occurrences of $\Log$ and the unusable data - attached to it wherever you may find it. - - Last modified: _6/13/1997_ - - 21. Why should I trust automatic merges? - - Some developers have the feeling that three-way merging doesn't work. - They fear and distrust the way the "update" command automatically - merges committed changes from the Repository into the working file. - - Experience has shown that most merges are utterly painless and most of - the rest are easily resolved. The few conflicts that cause headaches - are nearly all due to poor communication between developers, a problem - no source control system can obviate. - - Some developers were troubled in the past by flaky Unix software. I - can't say that everything is perfect, but the tools CVS depends on - (RCS and diff, mainly) are fairly solid nowadays. They work. - - Since it does seem to work for most of us, the algorithm is unlikely - to change soon. Why not test it on a couple trouble spots and if it - works for you, use it for a while? Then you can make an informed - decision. - - Last modified: _6/13/1997_ - - 22. How does CVS decide if it can safely perform a merge? - - CVS can merge any text file, possibly discovering a conflict and - leaving overlaps for you to edit. Editing the conflict markers out of - the file is a moment's work, but resolving the conflict could take an - arbitrary amount of time. CVS works to determine if it *should* merge, - not if it *can*. - - See 2B.6 for how the merge proceeds. - - Last modified: _6/13/1997_ - - 23. After resolving merge conflicts in a file, what if I want to keep my - previous version, and not take any of the branch changes? - - If you want to retain your previous version, a version on the MAIN - branch greater than 1.1 (one you committed there), just throw the - merged file away and "cvs update" the file. - - You don't need to commit something to remember it. The tags you place - before and after the merge should give all the handles you need to - find various versions. You don't have to create a new version of the - file. - - If you want to retain the previous Vendor revision, you can grab a - copy of it using "cvs update -p" and commit it or use the technique - described in 3B.3 to revert back to the Vendor branch. - - Last modified: _6/13/1997_ - - Category: /Advanced_Topics_/Engineering/ - - " + Engineering" - - 1. Where can I find out about Software Engineering? - - A couple different people suggested this book: - - Software Configuration Management: Coordination for Team Productivity; - Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0 - - A number of others suggested Appendix B of the book "Decline and Fall - of the American Programmer" by Ed Yourdon, called "The Programmer's - Bookshelf". It list 87 books you are expected to have read. Since they - publish many of the books, Prentice-Hall distributes this list as - "Prentice Hall Professional Technical reference PTR-125-AA3. - - One interesting item from the Yourdon book: The total number of - professional computer books sold is less than the number of - programmers currently in the United States. It wasn't clear from the - book whether this meant "per year" or not, but it is still - frightening. - - Last modified: _6/13/1997_ - - 2. How do I flexibly arrange the modules file to describe my sources? - - An equivalent question might be, "How do I structure my sources?" This - can be a difficult question especially in the areas that are more - political than technical. - - Generally you want to think about which pieces of your system need to - be checked out together, built as one system or tagged as a consistent - whole. You should certainly create module names that correspond to - complete, buildable collections that you would tag and release as one - "product". It is also convenient to create module names for small - sections of the Repository containing files that will all be worked on - at the same time by the same person or group. - - Once you have defined the structure of your work, you can usually see - how to lay it out in a Repository. After that the modules file is - easy. You set up module names and aliases to match what you need to - check out by name. If you like relative directories, it is possible, - but not recommended, to work completely without a modules file. See - 1D.11 and 2C.7 for some info about the modules file. - - Here are a few types of modules. You should experiment to see what - kind of structure each of these produces. They all have different - uses. - - Connected projects in one group with two separate helper - directories. The helper directories can contain build tools, header - files, libraries, or whatever you like. - - These are all aliases that checkout relative pathnames. The equivalent - results could be produced by placing the selected relative pathnames - on the "cvs checkout" command line. - - pr1 -a P1 HELPERS - pr2 -a P2 HELPERS - pr3 -a P3 HELPERS - pr12 -a P1 P2 HELPERS - pr13 -a P1 P3 HELPERS - pr23 -a P2 P3 HELPERS - - P1 -a group1/proj1 - P2 -a group1/proj2 - P3 -a group1/proj3 - HELPERS -a group1/helper1 group1/helper2 MAKEFILE - MAKEFILE -a group1/Makefile - - Actual Repository directory structure: (from $CVSROOT down) - - group1/ Makefile The top level Makefile. helper1/ helper2/ Helper - files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/ - Files and dirs - - "checkout group1" produces a duplicate of the above. "checkout projX" - produces all but "projY" and "projZ". "checkout projXY" produces all - but "projZ". - - Here is the exact same set of module names describing the same - Repository layout using module names (and aliases containing module - names) instead of merely aliases for relative pathnames. - - There is one difference in the result. The name of the top level - directory in the checked out working tree will match the "module" name - (e.g. pr1) instead of always being "group1" as it was in the first - example above. - - pr1 group1 proj1 &HELPERS - pr2 group1 proj2 &HELPERS - pr3 group1 proj3 &HELPERS - pr12 group1 proj1 proj2 &HELPERS - pr13 group1 proj1 proj3 &HELPERS - pr23 group1 proj2 proj3 &HELPERS - - HELPERS -a helper1 helper2 group1-Makefile - helper1 group1/helper1 - helper2 group1/helper2 - group1-Makefile -d . group1 Makefile - - The above line (with the -d in it) says that when the module named - "group1-Makefile" is checked out, the file named Makefile file will be - found in a directory named $CVSROOT/group1 and will be checked out - into a directory named '.', which obviously already exists. - - The & references say to interpret those pathnames relative to the - directory where the whole module is stored. For the "pr1" module, that - directory is "group1", so the &HELPERS reference winds up placing - Makefile in '.' relative to "group1". - - A short one containing the basic "module" actions: - - m1 head/path file1 dir2 file3 dir4 file5 - - When checked out, a directory named "m1" appears in your current - directory. Elements named file1, dir2, file3, dir4, and file5 appear - in it. They were originally taken as relative paths from - $CVSROOT/head/path. - - Here's another way to construct a working directory out of pieces of - the Repository: - - projX projX Makefile &projX_inc &projX_src &projX_doc - - # The first line selects a single file within projX, plus - # the contents of three other modules. Those three other - # modules rename their directories. - - projX_inc -d include projX/inc projX_src -d source projX/src projX_doc - -d documentation projX/doc - - A Unix tree. This is similar to what CVS was developed for and the - way I have used it for years. - - # Top level - unix unix - u_bin unix/bin - u_etc unix/etc - u_man unix/man - usr-bin unix/usr.bin - - # Subdirs of top level dirs. (tiny subset) - ls unix/bin/ls - fsck unix/etc/fsck - man8 unix/man/man8 - - # Programs without subdirs. (tiny subset) - cat unix/bin Makefile cat.c - uniq unix/usr.bin Makefile uniq.c - - # /usr/local/src - localsrc localsrc - gnu localsrc/gnu - public localsrc/public - X11 localsrc/X11 - - # GNU and PD tools - cvs localsrc/gnu/cvs - emacs localsrc/gnu/emacs - rcs localsrc/gnu/rcs - btoa localsrc/public/btoa - tcsh localsrc/public/tcsh - - # X11 related items. - tvtwm localsrc/X11/contrib/tvtwm - - "unix" was checked out and built from the top down, using a set of - Makefiles that knew about the whole structure. "localsrc" was kept - checked out in /usr/local/src. - - At any time I could run "checkout ls" or "checkout cat" and get a - simple directory with only that tool in it, plus a subset Makefile - that knew how to build that tool against the installed (or alternate, - via environment variables) headers and libraries. - - I found it very handy to be able to run "ls" and see the three tools I - was porting that week. - - Last modified: _6/13/1997_ - - 3. Can I have multiple source repositories, one for each project? - - Yes, you can have as many Repositories as you like. But each - Repository must be managed separately, creating additional work. - - Question 4A.1 provides a short description of setting up a single - Repository. A few additional considerations: - - It is a good idea to start by creating a single Repository and split - it up (or create additional Repositories) only if you believe it is - really necessary. I would only create a new Repository if the data is - completely disconnected from the rest of the main Repository. - - If there is a lot of overlap among the developers working on the - collections of files you want to place in different Repositories, or - if there is any connection between those collections, I would go out - of my way to create a single Repository. It is much easier to manage. - - Disk space should not be a factor since you can build up a - Repository using symbolic links and/or remote mounts. - - Each Repository is completely distinct. You can't check out modules - from different Repositories at the same time. A better way of looking - at it is that if you *can* check out two modules or directories with a - single "checkout" command (without contortions or explicit absolute - pathnames), then they are in the same Repository. - - To "checkout" modules from multiple Repositories, you must use the - "cvs -d" option on all CVS commands or alter your $CVSROOT variable - when you change focus to another Repository. If you work with multiple - Repositories, it is a good idea to configure CVS to use absolute - pathnames in the ./CVS/Repository file, since most commands (other - than "checkout") will use that file rather than $CVSROOT. - - If you configure CVS to use relative pathnames in your - ./CVS/Repository files, you must always be careful to set your - $CVSROOT properly or you will get unexpected results. - - If you have two modules or directories by the same name at the same - relative path inside two different Repositories, you are asking for - disaster. You could unexpectedly update a directory with completely - unrelated files. This is not a fanciful example -- a Repository is - occasionally duplicated for release purposes in which case *all* the - paths in the two Repositories are the same. - - Last modified: _6/13/1997_ - - 4. Who should administer the Repository and manage the modules file? - - This is a "management style" question. In large or traditional groups, - the CVS procedures are warped to conform to local conventions. In - small groups, in groups with strong personalities or on new projects - the choice of source control procedures can help create some of the - working environment. Here is a taxonomy of environments I have worked - in or helped set up: - - Situation 1. - - A small number of competent developers working on a medium size - project. We all got along and we all respected each other (at least - technically). Anyone edited anything. - - Modules and Repository admin was mostly left to me. I never found a - problem in minor changes made by anyone else. - - Situation 2. - - A large number of experienced developers sprinkled with wackos. Many - of the developers didn't want to deal with any kind of source control. - They wanted a full-service source control system that caused them zero - thought. - - I learned "big stick" diplomacy here. There was a small number of - "designated" (by me) people who were allowed to do *anything* other - than "update" and "commit". Even "checkouts" were controlled. This is - where I found "history" and "release" the most useful. - - Situation 3. - - A small number of developers who wanted me to "help", but who didn't - want to deal with anything other than their favorite algorithms. - - I didn't have the time to baby-sit this group, so I designated one of - them to be my official contact and made him do it all. He felt sullied - by the requirement to pay attention to anything other than his pet - coding projects, but enjoyed the "status" of being the only one who - could touch the control files without my kicking the chair out from - under him. - - Situation 4. - - A huge number of developers of covering the whole spectrum of - competence and experience split into 20 groups, none of which - cooperated with the others, working on 57 different projects, most of - which didn't inter-operate. - - Managing it in any coherent way was not my responsibility (and beyond - my tolerance for chaos). Too many people. So I privately designated a - person in each group to be the contact and kept watch on the - Repository activity. When something went wrong, I notified the contact - for the group and told him what was happening and *he* kept his troops - in line. They were tougher with their own group that I would have - been. - - Eventually only a few people were willing to touch the control files, - since they were flamed from all directions if they screwed up. - - Situation 5. - - In a medium group of really *serious*, and seriously overworked, - people, someone else was designated the "master". I convinced the - master I knew what I was doing and went on my way. - - No one else in the world was allowed to touch anything. - - Situation 6. - - In a large amorphous group of beginners, experts and clowns, over whom - no one had official control, I was forced to employ a group of - relative beginners (who became experts rather quickly) to police the - world. The ultimate in locking the barn after the horse was stolen, we - kept Chaos from destroying us only by use of superior firepower. - - My choice, if allowed, is to let anyone touch anything. I keep backups - of important items and let people know individually whether I want - them to touch things or not. If someone on my "no touch" list touches - and succeeds, they are allowed more slack. If they screw up after - being warned, their screwup becomes public. After a few months, I - usually have no trouble keeping the world running smoothly, at least - from my (and CVS's) perspective. - - Last modified: _6/13/1997_ - - 5. Isn't disk space a big factor? CVS copies files out of the Repository, - duplicating everything. - - Everyone knows that disk space is getting cheaper. How do we reconcile - this with the equally well-known problem that *all* disk is *always* - filled up? - - In my opinion, the main reason disk space will never be an unlimited - resource is that it is the major variable in organizational time/space - tradeoffs. It isn't a problem of waste or an aspect of Murphy's law, - as some claim it is, but rather a direct consequence of good - management. Disk space is, and will always be, a limited resource. - - First, the cost of *deploying* that disk is not dropping as fast as - the cost of the storage medium. The cost of machines to hold the disks - and the networks to connect them are dropping more slowly than disk - media. And the cost of the human time necessary to manage the - machines, networks, disks, and the developers using them, is not - dropping at all. The cost of human time continues to rise. - - If management decides that expensive human time can be saved by using - all that new disk space to keep the last three releases online, then - that's what it will be used for. If each release takes up a Gigabyte - and you support 30 platforms, a simple time-saving suggestion has just - grabbed 100 Gigabytes of disk space. And we've ignored the potential - disk storage needed to support "better Customer Service", another - management refrain. - - Even at 30 cents per Megabyte (next year's price), you've just used up - $30,000 of disk space. And that doesn't count the computers, tape - drives and humans necessary to maintain and deploy all of it. Spending - money to save time has its own overhead, too. - - Binaries are getting bigger. Graphics and data collection devices can - eat up any amount of disk. There are more tools available, more - libraries, more raw data than you can ever store. My home computer has - a Gigabyte of disk on it. It could easily handle 30. - - The "economy" of disk storage media will never remove the need to - manage disk space. - - So, here's an un-reviewed suggestion originally from Graydon Dodson - <grdodson@lexmark.com>, which I've altered and edited heavily. - - - Keep a directory where the whole tree is checked out. (It might be - built and tested once in a while to make sure it is worth linking to, - but that doesn't affect the source control aspect of this procedure). - Let's call it /master/build. - - - Write a tool that creates a tree of directories (like the X11 - "lndir" command) filled with links to the checked out files in the - /master/build tree. - - This tool should also provide real copies of, not symlinks to, all the - files within the CVS administrative directories. - - - You could also provide a way for the tool to take a list of whole - directories that you will never change, for which it would create a - single symlink to the directory and not a subtree of symlinks to - files. Or you could rm -r pieces of the resulting working directory - yourself and replace it with links. - - - If you want to edit a file, you have to grab a real copy and keep it - until your revision shows up in the /master/build tree. I'd create a - script to do this: cvsgrab <file> - - #!/bin/csh -f - set f = $1 - if (! -l $f) then - echo "file $f is not a symlink" - exit 1 - endif - rm $f - set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'` - cvs update -p -r $rev $f > $f - - You can't do a plain "cvs update" since that would grab newer - revisions from the Repository, not the revision you wanted to start - with. After the file is no longer a symlink, you can work normally. - You'll have to run "update" before "commit" anyway if there are newer - revisions. - - - Presumably there would also be a tool to traverse the link tree and - revert it to links if there are no modified files and/or if all the - real files match the revision of the /master/build tree. - - - To avoid confusing CVS when the /master/build revisions are updated - but your CVS/Entries files is not, CVS would have to change to handle - symlinks. It currently causes problems with this scenario: - - ./<file> is a symlink. - - ./CVS/Entries says you are revision 1.2. - - The corresponding CVS/Entries file in /master/build says the latest - revision is 1.3. - - cvs update <file> shows a 'C' conflict flag. - - Last modified: _6/13/1997_ - - Category: /Advanced_Topics_/Installing_CVS/ - - " + Installing CVS" - - 1. What do I have to do before I install CVS? - - You must decide where to set up a Repository. - - Though you can construct a Repository tree structure using links and - mount points, there must be a single copy of each real file across - your entire organization. You may not "rdist" files and expect to edit - both copies. - - CVS does not support a truly distributed Repository. You can have - multiple Repositories, but each one must be mounted (not copied or - "rdist"ed) from a single place onto all machines where it will be - used. - - Initially, a Repository takes about same amount of disk space as the - sources you want to put into it, plus a bit of overhead for the RCS - files. - - See Section 4B. For multiple Repositories, see 4G.3 - - You need a directory in everyone's $PATH variable where you can - install all the executables. /usr/local/bin is a common place. - - You need some helper tools besides CVS such as "RCS" and a good set - of "diff" and "diff3" programs. See 1B.4 for suggestions. - - Read the README, INSTALL and ChangeLog files to see what you are - getting into. - - Though you can probably muddle along without it, you should appoint - one or more "Repository Administrators" who will be responsible for - maintaining the Repository structure, administrative files and the - "modules" interface. - - Someone at your site should probably be on the info-cvs mailing list. - See 1B.5. - - Last modified: _6/13/1997_ - - 2. How do I configure the CVS programs? - - You should certainly start by reading the README file, the INSTALL - files and possibly the ChangeLogs in each directory, the Makefile.in - files and the "cvsinit.sh" program. - - Execute the ./configure command. - - Type "make". - - After running "make" you might try running the "sanity.sh" script: - ./src/sanity.sh `pwd`/src/cvs - - It writes into /tmp/cvs-sanity by default. - - Finish reading the INSTALL file and test out the system. - - Last modified: _6/13/1997_ - - 3. What do I have to install? - - Install the "cvs" executable and "mkmodules" from the CVS sources. - The man page is useful too. If you plan to report bugs, you should - also install "cvsbug". - - Set your $CVSROOT environment variable and create the Repository - (which you planned out in 4A.1) with the "cvsinit" command at the top - of the CVS sources. - - You'll need to edit the Repository control files created by - "cvsinit". - - Install any helper programs mentioned in the modules file. - - Last modified: _6/13/1997_ - - 4. How do I work around the merge problems in GNU diff version 2.1 or - later? - - See 1B.4 If you use recent versions of RCS and "diff", you won't run - into the above. If you do, see 5B.8 - - Last modified: _6/13/1997_ - - Category: /Advanced_Topics_/Internal_errors/ - - " + Internal errors" - - 1. Explain: "ci error: unexpected EOF in diff output" - - RCS versions earlier than 5.5 print the above error when a file does - not end in a newline character. It can be caused by: - - - Editing with Emacs and not using "require-final-newline". - - Committing a binary file. - - Filesystem failures (NFS!) that put nulls in your file. - - The solution is to upgrade to RCS 5.5 or later. (Of course, this won't - fix filesystem failures. It will merely allow RCS (and therefore CVS) - to handle the file without error.) - - Last modified: _6/13/1997_ - - 2. Explain: "RCS file /Repository/module/file.c,v is in use" - - This is an RCS error that occurs when its internal lock file has been - left around by an RCS command interrupted by some sort of system - crash, disk failure or SIGKILL signal. - - Go into the Repository and look for files with names similar to - "file.c,v", usually starting with ',', '_' or '#'. Make sure they are - really crash remnants and do not belong to transactions in progress -- - a recent last-modified timestamp is a good indicator of a live - transaction. Delete them if they are old. - - Last modified: _6/13/1997_ - - 3. Explain: "co error, line 2: Missing access list" - - This is an error message from RCS Version 3 when it tries to read a - file created by a later version of RCS. - - HP decided to "standardize" on an ancient version of RCS some time - ago. You can't use it for CVS. See 4H.6. - - Since the error comes from having a later version of RCS than HP - supports, you probably did install the later version but must have - recently changed your $PATH or installed the HP package that has RCS - in it. - - You should either reconfigure CVS to use absolute pathnames to the - proper versions of the RCS programs that CVS uses, or change your PATH - to look there first. If you haven't installed the latest version of - RCS, you should upgrade. See 1B.4 - - Last modified: _6/13/1997_ - - 4. Explain: "error: RCS file name `xyz .c' contains white space" - - RCS 5.6 doesn't allow white space in filenames. Apparently this - restriction will be removed in RCS 5.7, but CVS may still require that - filenames have no white space in them. - - Last modified: _6/13/1997_ - - 5. Explain: cvs checkout: warning: <X> is not (any longer) pertinent - - This message occurs in three instances: - - When there is an entry in the ./CVS/Entries for file <X> and there - is no RCS file in the Repository to back it up. - - If the working file exists, and hasn't changed (determined from the - timestamp) it is removed. - - When you try to check out a piece of the Repository with: - - cvs checkout some/place/in/repository/tree - - and at least the first element of the path (i.e. "some" in the above) - exists, but some part of the rest of it does not. - - The checkout command checks the modules file first for the whole path, - then for a prefix of the path as a module name. If it doesn't find - *any* portion of your path in the modules file, it says: - - cvs checkout: cannot find module `<module/path>' - ignored - - If it finds some set of prefix directories, it prints the message you - see. - - In practice this is usually a spelling error. - - If the Repository files you are trying to check out or update are - not readable by you, the same problems can occur. Check the - permissions on the files involved. - - Last modified: _6/13/1997_ - - 6. Why did a Repository file change from <file>,v to ,<file>,? - - This is an RCS problem, since the ,<file>, syntax for file names is - used by RCS and not CVS. - - RCS constructs a new <file>,v in a temporary file named ,<file>, - (which doubles as a lock file) then renames it to <file>,v when it is - done. The only way this is reliable is if your system's version of - rename(2) is an atomic, as required by POSIX. - - If your system has a non-atomic (and therefore non-POSIX) rename(2) - system call, RCS runs uses an internal version of this algorithm to - approximate the atomic rename: - - rm <file>,v; ln ,<file>, <file>,v; rm ,<file>, - - If the system crashes, or you lose your NFS connection between the - first "rm", but before the "ln", you can be left only with the - ,<file>, file. If the crash or network failure occurs between the "ln" - and the final "rm", you could be left with a pair of linked names. - - Recovery: - - If only the ,<file>, exists, rename it to <file>,v. - - - If both ,<file>, and <file>,v exist and are linked, remove the - ,<file>, file. - - - If both ,<file>, and <file>,v exist and are separate files, look at - the dates, "diff" them and make your best guess. This sounds like the - remnants of two separate events. - - Last modified: _6/13/1997_ - - Category: /Advanced_Topics_/Other_Systems/ - - " + Other Systems" - - 1. I use a NeXT. Is there anything I need to know? - - NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather than - the files used in previous revisions. It removes files it doesn't - recognize, making it impossible to place such a directory under CVS -- - the CVS admin directory will be removed. - - Some time ago, <Bob_Vadnais@pdh.com> posted a palette named CVSPalette - that claimed to resolve this problem. It was intended to preserve the - CVS administrative directories within nib documents (directories) that - Interface Builder usually removes. - - CVSPalette is no longer in its announced place: - - ftp.cs.orst.edu:/pub/next/submissions - - though I did find two other interesting files on ftp.cs.orst.edu: - - /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z - - which is a port of CVS 1.3 (along with RCS and diff) and: - - /software/NeXT/sources/programming/cvs.postamble-2.4.gz - - which appears to be a set of wrappers for CVS commands that claim to - allow you to use CVS effectively (and without need for the "command - line") on a NeXT machine. - - [[Anyone know the truth about CVS and NeXT?]] - - Last modified: _6/13/1997_ - - 2. I use OS/2 and/or DOS and/or Windows. Is there anything I need to know? - - When using a local repository, be sure to specify the local access - method or CVS will interpret the drive letter as a remote host name - due to the : following it: - - WRONG: CVSROOT=C:\SRC\CVSROOT - - RIGHT: CVSROOT=:local:C:\SRC\CVSROOT - - (larry.jones@sdrc.com) - - You can share RCS files between Unix and DOS while avoiding the MS-DOS - file name limits by setting your RCSINIT environment variable to - '-x/,v'. New RCS files will be created without the standard ",v" - suffix, though files ending in ",v" will still be found if there is no - matching file in the same directory without the ",v". - - Erik van Linstee offers an OS/2 and a DOS port of CVS 1.3 in: - - ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools or - ftp.rrzn.uni-hannover.de:/pub/os2-local - - The files are named: - - cvs13p?[bs].zip - - Where the ? stands for the patch level (currently 8) and the b is for - the binaries, the s for the sources. - - There are three binaries. An OS/2 only one (32-bit), a DOS only one - (16-bit) and an EMX one that runs on both (32-bit). - - There are many differences between the Unix and the DOS versions of - CVS. Read the material that comes with the DOS version before using - it. - - [[Updates?]]. - - Last modified: _9/22/1997_ - - 3. I use SCO Unix. Is there anything I need to know? - - On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the - configure program detects POSIXness and configures in the use of POSIX - signals. Workaround : Edit out the check for POSIXness in the - configure script. [[You could also remove all occurrences of - "-DPOSIX=1" from the Makefiles after configure is run. -dgg-]] - - SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks the - use of log.pl as it gets invoked by /bin/sh instead of - !#/usr/local/bin/perl. WorkAround : edit log.pl and change it into a - shell script which invokes perl with log.perl (renamed from log.pl) as - input. - Contributed by Joe Drumgoole - - Last modified: _6/13/1997_ - - 4. I use AIX. Is there anything I need to know? - - The only report on AIX claims to have no trouble using it in concert - with SunOS and IRIX platforms. - - Last modified: _6/13/1997_ - - 5. I use IRIX. Is there anything I need to know? - - If you see "uid" numbers where you would expect user names, try adding - -lsun to the link line. Without it CVS is unable to retrieve "passwd" - data through NIS. - - Last modified: _6/13/1997_ - - 6. I use an HP system. Is there anything I need to know? - - HP distributes RCS version 3 (a circa 1983 release!) with HP-UX. CVS - does not work with RCS version 3; it requires RCS version 4 or later. - Your best bet is to find the latest version of RCS and install it - somewhere. - - HP-UX 8.07 has a serious bug with the mmap system call and NFS files; - the bug can crash the operating system. Make sure that you configure - RCS to avoid mmap by setting has_mmap to 0 in RCS's conf.h. This bug - is fixed in HP-UX 9. - - Contributed by Paul Eggert - - If using the setgid() trick described in 4D.13, you will have to - create an entry in the /etc/privgroup file to give the group assigned - to the cvs executable setgid permission (see setprivgrp(1m)). - Additionally, if you are restricting "read" access to the Repository - by limiting access to the executable (this requires yet another - group), then you will require that /etc/logingroup exists and is - configured correctly (usually it's just alink to /etc/group). - - Contributed by Dale Woolridge - - Last modified: _6/13/1997_ - - 7. I use AFS. Is there anything I need to know? - - There is a problem with the way CVS performs its locking when the - files are within AFS. When your current PTS id != your uid, the locks - are not deleted. The stat() system call returns the PTS id of the - owner. If that id != your uid, CVS assumes you did not lock it, and - leaves the lock files alone. The next time you try to use it, it - complains that someone has the repository locked. - - Contributed by Michael Ganzberger - - [[This was against CVS 1.3. Is it still in CVS 1.4?]] - - Last modified: _6/13/1997_ - - 8. I use A/UX. Is there anything I need to know? - - [[??]] - - Last modified: _6/13/1997_ - - Category: /Advanced_Topics_/Related_Software/ - - " + Related Software" - - 1. How do I use CVS under Emacs? Is there an Emacs cvs-mode? - - The pcl-cvs package distributed with CVS is an emacs package that - helps with the update/commit process. When you are ready to update, - you use the 'cvs-update' command within emacs. This executes "update" - and fills a cvs-mode buffer with a line for each file that changed. - The most helpful features are: descriptive words for what happened - (i.e. Merged or Conflict rather than 'U' or 'C'), single keys bound to - diffs and commits, and the ability to mark arbitrary groups of files, - possibly from different directories, for commit as a whole. - - All the developers in my group that use emacs find pcl-cvs a much - friendlier and more helpful way to update/commit than raw cvs. One vi - user even converted to emacs just to use pcl-cvs. - - Contributed by Jeffrey M Loomis - - Last modified: _6/13/1997_ - - 2. What is GIC (Graphical Interface to CVS)? - - - - - GIC provides a graphical user interface to the Concurrent Version - System (CVS), a powerful revision control system. GIC is - implemented in the Tcl/Tk programming language and is intended to - augment the sometimes cumbersome CVS command line interface. - - Note that according to the official GIC page at - http://www.cpsc.ucalgary.ca/redirect/grouplab/projects/gic/ - GIC is no longer being maintained and tkCVS is recommended - instead. - - For more on tkCVS, see - <http://ximbiot.com/cvs/cvshome/dev/addontkcvs.html>. - - kingdon@cyclic.com - - Last modified: _9/6/1997_ - - 3. What is CAVEMAN? - - CAVEMAN is a front end to CVS written in PERL providing a collection - of features desired by the site where it was developed. - - - The ability to spread a "project" over multiple Repositories. - - Optional automatic tagging after each commit. - - Additional locking of files. - - Extra before and after program hooks. - - A layer of event logging. - - All sorts of error messages. - - Many changes to the semantics of commands. - - It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18] in - gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.) - - contact Kathleen Dyer kdyer@llnl.gov - (510)423-6803 - (510)423-5112 FAX - - [[Does someone want to elaborate?]] - - Last modified: _6/13/1997_ - - Category: /Advanced_Topics_/Setting_up_and_Manag/ - - " + Setting up and Managing the Repository" - - 1. What do I do first? How do I create a Repository? - - First, install all the programs. (See Section 4A.) - - Then create a Repository by executing "cvs -d init". (This works with - CVS 1.9.) - - Now you can configure your repository by checking out CVSROOT: "cvs -d - checkout CVSROOT". Change into the created directory CVSROOT. Edit the - files you want to edit, and afterwards, commit the changes by typing - "cvs commit". - - You will certainly want to add modules of your own. Edit the "modules" - file and add lines to describe the items you want to "checkout" by - module name. Here's a short list that could be used for storing a - small number of GNU and PD sources: - - local local - - gnu local/gnu - emacs local/gnu/emacs - cvs local/gnu/cvs - - public local/public - pdprog1 local/public/pdprog1 - pdprog2 local/public/pdprog2 - - test test - junk test/junk - - Andreas Kostyrka - - Last modified: _4/21/1998_ - - 2. What are those files in $CVSROOT/CVSROOT? - - There are eight Repository control (or "database") files of interest - in the CVSROOT directory: - - modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and - 4B.7 for more details. - - commitinfo contains two columns: 1. a regular expression to match - against pathnames within the Repository and - - a <command> to execute for matching pathnames. - - When you execute "commit", CVS passes the Repository pathname for each - directory (and the files to commit within that directory) to - <command>. If <command> exits with a non-zero status, the commit is - blocked. - - A <command> associated with a pathname of "DEFAULT" is executed if - nothing else matches. Every <command> associated with a pathname of - "ALL" is executed separately. - - rcsinfo contains the same first column as commitinfo, but the second - column is a template file for specifying the log entry you are - required to enter for each commit. - - "DEFAULT" and "ALL" work the same as in the commitinfo file. - - editinfo contains the same two columns as commitinfo, but the - <command> in the second column is intended to do some consistency - checking on the commit log. - - "DEFAULT" works as in commitinfo. - - loginfo contains the same two columns as commitinfo, but the - <command> is expected to read a log message from its standard input. - The <command> can do anything it wants with the log information, but - normally it is appended to a log file or sent to mailing lists. - - "DEFAULT" & "ALL" work the same as in commitinfo. - - cvsignore contains "ignore" patterns that are added to the built-in - ignore list. See 2D.10. - - checkoutlist contains a list of other files kept under RCS in - $CVSROOT/CVSROOT that should be checked out by mkmodules to provide a - readable copy. - - history contains a stream of text records, one for each event that - the "history" command is interested in. Though the contents of the - history file can be read, it is intended to be read and displayed by - the "history" command. This file is the only one in the above list - that is not under RCS. - - Last modified: _6/13/1997_ - - 3. Is there any other state stored in the Repository besides in the - $CVSROOT/CVSROOT directory? - - Only in the RCS files. The Repository holds exactly two things: the - tree of RCS files (each usually ending in ",v") and the CVSROOT - directory described above. - - Last modified: _6/13/1997_ - - 4. How do I put sources into the Repository? - - There are three main ways to put files in the Repository: - - Use the "import" command described in Section 3H. - - This method is the fastest way to put trees of new code into the - Repository and the *only* way to handle source releases from a 3rd - party software vendor. - - Use "add" followed by "commit". - - This is how to add new files and directories to the Repository, a few - at a time. Directories don't need to be committed. - - You can move RCS files directly into the Repository. - - You should create a directory hierarchy to hold them, but you can just - move arbitrary ",v" files into the Repository. The only "state" in the - Repository other than within ",v" files is in the required CVSROOT - directory at the top of the Repository. - - Last modified: _6/13/1997_ - - 5. What file permissions should I use on (and in) the Repository? - - If you are using pserver (password-authenticated access), see below. - - If you run a completely open environment (which usually means that you - don't have, or don't want to waste, the time to deal with it): - - - Set all directory permissions to 777. - - - Have everyone set their umasks to 0. - - (BTW, I don't suggest this. I am merely reporting it.) - - If you are a normal Unix shop and want to use groups effectively: - - - Set all the directory permissions in the Repository to 775. - - If you are using a system that handles both System V and BSD - filesystems, you might have to set the permissions to 2775.) - - If you are using one of the many recent versions of Unix that don't - allow you to use the full octal mode, then you'll have to type: chmod - u=rwx,g=rwx,o=rx,g+s dir> - - - Change all the groups on the directories to match the groups you - want to write to various directories. - - - Make sure every user is in the appropriate groups. - - - Have everyone set their umask to 002, including root. - - If you don't want non-group members to even read the files, do the - above, but change: - - - Repository directory permissions to 770. (or 2770) - - - umasks to 007. - - If you work in an environment where people can't be trusted to set - their "umask" to something reasonable, you might want to set the umask - for them: - - mv /usr/local/bin/cvs /usr/local/bin/cvs.real - cat > /usr/local/bin/cvs - #!/bin/sh - umask 2 # Or whatever your site standard is. - exec /usr/local/bin/cvs.real ${1+"$@"} - ^D - - Pserver (Password-Authenticated Access) <blome@de.ibm.com> - - The above suggestions are not valid when you use the pserver facility. - Be sure to read and understand the manual section about this (should - be 4.6.something). Above all: do /not/ make the repository and CVSROOT - group writeable. In CVSROOT, make `history´ group or world writeable - instead. - - I suggest creating one unix group per project group. In the - repository, you would then create one directory for each group, group - writeable. New projects must then be created in these group - directories. If you don't want to say <group>/<project> on - checkout, create a <project> module and point it there. - - Last modified: _9/24/1998_ - - 6. How do I structure my Repository? - - The Repository holds your software. It can be all interrelated or it - can be a bunch of separately managed directories. - - How you break a whole system down into its component parts, while - defining interfaces between them, is one aspect of "Software - Engineering", a discipline that requires the study of dozens of - strange and wonderful areas of the computer and management worlds. - - CVS provides a way to keep track of changes to individual files, a way - to "tag" collections of files, and a way to "name" collections of - files and directories. That's all. Everything else is in the way you - apply it. - - In other words, you should structure your Repository to match your - needs, usually tied in with the other tools you use to build, install - and distribute your work. Common needs include the ability to: - - - mount (or automount) directories from many places in your - organization. - - check out just what you need and no more. - - check out multiple sections in a fixed relation to each other. - - check out large sections to match the assumptions built into your - build system. (Makefiles?) - - In my opinion, you should start small and keep everything in one tree, - placing each major sub-system into a separate directory. Later, when - you know what you are doing, you can make it more sophisticated. - - Last modified: _6/13/1997_ - - 7. Why would anyone use "modules"? They are too restrictive. I want to be - able to select just the files I want to edit. - - Any form of structure is restrictive. If you believe that total chaos - is a viable working paradigm, or if you believe you can keep track of - the interrelations between all portions of your Repository in your - head, then you can do what you please. - - If you believe that systems of files require management and structure, - then the "modules" idea is very useful. It is a way to impose a naming - scheme on a tree of files, a naming scheme that can be simpler than a - large list of relative pathnames. - - The "modules" file represents a published interface to the Repository - set up by your Repository Administrator. If s/he did a creditable job, - the modules offered will be internally consistent and will smoothly - interact with the rest of your environment. - - Last modified: _6/13/1997_ - - 8. How do I rename a file or directory? What are the consequences? - - In CVS there is no single "rename" command. - - See 2C.4 for the suggested way to rename a file or directory. - - The rest of this section covers some of the consequences of renaming. - - A "renaming database" has been proposed that would keep track of name - changes so that "update -r <tag>" would continue to work across the - renaming. But as it stands, you have to pick one of the following - options: - - Use the technique described in 2C.4. (For each file, duplicate the - file in the Repository, "remove" the old version so it winds up in the - Attic and strip all Tags off the new version.) - - - "update -r <tag>" produces the correct files. - - - The duplicated revision history can be slightly misleading. - - - A plain (i.e. without the "-r <tag>") "checkout" or "update -d" will - create directories "renamed" this way, but you can delete it and a - plain "update" won't bring it back. - - Move the files and directories in the Repository to the new names. - - - You save the revision history under a different file name. - - - You save a little space. - - - "update -r <tag>" produces the wrong files or directories. - - This is not a good general solution, but if you plan never to look - back (someone may be gaining on you!), it is sometimes a useful - notion. - - If you are clever with Makefiles, you might be able to rework them to - handle either the new or old names, depending on which ones exist at - the time. Then you can move an old <tag> onto the new, more - sophisticated, revision of the Makefile. (Yes, this changes the - "released" file if <tag> indicates a release. But it is an option.) - - - Important Note: If you rename a directory, you must rename the - corresponding directory in every checked-out working directory. At the - same time, you must edit the pathname stored in the ./CVS/Repository - file within each of the moved directories. - - The easiest way to move a lot of directories around is to tell - everyone to remove their working directories and check them out again - from scratch. - - - The file exists in the working directory and in the ./CVS/Entries - file, but not in the Repository. For the old file, "update" prints: - - cvs update: xyz.c is no longer in the repository - - and deletes the file. If the file was modified, "update" prints: - - cvs update: conflict: xyz.c is modified but no longer in the - repository C xyz.c - - and leaves the file alone. In the new directory, you see: - - U xyz.c - - as you would if someone else executed "add" and "commit". - - For each file, copy the working file to a new name in the working - directory and use the "cvs remove" to get rid of the old old file and - "cvs add" to add the new one. Since there is no way for CVS to remove - a directory, this only works for files. - - - This is what most people think of first. Without a "rename" command, - the remove/add technique seems obvious. - - - You lose the connection of your new working file to its past - revision history. - - Last modified: _6/13/1997_ - - 9. What are "Attic" directories? - - When you use the "remove" command on a file, CVS doesn't delete the - file, it only registers your desire to delete it. - - When you "commit" a removed file, CVS moves the Repository's matching - RCS file into a sub-directory named "Attic" within the Repository. - - Attic files are examined when the '-r' or '-D' option is used on - "checkout" or "update". If the specified revision, tag or date matches - one on a file in the Attic, that file is checked out with the others. - - You can think of the Attic as a sort of dead branch, which is only - looked at when you refer to a <tag> or <date>. - - Last modified: _6/13/1997_ - - 10. Is it OK to remove anything from the Repository? - - In general, removing anything from the Repository is a bad idea. The - information in a deleted object is lost forever. There are many ways - to skip over files, directories and revisions without deleting them. - - Here are some of the consequences of removing the following things - stored in the Repository: - - CVSROOT files (Repository control files) - - The Repository will work without any of them, but you should - understand what you are losing by deleting them. See 4B.2. - - Revisions - - The only way to remove revisions is to use the "admin -o" command (or - the equivalent RCS command "rcs -o"). - - They are lost forever. Any tags formerly attached to deleted revisions - are now pointing into the Phantom Zone. You'll need to contact Jor-el - to get them back. - - Files - - You should not remove a file unless you truly never want to see it - again. If you want to be able to check out an old revision of this - file, use "cvs remove" instead. - - Tags - - Tags take up little space and you can't recover from deleting them. If - you depend on tags for releases you will lose vital information. - - Directories - - There is no Attic for directories, so the only way to remove them is - to use "rm -r". They are gone forever. - - If you delete (or move) a directory, all checked-out versions of that - directory will cause CVS to halt. You'll have to visit each - checked-out directory and remove the matching working directory by - hand. - - Attic files - - The "remove" command sends files to the Attic. To really delete them, - you have to go into the Attic and use "rm". - - If a file in the Attic has a Tag on it that you might ever want to - check out again, you probably don't want to delete it. - - Lock files (named: "#cvs.[wr]fl.<pid>") - - These are lock files. If you are getting "lock" errors and the dates - on the lock files indicate that they are old, you can delete them. - - Deleting lock files still in use by a CVS process might produce - unusual errors. - - Last modified: _6/13/1997_ - - 11. Can I convert to CVS from RCS without losing my revision history? - - Yes, you can simply move (or copy) your RCS files into a directory - within the Repository, check out that directory and start working. - - Last modified: _6/13/1997_ - - 12. Can I move RCS files with branches in them into the Repository? - - Yes, but they may not work if you created branches in a way that - conflicts with CVS's assumptions: - - You can't use .0. branches. (They are reserved for "Magic" branch - tags.) - - If you use branch 1.1.1, you can't use the Vendor branch. - - You can use other RCS branches under CVS. There is no need to create - "magic" branch tags because the physical branch already exists. - - Last modified: _6/13/1997_ - - 13. Can I use raw RCS commands on the Repository? - - You can use raw rcs commands directly on the Repository if you take a - little care. The Repository itself contains no "CVS state" (as opposed - to RCS revision histories) outside the CVSROOT directory. - - But using raw RCS commands to change branches, tags or other things - that CVS depends on may render the files unusable. - - See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the - "admin" command. - - Last modified: _6/13/1997_ - - 14. How do I convert from SCCS to RCS? - - You'll have to execute something like "sccs2rcs" (in the CVS contrib - directory) on every file. Then you can move the resulting RCS files - into the Repository as described above. - - Last modified: _6/13/1997_ - - 15. How do I limit access to the Repository? - - There are all sorts of ways to restrict access to Repository files, - none of which are hooked directly into CVS. - - Techniques for limiting access include: - - Training, management and good backups. - - The best form of Repository control is a combination of: - - - A reliable backup scheme (verify it!) - - Enough training to ensure your developers are competent and - knowledgeable about all areas of your sources. - - Effective management of the boundaries and grey areas. - - In many cases, technical solutions to "security" problems are - inadequate. You should first try to avoid them. - - Personal Opinion: In an environment where "unknowns" are allowed to - touch important sources the "owner" of the CVS Repository must be a - large, loud, vigorous lout with a well-balanced truncheon and the - right to use it. Don't underestimate the effectiveness of letting - everyone know they will be strapped into the stocks on the Town Common - and pelted with vegetables if they break something they don't - understand without first asking the experts. - - Set Unix groups and permissions. See 4B.5. You can set different - owners, groups and permissions for each sub-directory within the - Repository if that helps. - - Catch invocations of "commit" by defining pre-commit programs in the - "commitinfo" file. This is fairly powerful, since it can block commits - based on anything you can program. Take a look at the programs in the - "contrib" directory of the CVS source tree. - - Use multiple Repositories, each with its own protection scheme. If - you use NFS (or AFS) you can even use "export" restrictions to various - groups of machines to keep (for example) the Engineering Repository - off the Customer Service machines. - - Try the "setgid" trick described in 4D.13. - - Try to use the RCS access control lists, though I don't think CVS - will handle them cleanly. - - Edit the source code to CVS to add your own access control. - - Last modified: _6/13/1997_ - - 16. What are the Repository Administrator's responsibilities? - - Generally, the Administrator should set "policy", create the - Repository and monitor its size and control files. - - Some specific responsibilities include: - - Examining the Repository once in a while to clean up: - - Trash files left by misguided developers who mistake the Repository - for a working directory. - - Non-RCS files. Other than the files CVS needs in the - $CVSROOT/CVSROOT directory, every file in the Repository should be an - RCS file. - - Lock files (both CVS '#*' and RCS ',*' files) left around after - crashes. - - Wrong permissions, groups and ownerships. - - Locked files. (RCS locks, that is.) - - Attic files that should never have been under CVS at all. Don't - blindly delete files from Attic directories -- they were mostly put - there (via the "cvs remove") for a reason. Files that should be - deleted are binary files (e.g. '*.o', 'core', executables) that were - mistakenly inserted by "import -I !". - - Maintaining the modules file. - - Storing site-specific ignore patterns in the - $CVSROOT/CVSROOT/cvsignore file. - - Storing the names of non-standard CVSROOT files (See 4B.2) in the - $CVSROOT/CVSROOT/checkoutlist - - Maintaining the other Repository control files: commitinfo, loginfo, - rcsinfo and editinfo. - - Pruning the history file every once in a while. (Try the - "cln_hist.pl" script in the "contrib" directory.) - - Staying aware of developments on the info-cvs mailing list and what - is available in the FTP and WWW archives. - - Running "ps ax" once in a while and kill off any "update" programs - not running as "root". It is too easy to leave the "cvs" off the front - of the "cvs update" command. - - Executing monitor programs to check the internal consistency of the - Repository files. Ideas: - - Files that have a default RCS branch that is not 1.1.1 (From an - abuse of "admin -b".) - - Files that have only Revisions 1.1 and 1.1.1.1, with a default - branch of "MAIN". (From an abuse of "admin -o".) - - Existing branch tags and various branch consistency checks. - - Last modified: _6/13/1997_ - - 17. How do I move the whole Repository? - - Copy or move the tree. (On Unix systems, a set of piped "tar" commands - works great. If the Repository does not contain any symlinks, which it - normally doesn't, you can also use "cp -r".) - - If you can avoid changing $CVSROOT (i.e. the "logical" pathname of the - Repository) by replacing the old location with a symbolic link to the - new location, you don't have to do anything else. - - (You could also mount the new location on top of the old location if - you are using NFS or some other filesystem that allows it.) - - If you must change $CVSROOT, you must also tell everyone to change the - CVSROOT environment variable in all running shells and in any personal - configuration files ('.' files on Unix) where it is set. - - The Repository itself contains no references to its own name, except - possibly in some of the files in the CVSROOT directory. If your - modules (or loginfo, commitinfo, etc.) file mentions helper programs - directly in the Repository, you'll have to change the pathnames to - point to the new Repository location. - - The main changes you'll have to make are to all the CVS administrative - files (./CVS/Repository and ./CVS/Root) in every working directory - ever checked out from the previous location of the Repository you just - moved. - - You have three choices: - - If all ./CVS/Repository files in all working directories contain - relative pathnames, you don't have to do anything else. - - Have everyone "release" or delete their working directories (after - committing, or just saving, their work) and check them all out again - from the new Repository after the move. - - Use "find . ( -name Repository -o -name Root )" and a PERL or shell - script to run through all the ./CVS/Repository and ./CVS/Root files - and edit the values in the files. - - Last modified: _6/13/1997_ - - 18. How do I change permissions on a file in the Repository by using a CVS - command? (i.e. without using "chmod 777 $CVSROOT/dir/file") - - When you first "import" or "add"/"commit" a file, the read and execute - bits on the Repository file are inherited from the original source - file, while the write bits on the Repository file are are turned off. - This is a standard RCS action. - - After that, there is no way to alter the permissions on a file in the - Repository using CVS (or RCS) commands. You have to change the - permissions on both your working file and on the Repository file from - which it was retrieved. - - Whenever you "checkout" the file or retrieve a new revision via - "update" (or after a "commit"), your working file is set to match the - permissions of the Repository file, minus any "umask" bits you have - set. - - Last modified: _6/13/1997_ - - Category: /Advanced_Topics_/Tricks_of_the_Trade/ - - " + Tricks of the Trade" - - 1. How can you even check in binary files, let alone allow CVS to do its - auto-merge trick on them? - - -First of all, if you want to use binary files, you should get RCS 5.7 -and CVS 1.9 or later (earlier versions had some support, but there have been -bug fixes). Secondly, follow the instructions for installing RCS very -carefully (it is easy to get it installed so it works for everything -except binary files). - -Then, specify 'cvs add -kb' instead of just 'cvs add' to add a binary -file. If you want to set an existing file to binary, run 'cvs admin --kb' (and then check in a new copy of the file). Note that old -versions of CVS used -ko instead of -kb for binary files, so if you -see a reference to -ko in the context of binary files, you should -think -kb instead. - -Of course when 'cvs update' finds that a merge is needed, it can't -do this for binary files the same way as for text files. With the -latest versions (e.g. CVS 1.9.14), it should be able to give you both -versions and let you merge manually. Another approach is to -run 'cvs admin -l' to lock files, as described in -"How can I lock files while I'm working on them the way RCS does?" -elsewhere in this FAQ. See also -"Is there any way to import binary files?" and -"How do I "add" a binary file?" elsewhere in this FAQ. - -kingdon@cyclic.com - - Last modified: _9/6/1997_ - - 2. Can I edit the RCS (",v") files in the Repository? - - Yes, but be very careful. The RCS files are not free-form files, they - have a structure that is easily broken by hand-editing. The only time - I would suggest doing this is to recover from emergency failures that - are difficult to deal with using CVS commands, including the "admin" - command, which can talk directly to RCS. - - Though no one actively encourages the editing of RCS files, many - people have succumbed to the urge to do so when pressed for time. The - reasons given, usually with evident contrition, include: - - - Editing mistakes in, or adding text to, log entries. (If you have - RCS 5.6 or later, you should use `cvs admin -m'.) - - Renaming or moving symbolic names. (You should `cvs admin -N' - instead.) - - Unlocking a file by changing the "locker" from someone else to - yourself. (It's safer to use `cvs admin -u -l'.) - - Making global changes to past history. Example: Eradicating former - employees names from old documents and Author entries. (And someone - thought the "history" command was evidence of Big Brother! I never - realized how much help a wide-open revision control system could have - provided to The Ministry of Truth.) - - Last modified: _6/13/1997_ - - 3. Can I edit the ./CVS/{Entries,Repository,Tag} files? - - Yes, but with CVS 1.3 and later, there is almost no reason to edit any - of the CVS administrative files. - - If you move pieces of your Repository around it can be faster to edit - all the ./CVS/Repository files rather than checking out a large tree. - But that is nearly the only reason to do so. - - Last modified: _6/13/1997_ - - 4. Someone executed "admin -o" and removed revisions to which tags/symbols - were attached. How do I fix them? - - It depends on what you mean by "fix". I can think of three ways to fix - your predicament: - - Remove the tags. - - Assuming you really wanted to get rid of the revision and its - associated tags, you can remove them with the "admin" command. The - "tag -d" command will only remove tags attached to existing revisions. - You can remove a tag, even if it is attached to a non-existent - revision, by typing: - - cvs admin -N<tag> <file> - - Retrieve the outdated revision. - - You should first look in your backup system for recent versions of the - file. If you can't use them, you can carefully extract each revision - that followed the earliest outdated revision using RCS (or "cvs - admin") commands and reconstruct the file with all the right - revisions, branches and tags. This is a lot of work. - - You *can't* insert a revision into the current RCS file. - - Move the Tags to another revision in each file. - - If you want to move the tags to another valid revision, you have two - choices, both of which require that you find all the revision numbers - of the files you want to "tag" and execute the following command - sequences on each <file>. - - Use "update" to grab the revision you want, then execute a normal - "tag" command to Tag that revision: - - cvs update -r <rev> <file> - cvs tag <tag> <file> - - Use "admin" to set the tag to a specific revision: - - cvs admin -N<tag>:<rev> <file> - - Last modified: _6/13/1997_ - - 5. How do I move or rename a magic branch tag? - - (To rename a non-branch <tag> see 3O.9.) - - Before reading this, read 3M.3 and 3M.4 and understand exactly how tag - and rtag use '-r' and why it won't do the right job here. - - First, I have to explain exactly what a magic branch tag is. - - A magic <branch_tag> is an artificial tag attached to a non-existent - revision on a non-existent branch number zero. It looks like this: - - TAG1:<X>.0.Y - - <X> is the "branch point revision", a normal revision with an - odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc) - - Y is an even number (e.g. 2, 4, 6, etc.) All CVS branches, - other than the Vendor branch, are even numbered. - - TAG1 is considered by CVS to be attached to revision <X>. The first - "update -r TAG1 <file>" after applying TAG1 will produce a copy of - revision <X> with a sticky tag of TAG1. The first "commit" to that - file will cause CVS to construct an RCS branch named <X>.Y and check - in revision <X>.Y.1 on the new branch. - - Note: TAG1 is *not* considered to be attached to <X> by RCS, which - explains why you can't refer directly to the branch point revision for - some CVS commands. - - Moving a magic <branch_tag> is the act of reapplying the same tag to - different revisions in the file: - - TAG1:<X>.0.Y - to - TAG1:<X>.0.Z or TAG1:<A>.0.B - - You can move a magic branch tag to the revisions of your choice by - using "update" to find the revisions you want to tag and reapplying - the tag to all the files with the '-F' option to force it to move the - existing <branch_tag>. - - cvs update -r <tag/rev> (or '-A' for the Main Branch) - cvs tag -F -b <branch_tag> - - If the earlier location of TAG1 refers to a physical branch within any - RCS file, moving it will make the existing branch in the file seem to - disappear from CVS's view. This is not a good idea unless you really - want to forget the existence of those RCS branches. - - If the "update" above retrieves the original branch point revision - (<X>), the "tag" command above will create the tag: - - TAG1:<X>.0.Z - - Where Z is 2 greater than the highest magic branch already on revision - <X>. The TAG1 branch will still have the same branch point (i.e. - revision <X>), but the first commit to the new TAG1 branch will create - a different RCS branch number (<X>.Z instead of <X>.Y). - - Renaming a magic <branch_tag> is the act of changing - - TAG1:<X>.0.Y - to - TAG2:<X>.0.Y - - There is no harm in changing a tag name as long as you forget that - TAG1 ever existed and you clean up any working directories with sticky - TAG1 tags on them by using "update -A", "update -r <other_tag>" or by - removing the working directories. - - On the other hand, actually changing the tag is not easy. - - See 3M.3 for why the seemingly obvious solution won't work: - - cvs tag -b -r <old_branch_tag> <new_branch_tag> - - The only direct way to rename a magic tag is to use the "admin" - command on each file: (You might want to use '-n'. Read "man rcs" and - look at the '-n' and '-N' options.) - - cvs admin -N<new_branch_tag>:<old_branch_tag> . - cvs tag -d <old_branch_tag> - - But you have to be careful because "admin" is different from other CVS - commands: - - "admin" can be used recursively, but only by specifying directory - names in its argument list (e.g. '.'), - - Where "rtag -r <old_branch_tag>" would interpret <old_branch_tag> as - a magic CVS branch tag, "admin" is a direct interface to RCS which - sees a magic branch tag as a simple (though non-existent) RCS revision - number. - - This is good for us in this particular case, but different from normal - CVS. - - "admin" also skips the Attic and produces different kinds of errors - than CVS usually does. (Because they are coming directly from RCS.) - - The other way to rename a magic <branch_tag> is to edit the Repository - files with a script of some kind. I've done it in the past, but I'll - leave it as an exercise for the reader. - - Last modified: _6/13/1997_ - - 6. Can I use RCS locally to record my changes without making them globally - visible by committing them? - - You can, but it will probably confuse CVS to have ",v" files in your - working directory. And you will lose all your log entries when you - finally commit it. - - Your best bet is to create your own CVS branch and work there. You can - commit as many revisions as you want, then merge it back into the main - line (or parent branch) when you are finished. - - Last modified: _6/13/1997_ - - 7. How can I allow access to the Repository by both CVS and RCS? - - The first step is to try not to. If some people are using CVS, there - is no reason for everyone not to. It is not hard to learn the basics - and CVS makes certain operations *easier* than a series of RCS - commands. Personal preference in what software tools can be applied to - a shared Repository has to take second place to system integration - needs. If you disagree, try writing some Lisp code for inclusion in - your Unix kernel and see what kind of reception you get. - - If you really must allow routine RCS access to the CVS Repository, you - can link an RCS sub-directory into a piece of the Repository: - - ln -s /Repository/some/directory/I/want RCS - - and RCS will work just fine. - - Those who are using RCS will have to keep the following in mind: - - If a file was originally added to the Repository by "import" and has - not been changed using CVS, the *RCS* default branch will remain - attached to the Vendor branch, causing revisions checked-in by "ci" to - wind up on the Vendor branch, instead of the main branch. Only CVS - moves the RCS default branch on first commit. - - The way around this is to checkin (using "ci") all the files first and - move them into the Repository. That way they won't have Vendor - branches. Then RCS will work OK. - - It is possible to use "rcs" and "ci" to make the files unusable by - CVS. The same is true of the CVS "admin" command. - - Normal RCS practice locks a file on checkout with "co -l". In such - an environment, RCS users should plan to keep survival gear and food - for at least 30 days near their desks. When faced with bizarre and - unexpected permission errors, howling mobs of slavering CVS users will - run the RCS users out of town with pitchforks and machetes. - - See 3C.8 for a way to avoid machetes aroused by lock collisions. - - Though files checked in by RCS users will correctly cause - "up-to-date" failures during CVS "commits" and they will be - auto-merged into CVS working directories during "update", the opposite - won't happen. - - RCS users will get no warning and will not be required to merge older - work into their code. They can easily checkin an old file on top of a - new revision added by CVS, discarding work committed earlier by CVS - users. - - See the howling mob scenario described above. - - RCS is great. I have used it for years. But I wouldn't mix it this - way. In a two-camp society, you are asking for real trouble, both in - technical hassles to clean up and in political hassles to soothe. - Branch merges will also be a major problem. - - Last modified: _6/13/1997_ - - 8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't - the file now have a modified date of yesterday? - - CVS restores dates from the RCS files only on first "checkout". After - that, it is more important to maintain a timestamp relative to the - other files in the working directory. - - Example: You committed a source file at 5PM. Bubba updated his copy of - the file, grabbing your changes, then changed and committed a new - revision of the file at 6PM. At 7PM, you compile your file. Then you - execute "update". If CVS sets the date to the one in the RCS file, the - file would be given a timestamp of 6PM and your Makefile wouldn't - rebuild anything that depended on it. Bad news. - - Note that the same logic applies to retrieving a revision out of the - Repository to replace a deleted file. If CVS changes your file in an - existing working directory, whether it was because a new revision was - committed by someone else or because you deleted your working file, - the timestamp on the retrieved working file *must* be set to the - current time. - - When you first retrieve a file, there is no reason to expect any - particular timestamp on the file within your working area. But later, - when dependency checking is performed during a build, it is more - important for the timestamps on the local files to be consistent with - each other than than it is for working files to match the timestamps - on the files in the Repository. See 4D.17 for some more about - timestamps. - - Last modified: _6/13/1997_ - - 9. Why do timestamps sometimes get set to the date of the revision, - sometimes not? The inconsistency causes unnecessary recompiles. - - The "checkout" command normally sets the timestamp of a working file - to match the timestamp stored on the revision in the Repository's RCS - file. - - The "commit" command retains the timestamp of the file, if the act of - checking it in didn't change it (by expanding keywords). - - The "update" command sets the time to the revision time the first time - it sees the file. After that, it sets the time of the file to the - current time. See 4D.8 for a reason why. - - Here's a two-line PERL program to set timestamps on files based on - other timestamps. I've found this program useful. When you are certain - you don't want a source file to be recompiled, you can set its - timestamp to the stamp on the object file. - - #!/usr/local/bin/perl - # - # Set timestamp of args 2nd-Last to that of the first arg. - # - ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime) - = stat(shift); - utime($atime,$mtime,@ARGV); - - Last modified: _6/13/1997_ - - 10. While in the middle of a large "commit", how do I run other commands, - like "diff" or "stat" without seeing lock errors? - - Type: - cvs -n <command> - - The '-n' option to the main cvs command turns off lock checking, a - reasonable act for read-only commands given the promise offered by - '-n' not to alter anything. The "diff", "log" and "stat" commands - provide the same information (for files that are not being committed) - when used with and without the '-n' option. - - Warning: Ignoring locks can produce inconsistent information across a - collection of files if you are looking at the revisions affected by an - active commit. Be careful when creating "patches" from the output of - "cvs -n diff". If you are looking only at your working files, tagged - revisions, and BASE revisions (revisions whose numbers are read from - your ./CVS/Entries files), you should get consistent results. Of - course, if you catch a single file in the middle of RCS activity, you - might get some strange errors. - - Note that the suggested command is "cvs -n <command>". The visually - similar command "cvs <command> -n" has no relation to the suggested - usage and has an entirely different meaning for each command. - - "cvs -n update" also works in the middle of a commit, providing - slightly different information from a plain "cvs update". But, of - course, it also avoids modifying anything. - - You could also use the RCS functions, "rlog" and "rcsdiff" to display - some of the information by referring directly to the Repository files. - - You need RCS version 5 or later for the commands described above to - work reliably. - - Last modified: _6/13/1997_ - - 11. Where did the ./CVS/Entries.Static file come from? What is it for? - - Each CVS working directory contains a ./CVS/Entries file listing the - files managed by CVS in that working directory. Normally, if the - "update" command finds a file in the Repository that is not in the - ./CVS/Entries file, "update" copies the appropriate revision of the - "new" file out of the Repository and adds the filename to the Entries - file. This happens for files: - - Added to the Repository from another working directory. - - Dragged out of the Attic when switching branches with "update -A" or - "update -r". - - Whose names were deleted from the ./CVS/Entries file. - - If the ./CVS/Entries.Static file exists, CVS will only bring out - revisions of files that are contained in either ./CVS/Entries or - ./CVS/Entries.Static. If a Repository file is found in *neither* file, - it is ignored. - - The ./CVS/Entries.Static file is created when you check out an - individual file or a module that creates working directories that - don't contain all files in the corresponding Repository directory. In - those cases, without an ./CVS/Entries.Static file, a simple "update" - would bring more files out of the Repository than the original - "checkout" wanted. - - The ./CVS/Entries.Static file can be removed by hand. It is - automatically removed if you run "update -d" to create new directories - (even if no new directories are created). (Internally, since - "checkout" turns on the '-d' flag and calls the "update" routine, a - "checkout" of a module or directory that writes into an existing - directory will also remove the ./CVS/Entries.Static file.) - - Last modified: _6/13/1997_ - - 12. Why did I get the wrong Repository in the loginfo message? - - You probably: - - Use multiple Repositories. - - Configured CVS to use absolute pathnames in the ./CVS/Repository - file. - - Configured CVS not to use the ./CVS/Root file. - - Typed the "commit" command in one Repository with your $CVSROOT - pointing at another. - - "commit" and all other CVS commands will heed an absolute pathname in - the ./CVS/Repository file (or in the "-d CVSrootdir" override), but - the log function doesn't take arguments -- it just looks at $CVSROOT. - - If you avoid even one of the four steps above, you won't see this - problem. If you configure ./CVS/Root, you won't be allowed to execute - the program causing the error. - - Last modified: _6/13/1997_ - - 13. How do I run CVS setuid so I can only allow access through the CVS - program itself? - - Setuid to root is not a great idea. Any program that modifies files - and is used by a widely distributed group of users is not a good - candidate for a setuid program. (The worst suggestion I've ever heard - was to make *Emacs* setuid to root.) - - Root access on Unix is too powerful. Also, it might not work in some - (secure?) environments. - - Running it setuid to some user other than root might work, if you add - this line to main.c near the beginning: - - setuid(geteuid()); - - Otherwise it uses *your* access rights, rather than the effective - uid's. - - Also, you have to invent a fake user whose name will show up in - various places. But many sites, especially those who might want a - setuid CVS for "security", want personal accountability -- no generic - accounts. I don't know whether accountability outweighs file security. - - And finally, unless you take action to limit the "admin" command, you - are leaving yourself unprotected anyway. - - Last modified: _6/13/1997_ - - 14. How about using groups and setgid() then? - - Here is a way to run CVS setgid in some environments: - - Stick this near the front of the main() in main.c: - - setgid(getegid()); - - This will allow "access" to work on systems where it only works on the - real gid. - - Create a group named "cvsg". (This example uses "cvsg". You can name - it as you wish.) - - Put *no* users in the "cvsg" group. You can put Repository - administrators in this group if you want to. - - Set the cvs executable to setgid (not setuid): - - cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs - - Make sure every file in the Repository is in group "cvsg": - - chown -R root.cvsg $CVSROOT - - Change all directory permissions to 770. This allows all access to - the files by the "cvsg" group (which has no members!) and no access at - all to anyone else. - - find $CVSROOT -type d -exec chmod 2770 {} \; - - On some systems you might have to type: - - find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \; - - This should allow only the cvs program (or other "setgid to group - cvsg") programs to write into the area, but no one else. Yes the user - winds up owning the file, but s/he can't find it again later since - s/he can't traverse the tree. (If you enable the world execute bit - (mode 2771) on directories, users can traverse the tree and the user - who last wrote the file can still write to it.) - - If you want to allow read access, check out an entire tree somewhere. - You have to do this anyway to build it. - - Note: If you are using a stupid file system that can't inherit file - groups from the parent directory (even with the "setgid" (Octal 2000) - bit set), you might have to modify CVS (or RCS) to reset the group - every time you create a new file. I have not tested this. - - The setgid() method shares with the setuid() method the problem of - keeping "admin" from breaking things. - - Last modified: _6/13/1997_ - - 15. How do I use the "commitinfo" file? - - Go read 4B.2 first. - - The "commitinfo" file allows you to execute "sanity check" functions - before allowing a commit. If any function called from within the - commitinfo file exits with a non-zero status, the commit is denied. - - To fill out a "commitinfo" file, ask yourself (and those sharing your - Repository) these questions: - - - Is there anything you want to check or change before someone is - allowed to commit a file? If not, forget commitinfo. - - If you want to serialize binary files, you might consider something - like the rcslock.pl program in the contrib directory of the CVS - sources. - - - Do you want to execute the same exact thing before committing to - every file in the Repository? (This is useful if you want to program - the restrictions yourself.) If so, set up a single line in the - commitinfo: - - DEFAULT /absolute/path/to/program - - CVS executes the program once for each directory that "commit" - traverses, passing as arguments the directory and the files to be - committed within that directory. - - Write your program accordingly. Some examples exist in the contrib - directory. - - - Do you want a different kind of sanity check performed for different - directories? If so, you'll have to decide what to do for all - directories and enter lines like this: - - regexp1 /absolute/path/to/program-for-regexp1 - regexp2 /absolute/path/to/program-for-regexp2 - DEFAULT /absolute/path/to/program-for-all-else - - - Is there anything you want to happen before *all* commits, in - addition to other pattern matches? If so, include a line like this: - - ALL /absolute/path/to/program - - It is executed independently of all the above. And it's repeatable -- - you can have as many ALL lines as you like. - - Last modified: _6/13/1997_ - - 16. How do I use the "loginfo" files? - - See 4B.2 and the "commitinfo" question above. - - The "loginfo" file has the same format as the "commitinfo" file, but - its function is different. Where the "commitinfo" information is used - before a commit, the "loginfo" file is used after a commit. - - All the commands in the "loginfo" file should read data from standard - input, then either append it to a file or send a message to a mailing - list. If you want to make it simple, you can put shell (the shell used - by "popen(3)") command lines directly in the "loginfo" (or - "commitinfo") file. These seem to work: - - ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail - -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) > - /path/name/to/log/file - - Last modified: _6/13/1997_ - - 17. How can I keep people with restrictive umask values from blocking - access to the Repository? - - If a user creates a new file with restricted permissions (e.g. 0600), - and commits it, the Repository will have a file in it that is - unreadable by everyone. The 0600 example would be unreadable by - *anyone* but root and the user who created it. - - There are 3 solutions to this: - - Let it happen. This is a valid way to protect things. If everyone is - working alone, a umask of 077 is OK. If everyone is working only in - small groups, a umask of 007 is OK. - - Train your users not to create such things if you expect to share - them. - - See 4B.5 for a small script that will reset the umask. - - I personally don't like the idea of a program automatically - *loosening* security. It would be better for you all to talk about the - issue and decide how to work together. - - Last modified: _6/13/1997_ - - Category: /Commands_/ - - " Commands " - - Category: /Commands_/add_ad_new/ - - " + "add", "ad", "new"" - - 1. What is "add" for? - - To add a new directory to the Repository or to register the desire to - add a new file to the Repository. - - The directory is created immediately, while the desire to add the file - is recorded in the local ./CVS administrative directory. To really add - the file to the Repository, you must then "commit" it. - - Last modified: _6/13/1997_ - - 2. How do I add a new file to the branch I'm working on? - - The user actions for adding a file to any branch, including the Main - Branch, are exactly the same. - - You are in a directory checked out (or updated) with the '-A' option - (to place you on the Main Branch) or the "-r <branch_tag>" option (to - place you on a branch tagged with <branch_tag>). To add <file> to the - branch you are on, you type: - - cvs add <file> - cvs commit <file> - - If no ./CVS/Tag file exists (the '-A' option deletes it), the file - will be added to the Main Branch. If a ./CVS/Tag file exists (the "-r - <branch_tag>" option creates it), the file will be added to the branch - named (i.e. tagged with) <branch_tag>. - - Unless you took steps to first add the file to the Main Branch, your - new file ends up in the Attic. - - Last modified: _6/13/1997_ - - 3. Why did my new file end up in the Attic? - - The file is thrown into the Attic to keep it from being visible when - you check out the Main Branch, since it was never committed to the - Main Branch. - - Last modified: _6/13/1997_ - - 4. Now that it's in the Attic, how do I connect it to the Main branch? - - That can be considered a kind of "merge". See 4C.8 - - Last modified: _6/13/1997_ - - 5. How do I avoid the hassle of reconnecting an Attic-only file to the Main - Branch? - - You create it on the Main Branch first, then branch it. - - If you haven't yet added the file or if you decided to delete the new - Attic file and start over, then do the following: (If you added the - file (or worse, the 157 files) to the Attic and don't want to start - over, try the procedure in 4C.8.) - - Temporarily remove the sticky branch information. Either: - - Move the whole directory back to the Main Branch. [This might not be - a good idea if you have modified files, since it will require a merge - in each direction.] - - cvs update -A - - *or* - - Move the ./CVS/Tag file out of the way. - - mv ./CVS/Tag HOLD_Tag - - Add and branch the file "normally": - - cvs add <file> - cvs commit <file> - cvs tag -b <branch_tag> <file> - - [<branch_tag> is the same Branch Tag as you used on all the other - files. Look at ./CVS/Entries or the output from "cvs stat" for sticky - tags.] - - Clean up the temporary step. - - If you moved the ./CVS/Tag file, put it back. Then move the new file - onto the branch where you are working. - - mv HOLD_Tag ./CVS/Tag - cvs update -r <branch_tag> <file> - - If you ran "update -A" rather than moving the ./CVS/Tag file, move - the whole directory (including the new file) back onto the branch - where you were working: - - cvs update -r <branch_tag> - - Last modified: _6/13/1997_ - - 6. How do I cancel an "add"? - - If you want to remove the file entirely and cancel the "add" at the - same time, type: - - cvs remove -f <file> - - If you want to cancel the "add", but leave the file as it was before - you typed "cvs add", then you have to fake it: - - mv <file> <file>.hold - cvs remove <file> - mv <file>.hold <file> - - Last modified: _6/13/1997_ - - 7. What are the ./CVS/file,p and ./CVS/file,t files for? - - The ./CVS/file,p and ./CVS/file,t files are created by the "add" - command to hold command line options and message text between the time - of the "add" command and the expected "commit". - - The ./CVS/file,p file is always null, since its function was absorbed - by the "options" field in the ./CVS/Entries file. If you put something - in this file it will be used as arguments to the RCS "ci" command that - commit uses to check the file in, but CVS itself doesn't put anything - there. - - The ./CVS/file,t file is null unless you specify an initial message in - an "add -m 'message'" command. The text is handed to "rcs -i - -t./CVS/file,t" to create the initial RCS file container. - - Both files must exist to commit a newly added file. If the - ./CVS/file,p file doesn't exist, CVS prints an error and aborts the - commit. If the ./CVS/file,t file doesn't exist, RCS prints an error - and CVS gets confused, but does no harm. - - To recover from missing ,p and ,t files, just create two zero-length - files and rerun the "commit". - - Last modified: _6/13/1997_ - - 8. How do I "add" a binary file? - - If you configured CVS to use the GNU version of "diff" and "diff3", - you only need to turn off RCS keyword expansion. - - First you turn off RCS keyword expansion for the initial checkin by - using "add -ko". It works like "update -ko" in creating a "sticky" - option only for the copy of the file in the current working directory. - - cvs add -ko <file> - - Commit the file normally. The sticky -ko option will be used. - - cvs commit <file> - - Then mark the RCS file in the Repository so that keyword expansion is - turned off for all checked out versions of the file. - - cvs admin -ko <file> - - Since "admin -ko" records the keyword substitution value in the - Repository's RCS file, you no longer need the sticky option. You can - turn it off with the "update -A" command, but if you were on a branch, - you'll have to follow it "update -r <branch_tag>" to put yourself back - on the branch. - - Managing that binary file is another problem. See 4D.1. - - Last modified: _6/13/1997_ - - Category: /Commands_/admin_adm_rcs/ - - " + "admin", "adm", "rcs"" - - 1. What is "admin" for? - - To provide direct access to the underlying "rcs" command (which is not - documented in this FAQ) bypassing all safeguards and CVS assumptions. - - Last modified: _6/13/1997_ - - 2. Wow! Isn't that dangerous? - - Yes. - - Though you can't hurt the internal structure of an RCS file using its - own "rcs" command, you *can* change the underlying RCS files using - "admin" in ways that CVS can't handle. - - If you feel the need to use "admin", create some test files with the - RCS "ci" command and experiment on them with "rcs" before blasting any - CVS files. - - Last modified: _6/13/1997_ - - 3. What would I normally use "admin" for? - - Normally, you wouldn't use admin at all. In unusual circumstances, - experts can use it to set up or restore the internal RCS state that - CVS requires. - - You can use "admin -o" (for "outdate") to remove revisions you don't - care about. This has its own problems, such as leaving dangling Tags - and confusing the "update" command. - - There is some feeling among manipulators of binary files that "admin - -l" should be used to serialize access. See 3C.8. - - An interesting use for "admin" came up while maintaining CVS itself. I - import versions of CVS onto the Vendor branch of my copy of CVS, make - changes to some files and ship the diffs (created by "cvs diff -c -r - TO_BRIAN") off to Brian Berliner. After creating the diff, I retag - ("cvs tag -F TO_BRIAN") the working directory, which is then ready to - produce the next patch. - - I'll use "add.c" as an example (only because the name is short). - - When the next release came out, I discovered that the released "add.c" - (version 1.1.1.3 on the Vendor branch) was exactly the same as my - modified file (version 1.3). I didn't care about the changelog on - versions 1.2 and 1.3 (or the evidence of having done the work), so I - decided to revert the file to the state where it looked like I had not - touched the file -- where I was just using the latest on the vendor - branch after a sequence of imports. - - To do that, I removed all the revisions on the main branch, except for - the original 1.1 from which the Vendor branch sprouts: - - cvs admin -o1.2: add.c - - Then I set the RCS "default branch" back to the Vendor branch, the way - import would have created it: - - cvs admin -b1.1.1 add.c - - And I moved the "TO_BRIAN" Tag to the latest revision on the Vendor - branch, since that is the base from which further patches would be - created (if I made any): - - cvs admin -NTO_BRIAN:1.1.1.3 add.c - - Instead of 1.1.1.3, I could have used one of the "Release Tags" last - applied by "import" (3rd through Nth arguments). - - Suggestion: Practice on non-essential files. - - Last modified: _6/13/1997_ - - 4. What should I avoid when using "admin"? - - If you know exactly what you are doing, hack away. But under normal - circumstances: - - Never use "admin" to alter branches (using the '-b' option), which CVS - takes very seriously. If you change the default branch, CVS will not - work as expected. If you create new branches without using the "tag - -b" command, you may not be able to treat them as CVS branches. - - See 3C.8 for a short discussion of how to use "admin -l" for - serializing access to binary files. - - The "admin -o <file>" allows you to delete revisions, usually a bad - idea. You should commit a correction rather than back out a revision. - Outdating a revision is prone to all sorts of problems: - - Discarding data is always a bad idea. Unless something in the - revision you just committed is a threat to your job or your life, - (like naming a function "<boss's name>_is_a_dweeb", or including the - combination to the local Mafioso's safe in a C comment), just leave it - there. No one cares about simple mistakes -- just commit a corrected - revision. - - The time travel paradoxes you can cause by changing history are not - worth the trouble. Even if CVS can't interfere with your parents' - introduction, it *can* log commits in at least two ways (history and - loginfo). The reports now lie -- the revision referred to in the logs - no longer exists. - - If you used "import" to place <file> into CVS, outdating all the - revisions on the Main branch back to and including revision 1.2 (or - worse, 1.1), will produce an invalid CVS file. - - If the <file>,v file only contains revision 1.1 (and the connected - branch revision 1.1.1.1), then the default branch must be set to the - Vendor branch as it was when you first imported the file. Outdating - back through 1.2 doesn't restore the branch setting. Despite the above - admonition against it, "admin -b" is the only way to recover: - - cvs admin -b1.1.1 <file> - - Although you can't outdate a physical (RCS) branch point without - removing the whole branch, you *can* outdate a revision referred to by - a magic branch tag. If you do so, you will invalidate the branch. - - If you "outdate" a tagged revision, you will invalidate all uses of - the <tag>, not just the one on <file>. A tag is supposed to be - attached to a consistent set of files, usually a set built as a unit. - By discarding one of the files in the set, you have destroyed the - utility of the <tag>. And it leaves a dangling tag, which points to - nothing. - - And even worse, if you commit a revision already tagged, you will - alter what the <tag> pointed to without using the "tag" command. For - example, if revision 1.3 has <tag> attached to it and you "outdate" - the 1.3 revision, <tag> will point to a nonexistent revision. Although - this is annoying, it is nowhere near as much trouble as the problem - that will occur when you commit to this file again, recreating - revision 1.3. The old tag will point to the new revision, a file that - was not in existence when the <tag> was applied. And the discrepancy - is nearly undetectable. - - If you don't understand the above, you should not use the admin - command at all. - - Last modified: _6/13/1997_ - - 5. How do I restrict the "admin" command? The -i flag in the modules file - can restrict commits. What's the equivalent for "admin"? - - At this writing, to disable the "admin" command, you will have to - change the program source code, recompile and reinstall. - - Last modified: _6/13/1997_ - - 6. I backed out a revision with "admin -o" and committed a replacement. Why - doesn't "update" retrieve the new revision? - - CVS is confused because the revision in the ./CVS/Entries file matches - the latest revision in the Repository *and* the timestamp in the - ./CVS/Entries file matches your working file. CVS believes that your - file is "up-to-date" and doesn't need to be updated. - - You can cause CVS to notice the change by "touch"ing the file. - Unfortunately what CVS will tell you is that you have a "Modified" - file. If you then "commit" the file, you will bypass the normal CVS - check for "up-to-date" and will probably commit the revision that was - originally removed by "admin -o". - - Changing a file without changing the revision number confuses CVS no - matter whether you did it by replacing the revision (using "admin -o" - and "commit" or raw RCS commands) or by applying an editor directly to - a Repository (",v") file. Don't do it unless you are absolutely - certain no one has the latest revision of the file checked out. - - The best solution to this is to institute a program of deterrent - flogging of abusers of "admin -o". - - The "admin" command has other problems." See 3B.4 above. - - Last modified: _6/13/1997_ - - Category: /Commands_/checkout_co_get/ - - " + "checkout", "co", "get"" - - 1. What is "checkout" for? - - To acquire a copy of a module (or set of files) to work on. - - All work on files controlled by CVS starts with a "checkout". - - Last modified: _6/13/1997_ - - 2. What is the "module" that "checkout" takes on the command line? - - It is a name for a directory or a collection of files in the - Repository. It provides a compact name space and the ability to - execute before and after helper functions based on definitions in the - modules file. - - See 1D.11. - - Last modified: _6/13/1997_ - - 3. Isn't a CVS "checkout" just a bunch of RCS checkouts? - - Like much of CVS, a similar RCS concept is used to support a CVS - function. But a CVS checkout is *not* the same as an RCS checkout. - - Differences include: - - CVS does not lock the files. Others may access them at the same - time. - - CVS works best when you provide a name for a collection of files (a - module or a directory) rather than an explicit list of files to work - on. - - CVS remembers what revisions you checked out and what branch you are - on, simplifying later commands. - - Last modified: _6/13/1997_ - - 4. What's the difference between "update" and "checkout"? - - The "checkout" and "update" commands are nearly equivalent in how they - treat individual files. They differ in the following ways: - - The "checkout" command always creates a directory, moves into it, - then becomes equivalent to "update -d". - - The "update" command does not create directories unless you add the - '-d' option. - - "Update" is intended to be executed within a working directory - created by "checkout". It doesn't take a module or directory argument, - but figures out what Repository files to look at by reading the files - in the ./CVS administrative directory. - - The two commands generate completely different types of records in - the "history" file. - - Last modified: _6/13/1997_ - - 5. Why can't I check out a file from within my working directory? - - Though you *can* check out a file, you normally check out a module or - directory. And you normally do it only once at the beginning of a - project. - - After the initial "checkout", you can use the "update" command to - retrieve any file you want within the checked-out directory. There is - no need for further "checkout" commands. - - If you want to retrieve another module or directory to work on, you - must provide two pathnames: where to find it in the Repository and - where to put it on disk. The "modules" file and your current directory - supply two pieces of naming information. While inside a checked-out - working directory, the CVS administrative information provides most of - the rest. - - You should be careful not to confuse CVS with RCS and use "checkout" - in the RCS sense. An RCS "checkout" (which is performed by the RCS - "co" command) is closer to a "cvs update" than to a "cvs checkout". - - Last modified: _6/13/1997_ - - 6. How do I avoid dealing with those long relative pathnames? - - This question has also been phrased: - - How do I avoid all those layers of directories on checkout? or Why do - I have to go to the top of my working directory and checkout some long - pathname to get a file or two? - - This type of question occurs only among groups of people who decide - not to use "modules". The answer is to use "modules". - - When you hand the "checkout" command a relative pathname rather than a - module name, all directories in the path are created, maintaining the - same directory hierarchy as in the Repository. The same kind of - environment results if you specify a "module" that is really an alias - expanding into a list of relative pathnames rather than a list of - module names. - - If you use "module" names, "checkout" creates a single directory by - the name of the module in your current directory. This "module" - directory becomes your working directory. - - The "module" concept combines the ability to "name" a collection of - files with the ability to structure the Repository so that consistent - sets of files are checked out together. It is the responsibility of - the Repository Administrators to set up a modules file that describes - the software within the Repository. - - Last modified: _6/13/1997_ - - 7. Can I move a checked-out directory? Does CVS remember where it was - checked out? - - Yes and Yes. - - The ./CVS/Repository file in each working directory contains a - pathname pointing to the matching directory within the Repository. The - pathname is either absolute or relative to $CVSROOT, depending on how - you configured CVS. - - When you move a checked-out directory, the CVS administrative files - will move along with it. As long as you don't move the Repository - itself, or alter your $CVSROOT variable, the moved directory will - continue to be usable. - - CVS remembers where you checked out the directory in the "history" - file, which can be edited, or even ignored if you don't use the - "working directory" information displayed by the "history" command. - - Last modified: _6/13/1997_ - - 8. How can I lock files while I'm working on them the way RCS does? - - Until the day arrives of the all-powerful merge tool, there are still - files that must be accessed serially. For those instances, here's a - potential solution: - - Install a pre-commit program in the "commitinfo" file to check for - RCS locks. The program "rcslock.pl" performs this function. It can be - found in the contrib directory of the CVS source distribution. - - When you want to make a change to a file you know can't be merged, - first use "cvs admin -l" to lock the file. If you can't acquire the - lock, use the standard "locked out" protocol: go talk to the person - holding the lock. - - Make sure the pre-commit program prints a message and exits with a - non-zero status if someone besides the user running "commit" has the - file locked. This non-zero exist status will cause the "commit" to - fail cleanly. - - Make sure the pre-commit program exits with a zero status if the - file is either unlocked or locked by the user running "commit". The - "cvs commit" command that kicked off the pre-commit program will take - a zero exist status as an OK and checkin the file, which has the - side-effect of unlocking it. - - ===> The following is opinion and context. Don't read it if you are - looking for a quick fix. - - The topic of locking CVS files resurfaces on the network every so - often, producing the same results each time: - - The Big Endians: - - CVS was designed to avoid locks, using a copy-modify-merge model. - Locking is not necessary and you should take the time to learn the CVS - model which many people find workable. So why not get with the program - and learn how to think the CVS way? - - The Little Endians: - - The users determine how a tool is to be used, not the designers. We, - the users, have always used locking, our bosses demand locking, - locking is good, locking is God. I don't want to hear any more - lectures on the CVS model. Make locking work. - - Any organization making active changes to a source base will - eventually face the need to do parallel development. Parallel - development implies merges. (If you plan to keep separate copies of - everything and never merge, good luck. Tell me who you work for so I - can buy stock in your disk suppliers this year and sell your stock - short next year.) - - Merges will never go away. CVS chose to make "merges" stand front and - center as an important, common occurrence in development. It is one - way of looking at things. - - For free-format text, the merge paradigm gives you a considerable - amount of freedom. It does take a bit of management, but any project - should be ready to deal with it. - - On the other hand, there are many files that can't be merged using - text merge techniques. Straight text merge programs like "diff3" are - guaranteed to fail on executables (with relative branch statements), - files with self-referential counts stored in the file (such as TAGS - files), or files with relative motion statements in them (such as - Frame MIF files, many postscript files). They aren't all binary files. - - For these types of files, and many others, there are only two - solutions: - - Complex merge tools that are intimately aware of the contents of the - files to be merged. (ClearCase, and probably others, allow you to - define your own "files types" with associated "merge tools".) - - Serialization of access to the file. The only technical solution to - the problem of serialization is "locking". - - Since you can call a program that offers: - - "Which one do you want? A/B?" - - a "merge tool", more and more merge tools will appear which can be - hooked into a merge-intensive program like CVS. Think of a bitmap - "merge" tool that displays the bitmaps on the screen and offers a - "paint" interface to allow you to cut and paste, overlay, invert or - fuse the two images such that the result is a "merged" file. - - My conclusion is that the need for locking is temporary, awaiting - better technology. For large development groups, locking is not an - alternative to merging for text files. - - Last modified: _6/13/1997_ - - 9. What is "checkout -s"? How is it different from "checkout -c"? - - The '-c' and '-s' options to "checkout" both cause the modules file to - appear on standard output, but formatted differently. - - "checkout -c" lists the modules file alphabetized by the module name. - It also prints all data (including options like '-a' and "-o <prog>") - specified in the modules file. - - "checkout -s" lists the modules file sorted by "status" field, then by - module name. The status field was intended to allow you to mark - modules with strings of your choice to get a quick sorted report based - on the data you chose to put in the status fields. I have used it for - priority ("Showstopper", etc as tied into a bug database), for porting - status ("Ported", "Compiled", etc. when porting a large collection of - modules), for "assignee" (the person responsible for maintenance), and - for "test suite" (which automatic test procedure to run for a - particular module). - - Last modified: _6/13/1997_ - - Category: /Commands_/commit_ci_com/ - - " + "commit", "ci", "com"" - - 1. What is "commit" for? - - To store new revisions in the Repository, making them visible to other - users. - - Last modified: _6/13/1997_ - - 2. If I edit ten files, do I have to type "commit" ten times? - - No. The "commit" command will take multiple filenames, directory names - and relative pathnames on the command line and commit them all with - the same log message. If a file is unchanged, even if it is explicitly - listed on the command line, CVS will skip it. - - Like all CVS commands, "commit" will work on the whole directory by - default. Just type "cvs commit" to tell CVS to commit all modified - files (i.e. the files that "update" would display preceded by 'M') in - the current directory and in all sub-directories. - - Last modified: _6/13/1997_ - - 3. Explain: cvs commit: Up-to-date check failed for `<file>' - - You may not "commit" a file if your BASE revision (i.e. the revision - you last checked out, committed or retrieved via "update") doesn't - match the HEAD revision (i.e the latest revision on your branch, - usually the Main Branch). - - In other words, someone committed a revision since you last executed - "checkout", "update" or "commit". You must now execute "update" to - merge the other person's changes into your working file before - "commit" will work. You are thus protected (somewhat) from a common - form of race condition in source control systems, where a checkin of a - minor alteration of a second copy of the same base file obliterates - the changes made in the first. - - Normally, the "update" command's auto-merge should be followed by - another round of building and testing before the "commit". - - Last modified: _6/13/1997_ - - 4. What happens if two people try to "commit" conflicting changes? - - Conflicts can occur only when two developers check out the same - revision of the same file and make changes. The first developer to - commit the file has no chance of seeing the conflict. Only the second - developer runs into it, usually when faced with the "Up-to-date" error - explained in the previous question. - - There are two types of conflicts: - - When two developers make changes to the same section of code, the - auto-merge caused by "update" will print a 'C' on your terminal and - leave "overlap" markers in the file. - - You are expected to examine and clean them up before committing the - file. (That may be obvious to *some* of you, but . . .) - - A more difficult problem arises when two developers change different - sections of code, but make calls to, or somehow depend on, the old - version of each other's code. - - The auto-merge does the "right" thing, if you view the file as a - series of text lines. But as a program, the two developers have - created a problem for themselves. - - This is no different from making cross-referential changes in - *separate* files. CVS can't help you. In a perfect world, you would - each refer to the specification and resolve it independently. In the - real world you have to talk/argue, read code, test and debug until the - combined changes work again. - - Welcome to the world of parallel development. - - Last modified: _6/13/1997_ - - 5. I committed something and I don't like it. How do I remove it? - - Though you *can* use the "admin -o" (synonym: "rcs -o") command to - delete revisions, unless the file you committed is so embarrassing - that the need to eradicate it overrides the need to be careful, you - should just grab an old version of the file ("update -p -r - <previous-rev>" might help here) and commit it on top of the offending - revision. - - See Section 3B on "admin". - - Last modified: _6/13/1997_ - - 6. Explain: cvs commit: sticky tag `V3' for file `X' is not a branch - - The message implies two things: - - You created your working directory by using "checkout -r V3", or you - recently executed "update -r V3". - - The tag named V3 is not a branch tag. - - CVS records (i.e. makes "sticky") any "-r <tag/rev>" argument handed - to the "checkout" or "update" commands. The <tag/rev> is recorded as - the CVS working branch, which is the branch to which "commit" will add - a new revision. - - Branch tags are created when you use the -b switch on the "tag" or - "rtag" commands. Branch tags are magic tags that don't create a - physical branch, but merely mark the revision to branch from when the - branch is needed. The first commit to a magic branch creates a - physical branch in the RCS files. - - You can commit onto the end of the Main Trunk, if you have no sticky - tag at all, or onto the end of a branch, if you have a sticky branch - tag. But you can't commit a file that has a sticky tag not pointing to - a branch. CVS assumes a sticky Tag or Revision that does not refer to - a branch is attached to the middle of a series of revisions. You can't - squeeze a new revision between two others. Sticky dates also block - commits since they never refer to a branch. - - Scenario1: - - If you don't want a branch and were just looking at an old revision, - then you can move back to the Main Branch by typing: - - cvs update -A {files or dirs, default is '.'} - - or you can move to the branch named <branch_tag> by: - - cvs update -r <branch_tag> {files or dirs, default is '.'} - - Scenario2: - - If you really wanted to be on a branch and made an earlier mistake by - tagging your branch point with a non-branch tag, you can recover by - adding a new branch tag to the old non-branch tag: - - cvs rtag -b -r <oldtag> <newtag> <module> - - (It was not a big mistake. Branch-point tags can be useful. But the - <newtag> must have a different name.) - - If you don't know the <module> name or don't use "modules", you can - also use "tag" this way: - - cvs update -r <oldtag> - cvs tag -b <newtag> . - - Then, to put your working directory onto the branch, you type: - - cvs update -r <newtag> - - You can't delete <oldtag> before adding <newtag>, and I would not - advise deleting the <oldtag> at all, because it is useful in referring - to the branch point. If you must, you can delete the non-branch tag - by: - - cvs rtag -d <oldtag> <module> - or - cvs tag -d <oldtag> . - - Scenario3: - - If you made the same mistake as in Scenario2 (of placing a non-branch - tag where you wanted a branch tag), but really want <oldtag> to be the - name of your branch, you can execute a slightly different series of - commands to rename it and move your working directory onto the branch. - - Warning: This is not a way to rename a branch tag. It is a way to turn - a non-branch tag into a branch tag with the same name. - - cvs rtag -r <oldtag> <branch_point_tag> <module> - cvs rtag -d <oldtag> <module> - cvs rtag -b -r <branch_point_tag> <oldtag> <module> - - Then, if you really must, delete the <branch_point_tag>: - - cvs rtag -d <branch_point_tag> <module> - - Note: The unwieldy mixture of "tag" and "rtag" is mostly because you - can't specify a revision (-r <tag>) to the "tag" command. - - See 4C.3 for more info on creating a branch. - - Last modified: _6/13/1997_ - - 7. Why does "commit -r <tag/rev>" put newly added files in the Attic? - - If you specify "-r <rev>" (where <rev> is a dotted numeric number like - 2.4), it correctly sets the initial revision to <rev>, but it also - attaches the numeric <rev> as a sticky tag and throws the file into - the Attic. This is a bug. The obvious solution is to move the file out - of the Attic into the associated Repository directory and "update -A" - the file. There are no Tags to clean up. - - If you specify "-r <tag>" to commit a newly added file, the <tag> is - treated like a <branch_tag>, which becomes a symbolic RCS label - pointing to the string '1', which can be considered to be the "Main - branch number" when the main branch is still at revision 1.N. The file - is also thrown into the Attic. See 4C.8 for a way to recover from - this. - - In fact, a plain "commit" without the "-r" will throw a newly added - file into the Attic if you added it to a directory checked out on a - branch. See 3A.[2-5]. - - See Section 4C, on Branching, for many more details. - - Last modified: _6/13/1997_ - - 8. Why would a "commit" of a newly added file not produce rev 1.1? - - When committing a newly added file CVS looks for the highest main - branch major number in all files in the ./CVS/Entries file. Normally - it is '1', but if you have a file of revision 3.27 in your directory, - CVS will find the '3' and create revision 3.1 for the first rev of - <file>. Normally, the first revision is 1.1. - - Last modified: _6/13/1997_ - - Category: /Commands_/diff_di_dif/ - - " + "diff", "di", "dif"" - - 1. What is "diff" for? - - To display the difference between a working file and its BASE - revision (the revision last checked out, updated or committed): - - cvs diff <file> - - To display the difference between a working file and a committed - revision of the same file: - - cvs diff -r <tag/rev> <file> - - To display the difference between two committed revisions of the - same file: - - cvs diff -r <tag1/rev1> -r <tag2/rev2> <file> - - You can specify any number of <file> arguments. Without any <file> - arguments, it compares the whole directory. - - In the examples above, "-D <date>" may be substituted wherever "-r - <tag/rev>" appears. The revision a <date> refers to is the revision - that existed on that date. - - Last modified: _6/13/1997_ - - 2. Why did "diff" display nothing when I know there are later committed - revisions in the Repository? - - By default, "diff" displays the difference between your working file - and the BASE revision. If you haven't made any changes to the file - since your last "checkout", "update" or "commit" there is no - difference to display. - - To display the difference between your working file and the latest - revision committed to your current branch, type: - - cvs diff -r HEAD <file> - - Last modified: _6/13/1997_ - - 3. How do I display what changed in the Repository since I last executed - "checkout", "update" or "commit"? - - A special tag (interpreted by CVS -- it does not appear in the Tag - list) named "BASE" always refers to the revision you last checked out, - updated or committed. Another special tag named "HEAD" always refers - to the latest revision on your working branch. - - To compare BASE and HEAD, you type: - - cvs diff -r BASE -r HEAD <file> - - Last modified: _6/13/1997_ - - 4. How do I display the difference between my working file and what I - checked in last Thursday? - - cvs diff -D "last Thursday" <file> - - where "last Thursday" is a date string. To be more precise, the - argument to the '-D' option is a timestamp. Many formats are accepted. - See the man page under "-D date_spec" for details. - - Last modified: _6/13/1997_ - - 5. Why can't I pass long options, like --unified, to "diff"? - - CVS only handles single character '-X' arguments, not the FSF long - options. CVS also passes through only arguments it knows about, - because a few arguments are captured and interpreted by CVS. - - If you didn't configure RCS and CVS to use the GNU version of diff, - long options wouldn't work even if future versions of CVS acquire the - ability to pass them through. - - Most of the long options have equivalent single-character options, - which do work. The "--unified" option is equivalent to '-u' in - revisions of GNU diff since 1.15. - - Last modified: _6/13/1997_ - - Category: /Commands_/export_exp_ex/ - - " + "export", "exp", "ex"" - - 1. What is "export" for? - - "export" checks out a copy of a module in a form intended for export - outside the CVS environment. The "export" command produces the same - directory and file structure as the "checkout" command, but it doesn't - create "CVS" sub-directories and it removes all the RCS keywords from - the files. - - Last modified: _6/13/1997_ - - 2. Why does it remove the RCS keywords so I can't use the "ident" command - on the source files? - - It removes the RCS keywords, so that if the recipient of the exported - sources checks them into another set of RCS files (with or without - CVS), and then makes modifications through RCS or CVS commands, the - revision numbers that they had when you exported them will be - preserved. (That ident no longer works is just an unfortunate side - effect.) - - The theory is that you are exporting the sources to someone else who - will make independent changes, and at some point you or they will want - to know what revisions from your Repository they started with - (probably to merge changes, or to try to decide whether to merge - changes). - - A better way to handle this situation would be to give them their own - branch of your Repository. They would need to remember to checkin the - exported sources with RCS IDs intact (ci -k) so that their changes - would get revision numbers from the branch, rather than starting at - 1.1 again. Perhaps a future version of CVS will provide a way to - export sources this way. - - Contributed by Dan Franklin - - Last modified: _6/13/1997_ - - 3. Can I override the '-kv' flag CVS passes to RCS? - - Not as of CVS version 1.4. - - Last modified: _6/13/1997_ - - 4. Why doesn't "export" have a '-k' flag like "import" does? - - Export is intended for a specific purpose -- to remove all trace of - revision control on the way *out* of CVS. - - Last modified: _6/13/1997_ - - 5. Why does "export -D" check out every file in the Attic? - - See 5B.3 for an explanation of the same problem with "update". - - Last modified: _6/13/1997_ - - Category: /Commands_/history_hi_his/ - - " + "history", "hi", "his"" - - 1. What is "history" for? - - To provide information difficult or impossible to extract out of the - RCS files, such as a "tag" history or a summary of module activities. - - Last modified: _6/13/1997_ - - 2. Of what use is it? - - I have found it useful in a number of ways, including: - - Providing a list of files changed since - - - A tagged release. - - Yesterday, last Thursday, or a specific date. - - Someone changed a specific file. - - Providing a list of special events: - - - Files added or removed since one of the above events. - - Merge failures since one of the above events. (Where did the - conflicts occur?) - - Has anyone (and who) grabbed the revision of this file I committed - last week, or are they still working blind? - - Telling me how often a file/directory/module has been changed. - - Dumping a summary of work done on a particular module, including who - last worked on it and what changed. - - Displaying the checked-out modules and where they are being worked - on. - - To tell me what users "joe" and "malcolm" have done this week. - - Last modified: _6/13/1997_ - - 3. What is this, Big Brother? - - War is Peace. - Freedom is Slavery. - Ignorance is Strength. - - Normally manager types and those with the power to play Big Brother - don't care about this information. The Software Engineer responsible - for integration usually wants to know who is working on what and what - changed. Use your imagination. - - Last modified: _6/13/1997_ - - 4. I deleted my working directory and "history" still says I have it - checked out. How do I fix it? - - You can use "release -f" to forcibly add a "release" record to the - history file for a working directory associated with a "module". If - your version of "release" doesn't have the '-f' option, or you checked - out the directory using a relative path, you have to edit the - $CVSROOT/CVSROOT/history file. - - You can remove the last 'O' line in the history file referring to the - module in question or add an 'F' record. - - Last modified: _6/13/1997_ - - 5. So I *can* edit the History file? - - Yes, but if you are using history at all, you should take a little - care not to lose information. I normally use Emacs on the file, since - it can detect that a file has changed out from under it. You could - also copy and zero out the history file, edit the copy and append any - new records to the edited copy before replacing it. - - Last modified: _6/13/1997_ - - 6. Why does the history file grow so quickly? - - It stores 'U' records, which come in handy sometimes when you are - tracking whether people have updated each other's code before testing. - There should (and probably will sometime) be a way to choose what - kinds of events go into the history file. - - The contributed "cln_hist.pl" script will remove all the 'U' records, - plus matching pairs of 'O' and 'F' records during your normal clean up - of the history file. - - Last modified: _6/13/1997_ - - 7. What is the difference between "cvs history -r <tag/rev>" and "cvs - history -t <tag>"? - - The '-t' option looks for a Tag record stored by "rtag" in the history - file and limits the search to dates after the last <tag> of the given - name was added. - - The '-r' option was intended to search all files looking for the <tag> - in the RCS files. It takes forever and needs to be rewritten. - - Last modified: _6/13/1997_ - - 8. Why does "cvs history -c -t <tag>" fail to print anything? - - You have been using "tag" instead of "rtag". The "tag" command - currently doesn't store a history record. This is another remnant of - CVS's earlier firm belief in "modules". But it also has a basis in how - "rtag" and "tag" were originally used. - - "rtag" was intended for large-scale tagging of large chunks of the - Repository, an event work recording. "tag" was intended for adding and - updating tags on a few files or directories, though it could also be - used to tag the entire checked-out working tree when there is no - module defined to match the tree or when the working tree is the only - place where the right collection of revisions to tag can be found. - - Last modified: _6/13/1997_ - - 9. "cvs history -a -o" only printed one line for each checked-out module. - Shouldn't it print all the directories where the modules are checked out? - - Not as designed. - - Command Question it is supposed to answer. - ---------------- ------------------------------------------ - cvs history -o What modules do I have checked out? - cvs history -a -o <same for all users> - - cvs history -o -w What working directories have I created - and what modules are in them? - cvs history -a -o -w <same for every user> - - The -o option chooses the "checked out modules" report, which is the - default history report. - - Last modified: _6/13/1997_ - - 10. I can't figure out "history", can you give me concrete examples? - - Default output selects records only for the user who executes the - "history" command. To see records for other users, add one or more "-u - user" options or the '-a' option to select *all* users. - - To list (for the selected users): Type "cvs history" and: - - * Checked out modules: -o (the default) - * Files added since creation: -x A - * Modified files since creation: -c - * Modified files since last Friday: -c -D 'last Friday' - * Modified files since TAG was added: -c -t <tag> - * Modified files since TAG on files: -c -r <tag> - * Last modifier of file/Repository X? -c -l -[fp] X - * Modified files since string "str": -c -b str - * Tag history: (Actually "rtag".) -T - * History of file/Repository/module X: -[fpn] X - * Module report on "module": -m module - - Last modified: _6/13/1997_ - - 11. Can we merge history files when we merge Repositories? - - Assuming that the two Repositories have different sets of pathnames, - it should be possible to merge two history files by sorting them - together by the timestamp fields. - - You should be able to run: - - sort -k 1.2 ${dir1}/history ${dir2}/history > history - - If you "diff" a standard history file before and after such a sort, - you might see other differences caused by garbage (split lines, nulls, - etc) in the file. If your Repository is mounted through NFS onto - multiple machines you will also see a few differences caused by - different clocks on different machines. (Especially if you don't use - NTP to keep the clocks in sync.) - - Last modified: _6/13/1997_ - - Category: /Commands_/import_im_imp/ - - " + "import", "im", "imp"" - - 1. What is "import" for? - - The "import" command is a fast way to insert a whole tree of files - into CVS. - - The first "import" to a particular file within the Repository creates - an RCS file with a single revision on the "Vendor branch." Subsequent - "import"s of the same file within the Repository append a new revision - onto the Vendor branch. It does not, as some seem to believe, create a - new branch for each "import". All "imports" are appended to the single - Vendor branch. - - If the file hasn't changed, no new revision is created -- the new - "Release-Tag" is added to the previous revision. - - After the import is finished, files you have not changed locally are - considered to have changed in the "Main line of development". Files - you *have* changed locally must have the new Vendor code merged into - them before they are visible on the "Main line". - - See 4C.6 and 4C.15 - - Last modified: _6/13/1997_ - - 2. How am I supposed to use "import"? - - Create a source directory containing only the files you want to - import. Make sure you clean up any cruft left over from previous - builds or editing. You want to make sure that the directory contains - only what you want to call "source" from which everything else is - built. - - If this is not the first import from this "Vendor", you should also - compare the output of "find . ! -name CVS -print | sort" executed both - at the head of a checked out working directory and at the head of the - sources to be imported. If you find any deleted or renamed files, you - have to deal with them by hand. (See 4B.8 on renaming.) - - "cd" into your source directory and type: - - cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag> - - where <repos> is the relative directory pathname within the Repository - that corresponds to the sources you are importing. - - You might also consider using the "-I !" option to avoid ignoring - anything. It is easier to remove bogus files from the Repository than - to create a sparse tree of the ignored files and rerun "import". - - For example, if the FSF, CVS, Make and I are still active in the year - 2015, I'll import version 89.53 of GNU make this way: - - cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53 - - See 3H.13 for more details. - - Last modified: _6/13/1997_ - - 3. Why does import put files on a branch? Why can't I work on the main - trunk instead of a Vendor branch? - - This was a Design choice. The Vendor branch is the way "import" deals - with a Vendor release. It is a solution to the Engineering problem of - how to merge multiple external releases of Vendor-supplied sources - into your ongoing work. The Vendor releases are kept on a separate, - special, "Vendor" branch and your work is kept on the RCS trunk. New - Vendor releases are imported onto the Vendor branch and then merged - into your work, if there is any, on the trunk. - - This way, you can use CVS to find out not only about your work, but - you can also find out what the Vendor changed by diffing between two - of the Release Tags you handed to "import". - - CVS was designed to work this way. If you use CVS in some other way, - you should think carefully about what you are doing. - - Note that the CVS "Main Branch" and the RCS Main Trunk are not the - same. Placing files on the Vendor Branch doesn't keep you from - creating a development branch to work on. - - See Section 4C, on Branching. - - If you are not working with 3rd party (i.e. Vendor) sources, you can - skip the "import" and avoid the Vendor branch entirely. It works just - as well to move pre-existing RCS files into Repository directories. - - You can create a whole Repository tree by copying a directory - hierarchy of normal source files directly into the Repository and - applying CVS to it. Here's an idea you should *test* before using: - - cd <your source tree> - set source = `pwd` - set module = xyzzy <<== Your choice of directory name - mkdir $CVSROOT/$module - cd $CVSROOT/$module - (cd $source; tar cf - .) | tar xvpBf - - find . -type f -exec ci -t-Original. {} \; - - The RCS "ci" command, without -u or -l options, will turn your source - file into an RCS (",v") and delete the original source. - - Last modified: _6/13/1997_ - - 4. Is there any way to import binary files? - - If you configured CVS to use the GNU version of "diff" and "diff3", - then you can import any kind of file. - - Binary files with RCS keywords in them are a problem, since you don't - want them to expand. - - If the tree you are about to "import" is entirely filled with binary - files, you can use the '-ko' option on "import". Otherwise, I would - run the import normally, then fix the binary files as described below - in 3H.5. - - See 4D.1 on Binary files. - - Last modified: _6/13/1997_ - - 5. Why does "import" corrupt some binary files? - - The RCS "co" command, when it is invoked by a CVS "checkout" or - "update" (or after a "commit") command, searches for and expands a - list of keywords within the file. They are documented in the RCS "co" - man page. Strings such as "$\Id$" (or "$\Id:"), or "$\Revision$" (or - "$\Revision:") are altered to the include the indicated information. - - [[Note: The keywords should appear in the text without the '\' - character I have inserted to *avoid* expansion here. The only real RCS - keywords in this document are at the top of the file, where I store - the Revision and Date.]] - - If RCS keyword strings show up in a binary file, they will be altered - unless you set the '-ko' option on the RCS files to tell RCS to keep - the original keyword values and not to expand new ones. After - "import", you can set the '-ko' option this way: - - cvs admin -ko <file> - rm <file> - cvs update <file> - - After an import that didn't use '-ko' (because the whole tree wasn't - of binary files) you should fix up the binary files as described above - before checking out any new copies of the files and before updating - any working directories you checked out earlier. - - See 4D.1 on Binary files. - - Last modified: _6/13/1997_ - - 6. How do I retain the original $\Revision$ strings in the sources? - - If you want to leave old RCS keywords as they are, you can use the - '-ko' tricks described above. - - Last modified: _6/13/1997_ - - 7. I imported some files for the Yarg compiler that compiles files with a - suffix of ".yarg" and whose comment prefix is "YARG> ". When I check them - out, they will no longer compile because they have this junk in them. Why? - - YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG> - YARG> $\Log: - # Revision 1.3 1998/03/03 00:16:16 bubba - # What is 2+2 anyway? - # - # Revision 1.2 1998/03/03 00:15:15 bubba - # Added scorekeeping. - YARG> - YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG> - - Well bubba, "Yarg" hasn't hit the big time yet. Neither RCS nor CVS - know about your suffix or your comment prefix. So you have two - choices: - - Check out the Yarg-less module, and tell all the files about your - comment prefix. Visit each directory and type: - - cvs admin -c"YARG> " *.yarg - - If *all* files in the whole directory tree are Yarg files, you can use - this instead: - - cvs admin -c"YARG> " . - - Then save any changes you made, remove all the "*.yarg" files and grab - new copies from the Repository: - - rm *.yarg (or: find . -name '*.yarg' -exec rm {} ';') (or: find . - -name '*.yarg' -print | xargs rm) (or: find . -name '*.yarg' -print0 | - xargs -0 rm if you have spaces in filenames and the GNU find/xargs.) - cvs update - - It might be faster to remove the whole directory and check it out - again. - - Change the import.c file in the CVS sources and add the .yarg - suffix, along with the "YARG> " comment prefix to the "comtable" - array. - - If you ever plan to add new files with $\Log in them, you should also - go into the RCS sources and make the same change in the table - contained in the "rcsfnms.c" file. - - Then delete the imported files from the Repository and re-"import" the - sources. - - Last modified: _6/13/1997_ - - 8. How do I make "import" save the timestamps on the original files? - - Use "import -d" to save the current timestamps on the files as the RCS - revision times. - - See 4D.8 for another aspect of file timestamps. - - Last modified: _6/13/1997_ - - 9. Why can't I "import" 3 releases on different branches? - - I'll bet you typed something like this: - - cd /src/blasto.v2 - cvs import -b 1.1.2 VENDOR2 Version2 - cd /src/blasto.v3 - cvs import -b 1.1.3 VENDOR3 Version3 - cd /src/blasto.v4 - cvs import -b 1.1.4 VENDOR4 Version4 - - This is wrong, or at least it won't help you much. You have created - three separate Vendor branches, which is probably not what you wanted. - - Earlier versions of CVS, as described in Brian Berliner's Usenix - paper, tried to support multiple Vendor branches on the theory that - you might receive source for the *same* program from multiple vendors. - It turns out that this is very rare, whereas the need to branch in - *your* development, for releases and for project branches, is much - greater. - - So the model now is to use a single vendor branch to contain a series - of releases from the same vendor. Your work moves along on the Main - Trunk, or on a CVS branch to support a real "branch in development". - - To set this up, you should type this instead of the above: - - cd /src/blasto.v2 - cvs import VENDOR Version2 - cd /src/blasto.v3 - cvs import VENDOR Version3 - cd /src/blasto.v4 - cvs import VENDOR Version4 - - Last modified: _6/13/1997_ - - 10. What do I do if the Vendor adds or deletes files between releases? - - Added files show up with no extra effort. To handle "removed" files, - you should always compare the tree structure of the new release - against the one you have in your Repository. If the Vendor has removed - files since the previous release, go into a working directory - containing your current version of the sources and "cvs remove" - (followed by "cvs commit" to make it really take effect) each file - that is no longer in the latest release. - - Using this scheme will allow you to "checkout" any version of the - vendor's code, with the correct revisions and files, by using - "checkout -r Version[234]". - - Renames are harder to find, since you have to compare file contents to - determine that one has occurred. If you notice one, see 4B.8 on - renaming files. - - Last modified: _6/13/1997_ - - 11. What about if the Vendor changes the names of files or directories, or - rearranges the whole structure between releases? - - Currently CVS can't handle this cleanly. It requires "renaming" a - bunch of files or directories. - - See 4B.8 on "renaming" for more details. - - What I generally do is to close the Repository for a while and make - changes in both the Repository and in a copy of the vendor release - until the structure matches, then execute the import. - - If you ever have to check out and build an old version, you may have - to use the new, or completely different Makefiles. - - Last modified: _6/13/1997_ - - 12. I thought "import" was for Vendor releases, why would I use it for code - of my own? Do I have to use import? - - For code you produce yourself, "import" is a convenience for fast - insertion of whole trees. It is not necessary. You can just as easily - create ",v" files using the RCS "ci" command and move them directly - into the Repository. - - Other than the CVSROOT directory, the Repository consists entirely of - directories of ",v" files. The Repository contains no other state - information. - - See Section 4B, on Setting up and Managing the Repository. - - Last modified: _6/13/1997_ - - 13. How do I import a large Vendor release? - - When the sum of the changes made by the Vendor and the changes made by - local developers is small, "import" is not a big problem. But when you - are managing a large Repository, any care taken up front will save you - time later. - - First read the following, then, before executing "import", see the - questions in Section 4C dealing with branch merges and Vendor branch - merges. - - If this is not the first import of this code, before starting, rtag - the whole directory you will be changing. - - The first step is to make sure the structure of the new files - matches the structure of the current Repository. - - Run "find . -print | sort" on both trees and "diff" the output. - - Alter the "source" tree until the "diff" (of the list of filenames, - not of the whole trees) shows that the directory structures are - equivalent. - - The "comm" command, if you have it, can help figure out what has been - added or deleted between releases. - - If they deleted any files, you can handle them cleanly with "cvs - remove". The command "comm -23 files.old files.new" will show you a - list of files that need to be removed. - - You should examine the list first to see if any have been renamed - rather than simply deleted. - - If they renamed any files, see 4B.8 on renaming files. - - Remember to *SAVE* the output from the import command. - - When you have dealt with removed and renamed files, then you can - execute the import: - - cd <new source> - cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag> - - Where - - "-I !" is an optional argument that keeps "import" from ignoring - files. The comparison of the "find" commands above will probably avoid - the need for this, but it is easier to remove files from the - Repository than to run a subset "import" to catch just the ignored - files. [You might have to quote or backwhack the '!'.] - - Message is the log message to be stored in the RCS files. - - <repos> is a relative path to a directory within the - Repository. The directory <new source> must be at - the same relative level within the new sources as - the <repos> you give is within the Repository. (I - realize this is not obvious. Experiment first.) - - <VendorTag> is a Tag used to identify the Vendor who sent you - the files you are importing. All "imports" into - the same <repos> *must* use the same VendorTag. - You can find it later by using the "log" command. - - <ReleaseTag> is a Tag used to identify the particular release of the - software you are importing. It must be unique and should be mnemonic - -- at least include the revision number in it. (Note: you can't use - '.' characters in a Tag. Substitute '_' or '-'.) - - There will be six categories of files to deal with. (Actually there - are eight, but you have already dealt with "removed" and "renamed" - files.) - - If this is the first "import" into a given <repos> directory, only the - first three of these ('I', 'L' and 'N') can occur. - - Ignored file. - - CVS prints: I filename - - You'll need to examine it to see if it *should* have been ignored. If - you use "-I !", nothing will be ignored. - - Symbolic link. - - CVS prints: L linkname - - Links are "ignored", but you'll probably want to create a "checkout - helper" function to regenerate them. - - New file. - - CVS prints: N filename - - CVS creates a new file in the Repository. You don't have to do - anything to the file, but you might have to change Makefiles to refer - to it if this is really a new file. - - A file unchanged by the Vendor since its last release. - - CVS prints: U filename - - CVS will notice this and simply add the new ReleaseTag to the latest - rev on the Vendor branch. - - No work will be needed by you, whether you have changed the file or - not. No one will notice anything. - - A file changed by the Vendor, but not by you. - - CVS prints: U filename - - CVS should add the file onto the vendor branch and attach the Release - Tag to it. - - When you next execute "update" in any working directory you'll get the - new revision. - - A file changed by both the Vendor and by you. - - CVS prints: C filename - - These are the trouble files. For each of these files (or in groups -- - I usually do one directory at a time), you must execute: - - cvs update -j <PreviousReleaseTag> -j <ReleaseTag> - or - cvs update -j <VendorTag:yesterday> -j <VendorTag> - - It will print either 'M' (if no overlaps) or 'C', if overlaps. If a - 'C' shows up, you'll need to edit the file by hand. - - Then, for every file, you'll need to execute "cvs commit". - - See the part of Section 4C dealing with branch merges. - - If you are truly performing a large import, you will most likely - need help. Managing those people is another problem area. - - Since the merge of the Vendor branch is just like any other merge, you - should read section 4C for more info about performing and cleaning up - merges. - - The larger the import, and the larger the group of people involved, - the more often you should use "tag" and "rtag" to record even trivial - milestones. See 4C.14, especially the "paranoid" section. - - Before starting the import, you should install and test a "commitinfo" - procedure to record all commits in a file or via Email to a mail - archive. Along with the tags you placed on the Repository before the - import, this archive will help to track what was changed, if problems - occur - - There are four stages to the recovery: - - Parcel out the work -- Effective Emacs Engineering. - - As input to the assignment process, you might want to examine the tree - and record the last person who changed the file. You can also - research, if you don't already know, who is expert in each area of the - software. - - Examine the import log (you saved the output, right?), estimate how - much work is involved in each area and assign groups of files to - individual developers. Unless some directory is immense, it is easier - to manage if you assign whole directories to one person. - - Keep a list. Suggest a completion date/time. Tell them to "commit" the - file when they are finished with the merge. If you tagged the - Repository before starting the import, you should have no trouble - figuring out what happened. - - If you can, find out (or tell them) which working directory to use. - You should verify that the working directory they use is on the Main - Branch ("update -A") and without modified files. - - If you trust your crew, have them notify you by Email. Have them send - you the output from "cvs update" in their working directory. You might - have to poll some people until you are certain they have finished, or - have given up. (This is not an invention. I've heard a false, "Yeah, - sure. I finished yesterday," more times that you'd believe.) - - When all reports are in, go on to the Source Verification stage. - - Source Verification -- CVS and other Tools. - - If you didn't dictate which ones to use, find all working directories - and run "cvs -n update" in all of them. The history command and the - "commitinfo" log you set up might help to find checked out working - directories. - - Sticky conflict flags will help, but they can't recover from - sloppiness or incompetence. You might want to check everything out - into a tree and grep for the parts of the merge conflict markers CVS - doesn't look for. CVS looks for the string '^>>>>>>> '. The merge - operation also puts '^<<<<<<< ' and '^======= ' markers in the file - that careless developers might leave there. - - If you find problems simply by looking at the source files and working - directories, start the flogging now. Resolving the textual conflicts - is the easy part. Weed the turkeys out before reaching the next part - of the cleanup -- the resolution of logical conflicts. - - Then apply a set of post-commit tags. - - Logical Verification -- Diff and powerful eyeballs. - - No source control system can solve the problem of resolving - distributed conflicts in program logic. If you change the argument - template for function A (defined in file A.c) and add new calls to - function A from within function B (defined in file B.c) using the old - argument format, you are outside the realm of CVS's competence. - - Assign someone to understand what the Vendor changed by running "cvs - diff -c -r <PreviousReleaseTag> <ReleaseTag>", where the tags were - those handed to the last two invocations of "import". - - Then have the same person compare that output (logically or you can - actually diff the diffs) to the output of the similar "cvs diff -c -r - <pre-import-tag> <post-commit-tag>". The two sets of differences - should be almost identical. They should both show only the work *you* - have performed. - - Product Verification -- Build and Test. - - Don't let your help off the hook until you verify that the merge - actually produced something that can compile and pass tests. Compiling - should really be part of the logical verification phase, but you - should test the output of the build system before declaring victory - and releasing the troops. - - After it is all built, apply another set of tags to mark the end of - the "import process". You can delete the intermediate tags you added - during source and logic testing, but keep the "pre-import" and - "post-import" tags forever. - - Of course, experience can tell you when to skip a step. But I'd start - out by considering each one as necessary unless you can prove - otherwise. - - Last modified: _6/13/1997_ - - 14. Explain: ERROR: cannot create link to <file>: Permission denied - - This error appears when you try to execute a second (or later) - "import" into the same module from a directory to which you don't have - write access. - - The "link error" is caused by a feature purposely added to speed up - the import. - - Though the error message is somewhat strange, it indicates that - "import" is supposed to be executed only in writable directories. - - Last modified: _6/13/1997_ - - 15. Where does the -m <message> go when the file doesn't change? - - The <message> handed to import is used as an RCS log message, but only - if the imported file changed since the last version on the Vendor - branch. If the imported file hasn't changed, then no new revision is - created. The <ReleaseTag> is still applied, but to the previous - revision. So the Tags are still correct, but the message is lost. - - Maybe it should be appended to the previous log message. But currently - it isn't. - - Last modified: _6/13/1997_ - - 16. How do I "import" just the files ignored by a previous "import"? - - A real answer follows, but first, an editorial: - - I am now convinced that you should always use the "-I !" option. - Removing a few extraneous files from the Repository is a lot easier - than the recovery step described below. - - Let's assume your original import procedure was: (We assume there is - enough disk space in /tmp.) - - cd <head-of-vendor-tree> - cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP - - To import just the files ignored by "import", I would do this: - - Create a list of the ignored files to import: - - cd <head-of-vendor-tree> awk '/^I / {print $2}' /tmp/IMP | sed - 's|^gnu/xyz/||' > /tmp/IG [Edit the IG file to contain just the files - you want.] - - Then create a sparse directory by handing your list to the GNU - version of "tar", installed in many places as "gtar": - - mkdir /tmp/FIXUP gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf - -) - - Then rerun the import. Use the exact same command, but execute it in - the sparse directory tree you just created. And this time, tell it not - to ignore anything. - - cd /tmp/FIXUP - cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 - - Last modified: _6/13/1997_ - - 17. Why did "import" ignore all the symlinks? - - This is another design choice. - - Like the Unix "tar" command, "import" could sprout an option to follow - symbolic links, but I don't think CVS will ever follow symbolic links - by default. - - Two possible future enhancements have been seriously discussed: - - Treat symbolic links as data in its parent directory (the way - ClearCase does) in some sort of per-directory control file. - - Treat symbolic links as version-controlled elements themselves, - whose data is the value of readlink(2). - - For now, they are simply ignored. - - If you want to save and reconstruct symlinks, you might want to define - a "checkout" or "update" program in the modules file which could - consult a file kept under CVS in your working directory and make sure - the specified links are in place. - - Last modified: _6/13/1997_ - - Category: /Commands_/log_lo_rlog/ - - " + "log", "lo", "rlog"" - - 1. What is "log" for? - - To provide an interface to the RCS "rlog" command, which displays - information about the underlying RCS files, including the revision - history and Tag (RCS calls it a "symbol") list. - - Last modified: _6/13/1997_ - - 2. How do I extract the log entries between two revisions? - - If both <rev1> and <rev2> are on the same branch, you can get what you - are looking for with: (If they aren't on the same branch you'll either - get an error or a display of the whole change log.) - - cvs log -r<rev1>:<rev2> <file> - - If you want all the revisions on the branch from <rev1> to the end of - the branch <rev1> is on, you can use: - - cvs log -r<rev1>: <file> - - (If <rev1> is a numeric RCS symbol attached to a branch revision with - an even number of '.'s in it, you get the whole branch.) - - If you want all the revisions on the branch from the beginning of the - branch <rev2> is on up to revision <rev2>, you can use: - - cvs log -r:<rev2> <file> - - Note: Depending on whether <rev1> and <rev2> are: - - - numeric or symbolic - - in the file or not - - on the same branch or not - - the RCS "rlog" (and therefore the "cvs log") command will - display some combination of: - - - error messages - - (intuitively correct) partial log listings - - a display of the entire change log. - - Last modified: _6/13/1997_ - - 3. How do I extract the log entries on a whole branch? - - cvs log -r<rev> <file> - - where <rev> must be a branch revision (one with an even number of - dots) or a *non-branch* tag on a branch revision. Non-branch tags on a - branch revision are not normally attached by CVS, to add one you will - have to explicitly tag a physical branch number within each file. - Since these branch numbers are almost never the same in different - files, this command is not all that useful. - - The intuitive command (at least from the CVS perspective): - - cvs log -r<branch_tag> <file> - - does not work. - - Last modified: _6/13/1997_ - - 4. How do I generate ChangeLogs from RCS logs? - - A program called rcs2log is distributed as part of GNU Emacs 19. A - (possibly older) version of this program appears in the contrib - directory of the cvs source tree. - - Last modified: _6/13/1997_ - - 5. Why does "log" tell me a file was committed exactly 5 hours later - - than I know it was? - - I can tell by this question that you were working in a time zone that - is 5 hours behind GMT (e.g. the U.S. East Coast in winter). - - RCS file dates are stored in GMT to allow users in different time - zones to agree on the meaning of a timestamp. At first glance this - doesn't seem necessary, but many companies use distributed file - systems, such as NFS or AFS, across multiple timezones. - - Some standard form must be used. GMT, as the "grid origin", is an - obvious candidate. The only other reasonable choice is to put the - timezone information in all the time stamps, but that changes the RCS - file format incompatibly, a step which has been avoided in the last - few RCS releases. - - Last modified: _6/13/1997_ - - Category: /Commands_/patch_pa_rdiff/ - - " + "patch", "pa", "rdiff"" - - 1. What is "patch" for? - - To produce a "diff" between tagged releases to be handed to the - "patch" command at other sites. This is the standard way that source - patches are distributed on the network. - - Last modified: _6/13/1997_ - - 2. Why does "patch" include files from the Attic when I use '-D'? - - See the explanation of the same problem with "update -D" contained in - section 5B. - - Last modified: _6/13/1997_ - - 3. How do I make "patch" produce a patch for one or two files? It seems to - work only with modules. - - Patch is intended for producing patches of whole modules between - releases to be distributed to remote sites. Instead of "patch", you - can use the "diff" command with the '-c' context option: - - cvs diff -c -r <rev/tag> -r <rev/tag> <file1> . . . - - The patch command will be able to merge such a "diff" into the remote - source files. - - If you configured CVS to use a version of "diff" that supports the - '-u' option, you can produce a more compact "patch" in "unidiff" - format. The latest revisions of the patch command can parse and apply - patches in "unidiff" format. - - Last modified: _6/13/1997_ - - Category: /Commands_/release_re_rel/ - - " + "release", "re", "rel"" - - 1. What is "release" for? - - To register that a module is no longer in use. It is intended to - reverse the effects of a "checkout" by adding a record to the history - file to balance the checkout record and by optionally allowing you to - delete the checked-out directory associated with the module name. - - Last modified: _6/13/1997_ - - 2. Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs - release path/name/subdir" without an "unknown module name"? - - A simplistic implementation. (I can say this -- I wrote it.) - - The "release" function was written for CVS 1.2 under the assumption - that the "module name" is a first class, unavoidable interface to the - Repository, allowing no way to retrieve anything other than by module - name. Though it is easier to program that way, many users of CVS - believe the modules support to be too primitive to allow such a - limitation. - - Since "release" was written, other parts of CVS broke that assumption. - It needs to be revised. - - Last modified: _6/13/1997_ - - 3. Why can't I "release" portions of a checked out directory? I should be - able to "release" any file or sub-directory within my working directory. - - This isn't really a limitation in "release", per se. CVS doesn't try - to keep track of which files in which directories are "checked out" - and which are just lying there. You can delete directories and - "update" will not bring them back unless you add a special "-d" - option. - - In other words, CVS doesn't keep track of how you adjust the partition - between files you consider part of your working set and files that - were checked out because they are part of the same module or - directory. And neither does "release". - - In future CVS releases, "release" might become sophisticated enough to - handle both the reversal of a "checkout" and the deletion of random - portions of the working directory, but it isn't that way now. - - Last modified: _6/13/1997_ - - 4. I removed the tree that I was about to start working on. How do I tell - cvs that I want to release it if I don't have it anymore? - - See 3G.4. - - Last modified: _6/13/1997_ - - 5. Why doesn't "release -d module" reverse a "checkout module"? - - It does, if you are using "module" in a way that "release" expects: a - non-alias string in the left column of the "modules" database. - - If "module" is really an alias, or if you are using a relative path in - the place of "module", or if you renamed the directory with the -d - option in the modules file or on the "checkout" command line, then the - current version of "release" won't work. - - Future versions of "release" will probably fix most of these. - - Last modified: _6/13/1997_ - - 6. Why can't I release a module renamed with "cvs checkout -d"? - - The current version of "release" doesn't know how to track the - renaming option ('-d') of the "checkout" command. It will probably be - fixed in the future. - - Last modified: _6/13/1997_ - - Category: /Commands_/remove_rm_delete/ - - " + "remove", "rm", "delete"" - - 1. What is "remove" for? - - To remove a file from the working branch. It removes a file from the - main branch by placing it in an "Attic" directory. - - Last modified: _6/13/1997_ - - 2. Why doesn't "remove" work on directories when it appears to try? - - Oversight. It should be able to delete an empty directory, but you - still don't have a way to remember when it was there and when it - disappeared to allow the "-D " option to work. - - You'll have to remove the working directory and the matching directory - in the Repository. - - Note that you want to do a _cvs remove dir_ in the working directory, - do a cvs commit, and then do a _rmdir dir_ in the Repository. - (msusrtsp.mark at eds dot com) - - Last modified: _12/18/1997_ - - 3. I don't like removing files. Is there another way to ignore them? - - There's no reason to be hasty in using the "remove" command. - - If there is a way to ignore files in your build procedures, I'd just - do that. Later, when you decide that the files are really ancient, you - can execute a "remove" command to clean up. - - The CVS "ignore" concept can't ignore files already in CVS. - - Last modified: _6/13/1997_ - - 4. I just removed a file. How do I resurrect it? - - If you executed "remove", but haven't typed "commit" (you can tell - this by the 'R' notation that "update" prints next to the file), you - can execute "add" to reverse the "remove". - - If you followed the "remove" with a "commit", you'll have to move it - back out of the Attic by hand: - - I use something like this: (csh-like syntax) - - set repos = `cat ./CVS/Repository` - mv $repos/Attic/filename,v $repos/filename,v - - (If you use relative paths in your Repository files, that first line - becomes: set repos = $CVSROOT/`cat ./CVS/Repository`) - - While a file is in the Attic, you can't "add" another file by the same - name. To add such a file you either have to move it by hand as in the - above, or delete it from the Attic. - - The main reason for the Attic is to retain files with tags in them. If - you execute: "update -r <oldtag>", files with <oldtag> attached to - some revision will be taken from the normal Repository area and from - the Attic. That's why you can't "add" a file with the same name. - "remove" only moves a file off the main branch, it doesn't obliterate - it. - - Last modified: _6/13/1997_ - - 5. Why doesn't "remove" delete the file? Instead, it prints an error - message and tells me to remove the file by hand. - - Design choice. Unix software written within last decade, usually - requires an extra verification step, such as answering a question or - adding a flag on the command line. CVS currently requires that you - delete the file first unless you specify the '-f' (force) option, - which deletes the file before performing "cvs remove". - - Last modified: _6/13/1997_ - - Category: /Commands_/rtag_rt_rfreeze/ - - " + "rtag", "rt", "rfreeze"" - - 1. What is "rtag" for? - - To add a symbolic label (a "tag") to the last committed revisions of a - module directly in the Repository. - - Last modified: _6/13/1997_ - - 2. Why use "rtag"? It assumes no one is changing the Repository. - - Though the "tag" command is more useful in marking the revisions you - have in a particular working directory, "rtag" is much handier for - whole-Repository actions, which occur at major release boundaries. - - Last modified: _6/13/1997_ - - 3. What revision does "rtag -r <tag1> <tag2>" actually put the tag on? - - In short, the '-r' option is another way to select the revision to - tag. The revision is selected the same way for all commands that - accept a "-r <tag/rev>" option. - - Depending on whether <tag1> is a <branch_tag>, or a non-branch <tag> - and on whether you use the '-b' option to "rtag", you get four - different results: - - rtag -r <tag1> <tag2> - - Adds the non-branch tag <tag2> to the same revision that the - non-branch tag <tag1> is attached to. - - Example: - <tag1> --> TT1 - <tag2> --> TT2 - <file> --> Symbols: TT1:1.4 - After --> Symbols: TT1:1.4,TT2:1.4 - - rtag -r <branch_tag1> <tag2> - - Adds the non-branch tag <tag2> to the HEAD of (the highest revision - number on) the branch labelled with tag <branch_tag1>. - - Example: - <branch_tag1> --> BR1 - <tag2> --> TT2 - <file> --> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD) - After --> Symbols: BR1:1.2.0.2,TT2:1.2.2.5 - - If the branch tagged by <branch_tag1> has not been created, then the - tag shows up on the branch point revision: - - Example: - <branch_tag1> --> BR1 - <tag2> --> TT2 - <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.) - After --> Symbols: BR1:1.2.0.2,TT2:1.2 - - rtag -b -r <tag1> <branch_tag2> - - Adds the magic branch tag <branch_tag2> to the revision that the - non-branch tag <tag1> is attached to, preparing it to be a branch - point. - - Example: - <tag1> --> TT1 - <branch_tag2> --> BR2 - <file> --> Symbol: TT1:1.4 - After --> Symbol: TT1:1.4, BR2:1.4.0.2 - - rtag -b -r <branch_tag1> <branch_tag2> - - Adds the magic branch tag <branch_tag2> to the revision at the HEAD of - (the highest revision number on) the branch labelled with - <branch_tag1>, preparing it to be a branch point. - - Example: - <branch_tag1> --> BR1 - <branch_tag2> --> BR2 - <file> --> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD) - After --> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2 - - If the branch tagged by <branch_tag1> has not been created, then the - tag shows up as a second branch off the same branch point revision: - - Example: - <branch_tag1> --> BR1 - <tag2> --> TT2 - <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.) - After --> Symbols: BR1:1.2.0.2,TT2:1.2.0.4 - - In all four cases above, if <tag2> already exists on the file, you get - an error unless you specify the '-F' option. - - In all four cases, if <tag1> does not exist on the file, <tag2> is not - added unless you specify the '-f' option. - - Last modified: _6/13/1997_ - - 4. What happens if the tags are the same in "rtag -r <tag> <tag>"? - - Again, there are four cases depending on whether <tag> is a branch - tag, or a non-branch tag and on whether you use the '-b' option to - "rtag": - - rtag -r <tag> <tag> - - Is a no-op. It does nothing even with '-F' specified. - - If you add the '-f' option ("rtag -f -r <tag> <tag>"), then <tag> is - attached to the latest revision on the Main Branch if the file does - *not* already have <tag> on some revision. - - If the <tag> is already on the file, using "rtag -f" is still a no-op. - - rtag -r <branch_tag> <branch_tag> - - Produces an error, since the <branch_tag> is already on some revision - of the file. - - But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic branch tag - into a non-branch tag. - - Symbols: BR1:1.4.0.2 becomes Symbols: BR1:1.4 - - rtag -b -r <tag> <tag> - - Produces an error, since the <tag> is already on the file. - - But, "rtag -F -b -r <tag> <tag>" turns the non-branch tag into a magic - branch tag. - - Symbols: BR1:1.4 becomes Symbols: BR1:1.4.0.2 - - rtag -b -r <branch_tag> <branch_tag> - - Produces an error, since the <branch_tag> is already on the file. - - But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the branch - number. It essentially removes the branch and creates a new one by the - same name. - - Symbols: BR1:1.2.0.4 becomes Symbols: BR1:1.2.0.6 - - Last modified: _6/13/1997_ - - 5. Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or duplicate - a magic branch tag? - - None of the "tag" or "rtag" options rename anything. They only apply - (or, with the '-F' option, move) tags to specific revisions in the - file. - - See 3M.[3-4] above for details of how it works. - - To rename a non-branch tag, see 3O.9. To rename a magic branch tag, - see 4D.5 - - Last modified: _6/13/1997_ - - Category: /Commands_/status_st_stat/ - - " + "status", "st", "stat"" - - 1. What is "status" for? - - To display the status of files, including the revision and branch you - are working on and the existence of "sticky" information. - - Last modified: _6/13/1997_ - - 2. Why does "status" limit the File: at the top to 17 characters? - - Designed that way to line up with other data. You can find the whole - filename in the line beginning with "RCS version:", which is not - limited in length. - - Last modified: _6/13/1997_ - - 3. Why does it print "Sticky" lines when the values are "(none)"? - - Oversight. It should probably elide lines without information. - - Last modified: _6/13/1997_ - - 4. Shouldn't the status "Needs Checkout" be "Needs Update"? - - Probably. - - [[Did this show up in CVS 1.4?]] - - Last modified: _6/13/1997_ - - Category: /Commands_/tag_ta_freeze/ - - " + "tag", "ta", "freeze"" - - 1. What is "tag" for? - - To add a symbolic label (a "tag") to the RCS files last checked out, - updated or committed in a working directory. - - Last modified: _6/13/1997_ - - 2. What is the difference between "tag" and "rtag"? - - The end result of both commands is that a <tag>, or symbolic name, is - attached to a single revision in each of a collection of files. - - The differences lie in: - - The collection of files they work on. - - "rtag" works on the collection of files referred to by a "module" name - as defined in the "modules" file, or a relative path within the - Repository. - - "tag" works on files and directories specified on the command line - within the user's working directory. (Default is '.') - - Both commands recursively follow directory hierarchies within the - named files and directories. - - The revisions they choose to tag. - - "rtag" places a tag on the latest committed revision of each file on - the branch specified by the '-r' option. By default it tags the Main - Branch. - - "tag" places a tag on the BASE (i.e. last checked out, updated or - committed) revision of each file found in the working directory. (The - BASE revision of a file is the one stored in the ./CVS/Entries file.) - - A different set of command line options. - - For example, "rtag" takes a "-r <oldtag>" option to retag an existing - tag. The "tag" command does not. - - How it is logged. - - Currently "rtag" records the <tag> and the module in the "history" - file, while "tag" does not. - - Last modified: _6/13/1997_ - - 3. Why does "tag -b" not put a tag on the Branch Point revision? How do I - refer to the Branch Point? - - This is probably an oversight, or a disbelief in the need for it. If - everything works perfectly, the "update -j" command will do the merge - you need and you don't need to check up on it by playing with the - branch point revision. - - The '-b' option attaches a magic branch tag to allow CVS later to - figure out the branch point. The actual revision that <tag> is - attached to does not exist. References to the branch tag are - equivalent to references to the latest revision on the branch. - - There is no way to refer to the branch point without adding a - non-branch tag. You might want to add non-branch tags as a habit and - add branch tags later, possibly immediate after adding the non-branch - tag. See 4C.3 on Creating a Branch. - - Last modified: _6/13/1997_ - - 4. So "{r}tag" labels a bunch of files. What do you use a Tag for? - - You use it to "checkout" the labeled collection of files as a single - object, referring to it by name. - - Anywhere a revision number can be used a Tag can be used. In fact tags - are more useful because they draw a line through a collection of - files, marking a development milestone. - - The way to think about a Tag is as a curve drawn through a matrix of - filename vs. revision number. Consider this: - - Say we have 5 files (in some arbitrary modules, some may be in 2 or - more modules by name, some may be in 2 or more modules because of the - Repository tree structure) with the following revisions: - - file1 file2 file3 file4 file5 - - 1.1 1.1 1.1 1.1 /--1.1* <-*- <tag> - 1.2*- 1.2 1.2 -1.2*- - 1.3 \- 1.3*- 1.3 / 1.3 - 1.4 \ 1.4 / 1.4 - \-1.5*- 1.5 - 1.6 - - At some time in the past, the '*' versions were tagged. Think of the - <tag> as a handle attached to the curve drawn through the tagged - revisions. When you pull on the handle, you get all the tagged - revisions. Another way to look at it is that you draw a straight line - through the set of revisions you care about and shuffle the other - revisions accordingly. Like this: - - file1 file2 file3 file4 file5 - - 1.1 - 1.2 - 1.1 1.3 _ - 1.1 1.2 1.4 1.1 / - 1.2*----1.3*----1.5*----1.2*----1.1 (--- <-- Look here - 1.3 1.6 1.3 \_ - 1.4 1.4 - 1.5 - - I find that using these visual aids, it is much easier to understand - what a <tag> is and what it is useful for. - - Last modified: _6/13/1997_ - - 5. How do I get "tag" and "rtag" to send mail the way "commit" does? - - The "commit" command is supported by two files ("commitinfo" and - "loginfo") not used by other commands. To do logging the same way for - "tag" and "rtag" would require another file like loginfo, which - currently doesn't exist. - - The "rtag" command requires a "module" entry, which can specify a - "tag" program using the "-t programname" option on the module line. - - There is no equivalent support for "tag". - - Last modified: _6/13/1997_ - - 6. Why can't "tag" handle the '-r' option that "rtag" takes? - - Oversight. The answer is probably "Fixed in a Future Release." - - Last modified: _6/13/1997_ - - 7. After a "tag <tag>" in my working directory, why doesn't "checkout -r - <tag>" somewhere else produce copies of my current files? - - The only reason this would fail, other than misspelling the <tag> - string, is that you didn't "commit" your work before "tagging" it. - Only committed revisions may be tagged. Modified files are not marked - for later tagging. - - Last modified: _6/13/1997_ - - 8. Why doesn't "tag" write a history record the way "rtag" does? - - The "rtag" command was originally intended to place major "release" - tags onto modules. The "tag" functionality was developed to *move* the - more significant tag when slight changes to individual files sneaked - in after the release tag was stamped onto the Repository. - - The significant event was the "rtag", which was recorded in the - "history" file for the "history -T" option to work. - - It turns out that "tag" is generally more useful than "rtag", so the - model has changed. Future revisions of CVS will probably store both - kinds of tags in the history file. - - Last modified: _6/13/1997_ - - 9. How do I rename a <tag>? - - For a procedure to rename a branch tag, See section 4D.5 The following - covers only non-branch tags. - - First, pick a <newtag> that is not in use. You could reuse (i.e. move) - an existing tag to the new revisions using the '-F' option, but that - will confuse matters when both tags are not already on a file. (It - will probably confuse "rtag -f" too.) - - Use "rtag" to place <newtag> only on revisions attached to <oldtag> in - the whole Repository, then delete the old one. - - cvs rtag -r <oldtag> <newtag> world - cvs rtag -d <oldtag> world. - - You can also checkout or update your working directory to the <oldtag> - and "tag" rather than "rtag" the result. But that will take longer and - it has the chance of producing conflicts. - - cvs update -r <oldtag> - cvs tag <newtag> - cvs tag -d <oldtag> - cvs update -A (or cvs update -r <previous_tag>) - - Last modified: _6/13/1997_ - - Category: /Commands_/update_up_upd/ - - " + "update", "up", "upd"" - - 1. What is "update" for? - - The "update" command is by far the most important command and is - probably also the most used command. - - It has five purposes: (And many options.) - - To display the status of your working files. - - Though a plain "update" also displays the status, it does so after - possibly altering your working directory. To see the status of your - working files without changing anything, type: - - cvs -n update {optional list of files} - - To merge changes made by others to the branch you are working on - into your working files. - - Each working directory is attached to a branch, usually the Main - branch. To merge changes made on your working branch since your last - checkout, update or commit, type: - - cvs update {optional list of files} - - To merge changes made on another branch into the branch you are - working on (your "working branch"). - - If you want to grab a whole branch, from the branch point, which is - assumed to be on the Main Branch, to the end of the branch, you type: - - cvs update -j <branch_tag> {optional files} - - If you want to grab the changes made between two tags or revisions, - you type: - - cvs update -j <tag1> -j <tag2> {optional files} - - (If you are working with a single file, the Tags could also be - revisions numbers. Unless you take great care to match revision - numbers across different files (a waste of time given the way Tags - work), using revision numbers in place of the Tags for multiple files - would be meaningless.) - - To move your working directory to another branch. - - A working directory is presumed to be attached to (or working on) a - particular branch, usually the Main branch. To alter what CVS believes - to be your working branch, you "move" to that branch. - - To move to a tagged branch, type: - - cvs update -r <branch_tag> {optional files} - - To move to the Main Branch, type: - - cvs update -A {optional files} - - If you have modified files in your working directory, this is not a - clean move. CVS will attempt to merge the changes necessary to make it - look like you made the same changes to the new branch as you made in - the old one. But if you do this twice without resolving the merge - conflicts each time, you can lose work. - - To retrieve old revisions of files. - - This option is similar to 4 above but you are not restricted to using - a <branch_tag>. You may specify any revision or <tag> with '-r' and - get the specified revision or the tagged revision: - - cvs update -r <tag/rev> {optional files} - - Or you may specify any date with '-D': - - cvs update -D <date> {optional files} - - The '-p' option sends the revisions to standard output (normally your - terminal) rather than setting the "sticky" tag and changing the files. - - Last modified: _6/13/1997_ - - 2. What do 'U', 'M' and 'C' mean when I type "update"? Are they different - for "cvs -n update"? - - "cvs update" merges changes made to the Repository, since your last - "checkout", "update" or "commit", into your working files. You can - think of it as changing your BASE revision. - - "cvs update" prints lines beginning with: - - 'U' after replacing your unmodified file with a different - revision from the Repository. - - 'M' for two different reasons: - - for files you have modified that have not changed in the Repository. - - after a merge, if it detected no conflicts. - - 'C' after a merge, if it detected conflicts. See 2D.7 and 3P.6 for - more info on conflict resolution and "sticky conflicts." - - "cvs -n update" shows what it *would* do, rather than doing it. Or, - another way of looking at it, "cvs -n update" displays the - relationship between your current BASE revisions (identified in your - ./CVS/Entries file) and the HEAD revisions (the latest revisions in - the Repository). - - "cvs -n update" prints lines beginning with: - - 'U' for files you have not modified that have changed in the - Repository. - - 'M' for files you have modified that have not changed in the - Repository. - - 'C' for files you have modified that have also been changed in the - Repository. - - See 4C.6 for what the letters mean when merging in from another - branch. The output is almost the same for a normal update if you - consider the Repository as the branch and your working directory as - the "trunk". - - Last modified: _6/13/1997_ - - 3. What's the difference between "update" and "checkout"? - - See 3C.4 above. - - Last modified: _6/13/1997_ - - 4. Why don't I get new files when I execute "update"? - - There are six reasons for nothing to happen during an "update": - - Nothing on your branch changed in the Repository. - - If no one has committed anything to the branch you are working on - (normally the Main branch) since the last time you executed - "checkout", "update" or "commit", nothing will happen. - - It's like shouting "xyzzy" or "plugh" in the wrong room. - - You have a "sticky" non-branch <tag> or <date> attached to the - working files you are trying to "update". - - At some time in the past you checked out or updated your directory - with the "-r <tag>" or "-D <date>" option. Until you do it again with - a different tag or date, or go back to the Main Branch with "update - -A", you will never again see any updates. - - The ./CVS/Entries.Static file exists and you are expecting a new - file. - - If your ./CVS administrative directory contains a file named - Entries.Static, no files will be checked out that aren't already in - the Entries or Entries.Static file. - - You forgot to use the '-d' option and are looking for new - directories. - - If you execute "update" without the '-d' option, it will not create - new directories that have been added to the Repository. - - You typed "update" instead of "cvs update". - - On most Unix systems, your disk caches are now furiously being flushed - by multiple update daemons, destroying performance and proving to - management that you need more CPU power. :-) - - On HP systems you might be asked what package you want to install from - the "update server". - - Someone removed (using "admin -o") your BASE revision (the revision - CVS thought you had in your working directory), then committed a - "replacement". CVS is now confused because the revision in the - Repository matches your BASE revision when the files themselves don't - match. See 3B.6. - - Last modified: _6/13/1997_ - - 5. Why does "update" say 'M' both for plain modified files and for - successful (i.e. conflict-free) merges? Aren't they different? - - A design choice. Yes, they are different internally, but that - shouldn't matter. Your files are in the same condition after the - "update" as they were before -- a "diff" will display only your - modifications. And you are expected to continue onward with parts two - and three of the normal development cycle: "emacs" (a synonym for - "edit" in most of the civilized world) and "commit". - - Last modified: _6/13/1997_ - - 6. What's a "sticky conflict"? How does it know a conflict occurred? - - When a "cvs update" (or an "update -j") creates a conflict, it prints - a 'C' and stores the timestamp of the file after the merge in a - special field in the ./CVS/Entries file. - - This conflict indication implies that the merge command altered your - working file to contain conflict markers surrounding the overlapping - code segments. For example, say that - - - Two developers acquire revision 1.2 of <file> via "checkout" or - "update". - - - Developer A changes line 1 from "9999" to "5555", then commits the - file, creating revision 1.3. - - - Developer B changes line 1 from "9999" to "7777", then tries to - commit the file, but is blocked because the file is not up to date. - Developer B then runs "update" and sees the conflict marker 'C'. The - beginning of the file would look like this: - - <<<<<<< <file> The working <file> in question. - 7777 Change made to the working <file>. - ======= - 5555 Change made in the first commit (1.3) - >>>>>>> 1.3 The revision created by the first commit. - - The conflict is "sticky", which means that until the conflict is - cleared, the "update" command will continue to display the file's - status as 'C' and the "status" command will show the file's status as - "Unresolved Conflict". - - Until the conflict is cleared, "commit" is blocked for this file. - - The sticky conflict indicator can be cleared by: - - Resolving the conflict by editing the file. Two things must happen - before the conflict is considered resolved: - - The timestamp of the file must change. *and* The file must contain no - conflict markers. (The string searched for in the file is the regexp: - "^>>>>>>> ".) - - After clearing the sticky conflict indicator, you may then commit the - file normally. - - Removing the file and running "update". This throws away the local - changes and accepts the latest committed file on this branch. No - commit is needed. - - Forcing the commit to happen by using "commit -f". This is probably - a mistake since there are few lines of real text that begin with - ">>>>>>> ". - - Last modified: _6/13/1997_ - - 7. Is there a feature to tell me what I have changed, added and removed - without changing anything? - - The command "cvs -n update" will do exactly that. - - Last modified: _6/13/1997_ - - 8. Why were all my files deleted when I executed "update"? - - You probably executed "update -r <tag>" some time ago, then removed - <tag> from the Repository files. "update -r <tag>" will delete a file - that doesn't contain <tag>. - - A way to fix this is to "cd" into your working directory and type: - - cvs update -A - - If you don't want the latest revisions on the Main (or Vendor) Branch, - then decide what Tag (normal or branch) you want and type: - - cvs update -r <the_tag_you_want> - - Another way to make a file disappear is to execute "update -D <date>" - where <date> is before the date stamped onto the first revision in the - RCS file. - - Last modified: _6/13/1997_ - - Category: /Past__Future_/ - - " Past & Future " - - Category: /Past__Future_/Bugs_and_Patches/ - - " + Bugs and Patches" - - 1. Why can't CVS handle deletion of directories? - - An oversight, probably. [[Fixed in a future release?]] - - Last modified: _6/13/1997_ - - 2. Why can't CVS handle the moving of sources from one place in the - - directory hierarchy to another? - - A "renaming database" has been proposed to track the history of - pathname changes in the Repository. A general solution is a difficult - problem. See 4B.8. - - Last modified: _6/13/1997_ - - 3. When I typed "cvs update -D <date>", why did it check out all - - sorts of ancient files from the Attic? Shouldn't it just create the - set of files and revisions that existed at that date? - - This seems to be a bug, but is really the lack of any obvious place to - store the date when a file is "removed". - - There are four ranges of dates that CVS has to deal with when trying - to determine what revision was available on <date>: - - Dates before the earliest revision in the file. - - Dates between any two revisions in the file. - - Dates between the latest revision in the file and the date when the - file was moved to the Attic by "commit". - - Dates after moving the file to the Attic. - - Since the date when a file is moved to the Attic is not stored - anywhere, CVS can't tell the difference between #3 and #4. To avoid - not producing a file that should exist in case #3, it produces - extraneous files in case #4. - - For the above reason, if you have removed files in the Attic, it is - better to use "-r <tag>, or even "-r HEAD" than to use a date spec. - - If you must use "-D <date>", then you should either archive and delete - Attic files (losing some past history) or construct your Makefiles to - work with an explicit list of files and let the old source files stay - in the working directory. The contents of the revision-controlled - Makefile can then be considered to contain deletion "information". - - Last modified: _6/13/1997_ - - 4. When I typed "cvs update -D <date>" in my branch, why did it screw up - all my files? - - Currently, the internal routine ("version_ts") that looks up info - about a file, overrides both the tag and date if *either* the tag or - date is specified on the command line. If only the date is specified, - it should not override a branch tag, but it does. - - In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only works - with the Main Branch and the Vendor Branch. - - [[Is this fixed in CVS 1.4? This is one item I didn't check.]] - - Last modified: _6/13/1997_ - - 5. When I executed "checkout" into an existing directory I got "No such - file or directory" errors. Why? - - Though the man page says that "checkout" turns into an "update -d" in - directories that already exist, it is referring to directories that - already exist *and* were created by CVS. - - When you try to run "checkout" on top of an existing directory - structure, some of which wasn't created by CVS, it will handle - directories and non-CVS files within directories already under CVS, - but it will display the above error on non-CVS files within non-CVS - directories. - - Last modified: _6/13/1997_ - - 6. Why does "update" send all output to the terminal after 26 files have - been updated? - - CVS uses the "tmpnam()" function to generate temporary file names. The - ANSI standard for the "tmpnam()" function says: - - "The tmpnam function generates a different string each time it is - called, up to TMP_MAX times. If it is called more than TMP_MAX times, - the behavior is implementation defined." - - Later it says that the value of "TMP_MAX shall be at least 25." - - On some platforms, the above specification is taken literally by - turning "at least 25" into "exactly 26" and by doing something foolish - (i.e. "implementation defined") after that. Some systems return the - same name repeatedly, which causes one form of trouble. Others return - NULL or garbage, which causes a different form of trouble. - - The broken systems appear to be cycling a single character through the - alphabet. SunOS cycles 3 characters through the alphabet, so it won't - cause trouble until 26 cubed or 17576 calls to "tmpnam()". - - Since CVS doesn't depend on the exact format of the tmp files, the - workaround is to provide a "tmpnam()" that doesn't have a limit on the - number of calls to it. - - Last modified: _6/13/1997_ - - 7. Why does the merge occasionally resurrect lines of code? - - The diff3 program provided by GNU diff version 1.15 has a bug that - occasionally causes text to come back from the dead. - - This is an old problem which you can avoid by upgrading to the latest - GNU "diffutils" package. If you were using GNU diff version 1.15 and - plan to upgrade to the latest GNU diff program, see the next question. - - Last modified: _6/13/1997_ - - 8. Why does the merge fail when my "rcsmerge" program is configured to use - GNU diff version 2.1 or later? - - A change in the overlap format was introduced in GNU diff3 between - versions 2.0 and 2.1 that causes RCS versions before 5.6.0.1 to fail - during a merge. - - To get consistent rcsmerge behavior, you have four choices: - - Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or 5.6. - If you want to use GNU diff 2.1 or later, you'll have to pick one of - the other three choices in this list. - - Grab RCS version 5.6.0.1 from an FSF archive and set the DIFF3_A - macro to '1' as it tells you to in the Makefile: - - #define DIFF3_A 1 - - Patch the RCS 5.6 source. Change line 84 in "merger.c" from: - - DIFF3, "-am", "-L", label[0], "-L", label[1], to DIFF3, "-amE", "-L", - label[0], "-L", "", "-L", label[1], - - Wait both for RCS version 5.7 to be released and for a new version - of CVS that can deal with it. - - Last modified: _6/13/1997_ - - Category: /Past__Future_/Contributors/ - - " + Contributors" - - 1. Who wrote CVS? - - Brian Berliner <berliner@sun.com> converted a collection of scripts - written by Dick Grune <dick@cs.vu.nl> into a C program, then added all - sorts of features. He continues to maintain CVS. - - Jeff Polk <polk@bsdi.com> wrote much of the code added between - revisions 1.2 and 1.3. Many others were involved at some level. - - david d zuhn <zoo@armadillo.com> fixed a number of bugs, added some of - the new features, reworked the whole thing to be more portable, and - provided much of the energy to push CVS 1.4 out the door. - - Jim Kingdon implemented CVS 1.5's remote repository access features, - fixed many bugs, and managed the release of version 1.5. - - Take a look at the README and the ChangeLog files in the CVS sources - for more contributors. - - Last modified: _6/13/1997_ - - 2. You didn't write all of this FAQ, did you? - - In the original hunt for questions to answer (performed in Jan/Feb, - 1993), I polled hundreds of people and I rephrased all sorts of text - found on the net. Between 2/93 and 10/93, I released about 20 - versions, with corrections and additions from the info-cvs mailing - list and private correspondence. - - Between 10/93 and 10/94 I extracted frequently asked questions from - the 1200 mail messages to the info-cvs mailing list, turned them into - focused questions and tried to answer them. - - 93/02/?? ~4000 lines 93/06/?? ~5000 lines 93/10/23 7839 lines 278K - 94/10/29 9856 lines 360K 95/05/09 9981 lines 365K - - Because there are so many posers of questions, I will list only those - who contribute answers or help significantly with the content and - structure of this document. - - If I used someone else's text verbatim, I mentioned it in the given - answer. The people whose email postings have added to this document or - who have added to my understanding are: - - Brian Berliner <berliner@sun.com>, CVS maintainer. Paul Eggert - <eggert@twinsun.com>, RCS maintainer. - - Gray Watson <gray@antaire.com> Per Cederqvist <ceder@signum.se> Pete - Clark <pclark@is.com> - - all of whom have sent me copies of their tutorials and local CVS - documentation. - - Additional contributors, who have sent me ideas, text, corrections and - support include (in alphabetical order): - - Per Abrahamsen <amanda@iesd.auc.dk> Donald Amby - <amby@mixcom.mixcom.com> Mark D Baushke <mdb@cisco.com> Jim Blandy - <jimb@cyclic.com> Tom Cunningham <tomc@bouwsma,sps.mot.com> Graydon - Dodson <grdodson@lexmark.com> Joe Drumgoole - <joed@splatter.demon.co.uk> Don Dwiggins <dwig@markv.com> Bryant - Eastham <bryant@ced.utah.edu> Dan Franklin <dan@diamond.bbn.com> - Michael Ganzberger <ganzbergermd@ES.net> Steve Harris - <vsh%etnibsd@uunet.uu.net> Erik van Linstee - <linstee@dutecaj.et.tudelft.nl> Jeffrey M Loomis <jml@world.std.com> - Barry Margolin <barmar@near.net> Mark K. Mellis <mkm@ncd.com> Chris - Moore <Chris.Moore@src.bae.co.uk> Gary Oberbrunner <garyo@avs.com> - Steve Turner <stevet@carrier.sps.mot.com> Dave Wolfe - <dwolfe@pffft.sps.mot.com> Dale Woolridge <dwoolridge@cid.aes.doe.ca> - - Please send corrections. If I forgot you, remind me and I'll add your - name to the list. - - Last modified: _6/13/1997_ - - Category: /Past__Future_/Development/ - - " + Development" - - 1. Where do I send bug reports? - - First make sure it is a bug. Talk to your friends, coworkers and - anyone you know who uses CVS. Search this FAQ for related issues. Then - test it carefully. Try out variations to narrow down the problem. Make - sure it is repeatable. Look for workarounds so you can report them. - - If you are still sure it's a bug and you tried to fix it, skip to the - next question. Otherwise, send a message to the info-cvs mailing list - containing one of the following: - - If you have a good repeatable case and you think you know what is - going on, then describe the problem in detail. Include a workaround if - you have one. - - If you have no idea what is going on, go ahead and send a question - to the info-cvs mailing list. Include any information you have - describing the symptoms. - - Last modified: _6/13/1997_ - - 2. Where do I send fixes and patches? - - First make sure the "fix" does something useful. Have someone review - your fix. Spend a bit of one person's time in a detailed analysis of - your vast idea before displaying a half-vast idea to hundreds of - people. - - If you tried to fix it and the patch is small, include the patch in - your message. Make sure the patch is based on the latest released - version of CVS. - - If you tried to fix it and the patch is large, you should think about - why it is so large. Did you add a generally useful feature, or did it - grow out of hand? - - If you still believe it is solid, produce a patch file using the CVS - commands "patch" or "diff -c". [[You *are* keeping CVS under CVS, - right?]] The patch should be based on the latest released version of - CVS. Then use the "cvsbug" program (provided with the CVS sources) to - send it to the CVS maintainers. A self-contained patch that provides a - single useful feature or correction might show up independently in the - patches directory of the FTP archive. - - If careful testing reveals an RCS bug rather than a CVS bug, you can - send bug reports to: rcs-bugs@cs.purdue.edu - - Last modified: _6/13/1997_ - - 3. Where do I send ideas for future development? - - If you have a bright idea, discuss it on the info-cvs mailing list. If - you have the time to implement something you can test, send the diffs - along too as described above. - - Last modified: _6/13/1997_ - - 4. What plans are there for new features? - - - -A "rename" or "per-directory" database has been bandied about on -the net for years. Many of the goals of the rename database have -been achieved by the so-called "death support" in recent versions of -CVS (such as 1.9). For more information on what may remain to be -done, see item #189 in the TODO file of a development version of CVS. - -CVS version 1.5 supports remote repository access, but Paul -Kunz has produced another version -(rCVS) that also runs remotely. Note that as far as I know there -are no advantages to rCVS over the remote CVS in CVS 1.5 and later, -and the rCVS user community has migrated to remote CVS. -rCVS is *not* a multisite CVS (see item #186 in TODO for more on -multisite). For more on rCVS, see - -ftp://ftp.slac.stanford.edu/software/rcvs - -kingdon@cyclic.com - - Last modified: _9/6/1997_ - - 5. I have some time and I'd like to help. What can I do for you? - - - You can review this document, correct errors and fill in any of - the incomplete sections. - - You can write scripts or CVS add-ons and make them available by - web/FTP/etc. - - You could work on the regression test suite (src/sanity.sh in the - CVS source distribution). - - You can write specs for new features, fix bugs, review the - documentation or . . . - - For more information, see the files HACKING and DEVEL-CVS in the - CVS source distribution or - http://www.cyclic.com/cyclic-pages/cvsdev.html - - kingdon@cyclic.com - - Last modified: _9/6/1997_ - - Category: /Past__Future_/Professional_Support/ - - " + Professional Support" - - 1. Doesn't Cygnus support CVS? - - - - - Cygnus is a company that supports free software such as the GCC - compiler. They have never sold support for CVS, however. They - do use CVS internally and have contributed much code to CVS over - the years (for which CVS users should be grateful). - - kingdon@cyclic.com - - Last modified: _9/6/1997_ - - 2. What is Cyclic Software doing with CVS? - - -Cyclic Software exists to provide support for CVS. For details such -as prices and what this covers, see http://www.cyclic.com or ask -info@cyclic.com. - -kingdon@cyclic.com - - Last modified: _9/6/1997_ - - Category: /User_Tasks_/ - - " User Tasks " - - Category: /User_Tasks_/Common_User_Tasks/ - - " + Common User Tasks" - - 1. What is the absolute minimum I have to do to edit a file? - - Tell your Repository Administrator to create a module covering the - directory or files you care about. You will be told that your module - name is <module>. Then type: - - cvs checkout <module> - cd <module> - emacs <file> # Isn't Emacs a synonym for edit? - cvs commit <file> - - If you don't use modules (in my opinion, a mistake), you can check out - a directory by substituting its relative path within the Repository - for <module> in the example above. - - To work on a single file, you'll have to change "cd <module>" to "cd - `dirname <module>`". - - Last modified: _6/13/1997_ - - 2. If I edit multiple files, must I type "commit" for each one? - - No. You can commit a list of files and directories, including relative - paths into multiple directories. You can also commit every modified - file in the current directory or in all directories and subdirectories - from your current directory downward. See 3D.2. - - Last modified: _6/13/1997_ - - 3. How do I get rid of the <module> directory that "checkout" created? - - Change your directory to be the same as when you executed the - "checkout" command that created <module>. - - If you want to get rid of the CVS control information, but leave the - files and directories, type: - - cvs release <module> - - If you want to obliterate the entire directory, type: - - cvs release -d <module> - - ("release -d" searches through the output of "cvs -n update" and - refuses to continue if the "update" command finds any modified files - or non-ignored foreign files. Foreign directories too.) - - If you don't care about keeping "history", or checking for modified - and foreign files, you can just remove the whole directory. That's "rm - -rf <module>" under Unix. - - Last modified: _6/13/1997_ - - 4. How do I find out what has changed since my last update? - - There are many ways to answer this. - - To find out what you've changed in your current working directory - since your last checkout, update or commit, type: - - cvs diff - - To find out what other people have added (to your branch) since you - last checked out or updated, type: - - cvs diff -r BASE -r HEAD - - To look at a revision history containing the comments for all changes, - you can use the "log" command. - - You can also use "history" to trace a wide variety of events. - - Last modified: _6/13/1997_ - - 5. I just created a new file. How do I add it to the Repository? - - The "update" command will mark files CVS doesn't know about in your - working directory with a '?' indicator. - - ? <file> - - To add <file> to the Repository, type: - - cvs add <file> - cvs commit <file> - - See 3A.[2-5] and 4C.8 for branch and merge considerations. - - Last modified: _6/13/1997_ - - 6. How do I merge changes made by others into my working directory? - - If you are asking about other branches, see Section 4C on "Branching". - You will have to use the "update -j" command. - - Retrieving changes made to the Repository on the *same* branch you are - working on is the main purpose of the "update" command. The "update" - command tries to merge work committed to the Repository by others - since you last executed "checkout", "update" or "commit" into your - working files. - - For a single file, there are six possible results when you type the - "update" command: - - If the file is lying in your working directory, but is not under - CVS, it will do nothing but print: - - ? <file> - - If neither you nor anyone else has committed changes to <file>, - since your last "checkout", "update" or "commit", "update" will print - nothing and do nothing. - - If you have made no changes to a working file, but you or others - have committed changes to the Repository since your last "checkout", - "update" or "commit" of this working file, CVS will remove your - working file and replace it with a copy of the latest revision of that - file in the Repository. It will print: - - U <file> - - You might want to examine the changes (using the CVS "diff" command) - to see if they mesh with your own in related files. - - If you have made changes to a working file, but no one has changed - your BASE revision (the revision you retrieved from the Repository in - your last "checkout", "update" or "commit"), "update" will print: - - M <file> - - Nothing changes. You were told that you have a modified file in your - directory. - - If you have made changes to your working file and you or others have - committed changes to the Repository, but in different sections of the - file, CVS will merge the changes stored in the Repository since your - last "checkout", "update" or "commit" into your working file. "update" - will print: - - RCS file: /Repository/module/<file> retrieving revision 1.X retrieving - revision 1.Y Merging differences between 1.X and 1.Y into <file> M - <file> - - If you execute "diff" before and after this step, you should see the - same output, since both the base file and your working file changed in - parallel. This is one of the few times the otherwise nonsensical - phrase "same difference" means something. - - If both you and those who committed files (since your last checkout, - update or commit) have made changes to the same section of a file, CVS - will merge the changes into your file as in #5 above, but it will - leave conflict indicators in the file. "update" will print: - - RCS file: /Repository/module/<file> retrieving revision 1.X retrieving - revision 1.Y Merging differences between 1.X and 1.Y into <file> - rcsmerge warning: overlaps during merge - cvs update: conflicts found in <file> - C <file> - - This is a "conflict". The file will contain markers surrounding the - overlapping text. The 'C' conflict indicator is sticky -- subsequent - "update" commands will continue to show a 'C' until you edit the file. - - You must examine the overlaps with care and resolve the problem by - analyzing how to retain the features of both changes. See 2D.7 and - 3P.6 for more details on conflict resolution. - - Last modified: _6/13/1997_ - - 7. How do I label a set of revisions so I can retrieve them later? - - To "tag" the BASE revisions (the ones you last checked out, updated, - or committed) you should "cd" to the head of the working directory you - want to tag and type: - - cvs tag <tag> - - It recursively walks through your working directory tagging the BASE - revisions of all files. - - To "tag" the latest revision on the Main branch in the Repository, you - can use the following from anywhere: (No "cd" is required -- it works - directly on the Repository.) - - cvs rtag <tag> <module> - - Last modified: _6/13/1997_ - - 8. How do I checkout an old release of a module, directory or file? - - Module names and directories are simply ways to name sets of files. - Once the names are determined, there are 6 ways to specify which - revision of a particular file to check out: - - By tag or symbolic name, via the "-r <tag>" option. - - By date, via the "-D <date>" option. - - By branch tag (a type of tag with a magic format), via the "-r - <branch_tag>" option. - - By date within a branch, via the "-r <branch_tag>:<date>" option. - - By an explicit branch revision number ("-r <rev>"), which refers to - the latest revision on the branch. This isn't really an "old" - revision, from the branch's perspective, but from the user's - perspective the whole branch might have been abandoned in the past. - - An explicit revision number: "-r <rev>" Though this works, it is - almost useless for more than one file. - - You type: - - cvs checkout <option-specified-above> <module> - cd <module> - - Last modified: _6/13/1997_ - - 9. What do I have to remember to do periodically? - - You should execute "cvs -n update" fairly often to keep track of what - you and others have changed. It won't change anything -- it will just - give you a report. - - Unless you are purposely delaying the inclusion of others' work, you - should execute "update" once in a while and resolve the conflicts. It - is not good to get too far out of sync with the rest of the developers - working on your branch. - - It is assumed that your system administrators have arranged for editor - backup and Unix temp files (#* and .#*) to be deleted after a few - weeks. But you might want to look around for anything else that is - ignored or hidden. Try "cvs -n update -I !" to see all the ignored - files. - - If you are the Repository Administrator, see 4B.16 on Administrator - responsibilities. - - Last modified: _6/13/1997_ - - Category: /User_Tasks_/General_Questions/ - - " + General Questions" - - 1. How do I see what CVS is trying to do? - - The '-t' option on the main "cvs" command will display every external - command (mostly RCS commands and file deletions) it executes. When - combined with the '-n' option, which prevents the execution of any - command that might modify a file, you can see what it will do before - you let it fly. The '-t' option will *not* display every internal - action, only calls to external programs. - - To see a harmless example, try typing: - - cvs -nt update - - Some systems offer a "trace" or "truss" command that will display all - system calls as they happen. This is a *very* low-level interface that - does not normally follow the execution of external commands, but it - can be useful. - - The most complete answer is to read the source, compile it with the - '-g' option and step through it under a debugger. - - Last modified: _6/13/1997_ - - 2. If I work with multiple modules, should I check them all out and commit - them occasionally? Is it OK to leave modules checked out? - - The simple answers are "Yes." - - There is no reason to remove working directories, other than to save - disk space. As long as you have committed the files you choose to make - public, your working directory is just like any other directory. - - CVS doesn't care whether you leave modules checked out or not. The - advantage of leaving them checked out is that you can quickly visit - them to make and commit changes. - - Last modified: _6/13/1997_ - - 3. What is a "sticky" tag? What makes it sticky? How do I loosen it? - - When you execute "update -r <tag>", CVS remembers the <tag>. It has - become "sticky" in the sense that until you change it or remove it, - the tag is remembered and used in references to the file as if you had - typed "-r <tag>" on the command line. - - It is most useful for a <branch_tag>, which is a sticky tag indicating - what branch you are working on. - - A revision number ("-r <rev-number>") or date ("-D <date>") can also - become sticky when they are specified on the command line. - - A sticky tag, revision or date remains until you specify another tag, - revision or date the same way. The "update -A" command moves back to - the Main branch, which has the side-effect of clearing all sticky - items on the updated files. - - The "checkout" command creates sticky tags, revisions and dates the - same way "update" does. - - Also, the '-k' option records a "sticky" keyword option that is used - in further "updates until "update -A" is specified. - - Last modified: _6/13/1997_ - - 4. How do I get an old revision without updating the "sticky tag"? - - Use the '-p' option to "pipe" data to standard output. The command - "update -p -r <tag/rev>" sends the selected revision to your standard - output (usually the terminal, unless redirected). The '-p' affects no - disk files, leaving a "sticky tag" unaltered and avoiding all other - side-effects of a normal "update". - - If you want to save the result, you can redirect "stdout" to a file - using your shell's redirection capability. In most shells the - following command works: - - cvs update -p -r <tag/rev> filename > diskfile - - Last modified: _6/13/1997_ - - 5. What operations disregard sticky tags? - - The functions that routinely disregard sticky tags are: - - Those that work directly on the Repository or its administrative - files: - - admin rtag log status remove history - - Those that take Tags or revisions as arguments and ignore everything - else: (They also never *set* a sticky tag.) - - rdiff import export - - The "release" command itself ignores sticky tags, but it calls "cvs - -n update" (which *does* pay attention to a sticky tag) to figure out - what inconsistencies exist in the working directory. If no - discrepancies exist between the files you originally checked out - (possibly marked by a sticky tag) and what is there now, "release -d" - will delete them all. - - The "tag" command works on the revision lying in the working - directory however it got there. That the revision lying there might - happen to have a sticky tag attached to it is not the "tag" command's - concern. - - The main function that *does* read and write sticky tags is the - "update" command. You can avoid referring to or changing the sticky - tag by using the '-p' option, which sends files to your terminal, - touching nothing else. - - The "checkout" command sets sticky tags when checking out a new module - and it acts like "update" when checking out a module into an existing - directory. - - The "diff" and "commit" commands use the sticky tags, unless - overridden on the command line. They do not set sticky tags. Note that - you can only "commit" to a file checked out with a sticky tag, if the - tag identifies a branch. - - There are really two types of sticky tags, one attached to individual - files (in the ./CVS/Entries file) and one attached to each directory - (in the ./CVS/Tag file). They can differ. - - The "add" command registers the desire to add a new file. If the - "directory tag" (./CVS/Tag) file exists at the time of the "add", the - value stored in ./CVS/Tag becomes the "sticky tag" on the new file. - The file doesn't exist in the Repository until you "commit" it, but - the ./CVS/Entries file holds the sticky tag name from the time of the - "add" forward. - - Last modified: _6/13/1997_ - - 6. Is there a way to avoid reverting my Emacs buffer after committing a - file? Is there a "cvs-mode" for Emacs? - - See Section 4F.1 - - Last modified: _6/13/1997_ - - 7. How does conflict resolution work? What *really* happens if two of us - change the same file? - - While editing files, there is no conflict. You are working on separate - copies of the file stored in the virtual "branch" represented by your - working directories. After one of you commits a file, the other may - not commit the same file until "update" has merged the earlier - committed changes into the later working file. - - For example, say you both check out rev 1.2 of <file> and make change - to your working files. Your coworker commits revision 1.3. When you - try to commit your file, CVS says: - - cvs commit: Up-to-date check failed for `<file>' - - You must merge your coworker's changes into your working file by - typing: - - cvs update <file> - - which will produce the output described in 2B.6. - - If a conflict occurs, the filename will be shown with a status of 'C'. - After you resolve any overlaps caused by the merging process, you may - then commit the file. See 3P.6 for info on "sticky conflicts". - - Even if you get a simple 'M', you should examine the differences - before committing the file. A smooth, error-free text merge is still - no indication that the file is in proper shape. Compile and test it at - least. - - The answer to two obvious questions is "Yes". - - Yes, the first one who commits avoids the merge. Later developers have - to merge the earlier changes into their working files before - committing the merged result. Depending on how difficult the merge is - and how important the contending projects are, the order of commits - and updates might have to be carefully staged. - - And yes, between the time you execute "update" and "commit" (while you - are fixing conflicts and testing the results) someone else may commit - another revision of <file>. You will have to execute "update" again to - merge the new work before committing. Most organizations don't have - this problem. If you do, you might consider splitting the file. Or - hiring a manager. - - Last modified: _6/13/1997_ - - 8. How can I tell who has a module checked out? - - If you "checkout" module names (not relative pathnames) and you use - the release command, the "history" command will display active - checkouts, who has them and where they were checked out. It is - advisory only; it can be circumvented by using the '-l' option on the - main "cvs" command. - - Last modified: _6/13/1997_ - - 9. Where did the .#<file>.1.3 file in my working directory come from? - - It was created during an "update" when CVS merged changes from the - Repository into your modified working file. - - It serves the same purpose as any "backup" file: saving your bacon - often enough to be worth retaining. It is invaluable in recovering - when things go wrong. - - Say Developers A (you) and B check out rev 1.3 of file <file>. You - both make changes -- different changes. B commits first, so <file>,v - in the Repository contains revisions up through 1.4. - - At this point, there are 5 (yes, five) versions of the file of - interest to you: - - Revision 1.3 (What you originally checked out.) - - Revision 1.4 (What you need from developer B.) - - Your old working file. (Before the update.) - - Your new working file. (After the merge caused by "update".) - - Revision 1.5 (Which you will commit shortly.) - - In the case where your working file was not modified, #1 and #3 will - be the same, as will #2 and #4. In this degenerate case, there is no - need to create #5. The following assumes that your working file was - modified. - - If the merge executed by the "update" caused no overlaps, and you - commit the file immediately, #4 and #5 will be the same. But you can - make arbitrary changes before committing, so the difference between #4 - and #5 might be more than just the correction of overlaps. In general, - though, you don't need #4 after a commit. - - But #3 (which is the one saved as ".#<file>.1.3") holds all of your - work, independent of B's work. It could represent a major effort that - you couldn't afford to lose. If you don't save it somewhere, the merge - makes #3 *disappear* under a potential blizzard of conflicts caused by - overlapping changes. - - I have been saved a few times, and others I support have been saved - hundreds of times, by the ability to "diff <original file> <original - file with only my work added>", which can be done in the example above - by the Unix shell command: - - cvs update -p -r 1.3 <file> | diff - .#<file>.1.3 - - The assumption is that the ".#" files will be useful far beyond the - "commit" point, but not forever. You are expected to run the "normal" - Unix cleanup script from "cron", which removes "#*" and ".#*" files - older than a some period chosen by your sysadmin, usually ranging from - 7 to 30 days. - - A question was raised about the need for #3 after #5 has been - committed, under the assumption that you won't commit files until - everything is exactly as you like them. - - This assumes perfect humans, which violates one of the Cardinal rules - of Software Engineering: Never assume any form of discipline on the - part of the users of software. If restrictions are not bound into the - software, then you, the toolsmith, have to arrange a recovery path. - - In other words, I've seen every possible variety of screwup you can - imagine in #5. There is no way to make assumptions about what "should" - happen. I've seen #5 filled with zeros because of NFS failures, I've - seen emacs core dumps that leave #5 in an unreasonable state, I've - seen a foolish developer uppercase the whole file (with his "undo" - size set low so he couldn't undo it) and decide that it would be less - work to play with the uppercased file than to blow it away and start - over. I've even seen committed files with conflict markers still in - them, a sure sign of carelessness. - - There are all sorts of scenarios where having #3 is incredibly useful. - You can move it back into place and try again. - - Last modified: _6/13/1997_ - - 10. What is this "ignore" business? What is it ignoring? - - The "update" and "import" commands use collections of Unix wildcards - to skip over files and directories matching any of those patterns. - - You may add to the built-in ignore list by adding lines of - whitespace-separated wildcards to the following places: (They are read - in this order.) - - In a file named "cvsignore" in $CVSROOT/CVSROOT. - - A Repository Administrator uses this to add site-specific files and - patterns to the built-in ignore list. - - In a file named ".cvsignore" in your home directory. - - For user-specific files. For example, if you use "__" as your default - junk file prefix, you can put "__*" in your .cvsignore file. - - People who play around exclusively in directory trees where the - Makefiles are generated by "imake" or "configure" might want to put - "Makefile" in their ignore list, since they are all generated and - usually don't end up in the Repository. - - In the CVSIGNORE environment variable. - - For session-specific files. - - Via the '-I' option on "import" or "update" commands. - - For this-command-only files. - - In a file named ".cvsignore" within each directory. - - The contents of a ".cvsignore" file in each directory is temporarily - added to the ignore list. This way you can ignore files that are - peculiar to that directory, such as executables and other generated - files without known wildcard patterns. - - In any of the places listed above, a single '!' character nulls out - the ignore list. A Repository administrator can use this to override, - rather than enhance, the built-in ignore list. A user can choose to - override the system-wide ignore list. For example, if you place "! *.o - *.a" in your .cvsignore file, only *.o *.a files, plus any files a - local-directory .cvsignore file, are ignored. - - A variant of the ignore-file scheme is used internally during - checkout. "Module names" found in the modules file (or on the - "checkout" command line) that begin with a '!' are ignored during - checkout. This is useful to permanently ignore (if the '!' path is in - the modules file) or temporarily ignore (if the '!' path is on the - command line) a sub-directory within a Repository hierarchy. For - example: - - cvs checkout !gnu/emacs/tests gnu/emacs - - would checkout the module (or relative path within $CVSROOT) named - "gnu/emacs", but ignore the "tests" directory within it. - - Last modified: _6/13/1997_ - - 11. Is there a way to set user-specific configuration options? - - User-specific configuration is available through use of a ".cvsrc" - file in your home directory. - - CVS searches the first column of your ~/.cvsrc file for the cvs - command name you invoked. If the command is found, the rest of the - line is treated like a set of command line options, stuffed into the - command line before the arguments you actually typed. - - For example, if you always want to see context diffs and you never - want to have to delete a file before you run "cvs remove", then you - should create a .cvsrc file containing the following: - - diff -c - remove -f - - which will add the given options to every invocation of the given - commands. - - [[The rest of this will be removed someday, when CVS changes.]] - - I would like to stop here with a comment that the command name to use - is the full, canonical one. But the command that the cvsrc support - uses is the string you typed on the command line, not the proper - command. So to get the full effect of the above example, you should - also add all the alternate command names: - - di -c - dif -c - rm -f - delete -f - - There are two other limitations that will probably be fixed when CVS - sprouts long option names: - - It only affects options made available on the command line. - - There is a limited number of short options. With long option names, - there is no problem. You can have as many long options as you like, - affecting anything that looks malleable. - - The existing command line options do not come in on/off pairs, so - there is no easy way to override your ~/.cvsrc configuration for a - single invocation of a command. - - Choosing a good set of long option pairs would fix this. - - Last modified: _6/13/1997_ - - 12. Is it safe to interrupt CVS using Control-C? - - It depends on what you mean by "safe". ("Ah," said Arthur, "this is - obviously some strange usage of the word *safe* that I wasn't - previously aware of." -- Hitchhiker's Guide to the Galaxy) - - You won't hurt the underlying RCS files and if you are executing a - command that only *reads* data, you will have no cleanup to do. - - But you may have to hit Control-C repeatedly to stop it. CVS uses the - Unix "system" routine which blocks signals in the CVS parent process. - A single Control-C during "system" will only halt the child process, - usually some form of RCS command. - - If you don't hit another Control-C while the CVS process has control, - it is likely to continue onto the next task assuming that the earlier - one did its job. It is not enough to hit two Control-C's. You might - simply kill two child processes and not interrupt CVS at all. - Depending on the speed of your processor, your terminal and your - fingers, you might have to hit dozens of Control-C's to stop the damn - thing. - - Executing a CVS command, such as "commit" or "tag" that writes to the - files is a different matter. - - Since CVS is not a full-fledged database, with what database people - call "commit points", merely stopping the process will not back out - the "transaction" and place you back in the starting blocks. CVS has - no concept of an "atomic" transaction or of "backtracking", which - means that a command can be half-executed. - - Hitting Control-C will usually leave lock files that you have to go - clean up in the Repository. - - Example1: - - If you interrupt a multi-file "commit" in the middle of - an RCS checkin, RCS will leave the file either fully - checked-in or in its original state. But CVS might have - been half-way through the list of files to commit. The - directory or module will be inconsistent. - - To recover, you must remove the lock files, then decide - whether you want to back out or finish the job. - - To back out, you'll have to apply the "admin -o" - command, very carefully, to remove the newly committed - revisions. This is usually a bad idea, but is - occasionally necessary. - - To finish, you can simply retype the same commit command. - CVS will figure out what files are still modified and - commit them. It helps that RCS doesn't leave a file in an - intermediate state. - - Example2: - - If you interrupt a multi-file "tag" command, you have a - problem similar, but not equivalent, to interrupting a - "commit". The RCS file will still be consistent, but - unlike "commit", which only *adds* to the RCS file, "tag" - can *move* a tag and it doesn't keep a history of what - revision a tag used to be attached to. - - Normally, you have little choice but to re-execute the - command and allow it to tag everything consistently. - - You might be able to recover by carefully re-applying the - tags via the "cvs admin -N" command, but you'll still have - to dig up from outside sources the information you use to - determine what tag was on what revision in what file. - the Repository, or by using the equivalent: "cvs admin". - - Halting a new "checkout" should cause no harm. If you don't want it, - "release" (or rm -rf) it. If you do want it, re-execute the command. A - repeated "checkout" from above a directory acts like a repeated - "update -d" within it. - - Halting "update" half-way will give you an unpredictable collection of - files and revisions. To continue, you can rerun the update and it - should move you forward into in a known state. To back out, you'll - have to examine the output from the first "update" command, take a - look at each file that was modified and reconstruct the previous state - by editing the ./CVS/Entries file and by using "cvs admin". Good Luck. - - Last modified: _6/13/1997_ - - 13. How do I turn off the "admin" command? - - In the current revision, you'd have to edit the source code. - - Last modified: _6/13/1997_ - - 14. How do I turn off the ability to disable history via "cvs -l"? - - In the current revision, you'd have to edit the source code. - - Last modified: _6/13/1997_ - - 15. How do I keep certain people from accessing certain directories? - - If you don't try to run CVS set[ug]id, you can use Unix groups and - permissions to limit access to the Repository. - - If you only want to limit "commit" commands, you can write a program - to put in the "commitinfo" file. In the "contrib" directory, there are - a few scripts that might help you out. - - Last modified: _6/13/1997_ - - Category: /User_Tasks_/Getting_Started/ - - " + Getting Started" - - 1. What is the first thing I have to know? - - Your organization has most likely assigned one or more persons to - understand, baby-sit and administer the CVS programs and the data - Repository. I call these persons Repository Administrators. They - should have set up a Repository and "imported" files into it. - - If you don't believe anyone has this responsibility, or you are just - testing CVS, then *you* are the Repository Administrator. - - If you are a normal user of CVS ask your Repository Administrator what - module you should check out. - - Then you can work. - - If you *are* the Repository Administrator, you will want to read - everything you can get your hands on, including this FAQ. Source - control issues can be difficult, especially when you get to branches - and release planning. Expect to feel stupid for a few days/weeks. - - No tool in the universe avoids the need for intelligent organization. - In other words, there are all sorts of related issues you will - probably have to learn. Don't expect to dive in without any - preparation, stuff your 300 Megabytes of sources into CVS and expect - to start working. If you don't prepare first, you will probably spend - a few sleepless nights. - - Last modified: _6/13/1997_ - - 2. Where do I work? - - Wherever you have disk space. That's one of the advantages of CVS: you - use the "checkout" command to copy files from the Repository to your - working directory, which can be anywhere you have the space. - - Your local group might have conventions for where to work. Ask your - peers. - - Last modified: _6/13/1997_ - - 3. What does CVS use from my environment? - - You must set two environment variables. Some shells share these - variables with local shell variables using a different syntax. You'll - have to learn how your shell handles them. - - Variable Value (or action) - --------- --------------------- - CVSROOT Absolute pathname of the head of your Repository. - - PATH Normally set to a list of ':'-separated directory - pathnames searched to find executables. You must - make sure "cvs" is in one of the directories. - - If your CVS was built with the RCSBIN directory set - to null (""), and you don't set the RCSBIN - variable mentioned below, then the RCS commands - also must be somewhere in your PATH. - - Optional variables: (Used if set, but ignored otherwise.) - - Variable Value (or action) - --------- --------------------- - CVSEDITOR The name of your favorite fast-start editor - program. You'll be kicked into your editor to - supply revision comments if you don't specify them - via -m "Log message" on the command line. - - EDITOR Used if CVSEDITOR doesn't exist. If EDITOR - doesn't exist, CVS uses a configured constant, - usually, "vi". - - CVSREAD Sets files to read-only on "checkout". - - RCSBIN Changes where CVS finds the RCS commands. - - CVSIGNORE Adds to the ignore list. See Section 2D. - - Other variables used by CVS that are normally set upon login: - - Variable Value (or action) - --------- --------------------- - LOGNAME Used to find the real user name. - - USER Used to find the real user name if no LOGNAME. - - HOME Used to determine your home directory, if set. - Otherwise LOGNAME/USER/getuid() are used to find - your home directory from the passwd file. - - TMPDIR Used during import. It might also be used if your - platform's version of mktemp(3) is unusual, or - you have changed the source to use tmpnam(3). - - Last modified: _6/13/1997_ - - 4. OK, I've been told that CVS is set up, my module is named "ralph" and I - have to start editing. What do I type? - - cd <where you have some space to work> - cvs checkout ralph - cd ralph - - And hack away. - - Last modified: _6/13/1997_ - - 5. I have been using RCS for a while. Can I convert to CVS without losing - my revision history? How about converting from SCCS? - - If you are asking such questions, you are not a mere user of CVS, but - one of its Administrators! You should take a look at Section 4A, - "Installing CVS" and Section 4B, "Setting up and Managing the - Repository". - - Last modified: _6/13/1997_ - - Category: /User_Tasks_/Less_Common_User_Tas/ - - " + Less Common User Tasks" - - 1. Can I create non-CVS sub-directories in my working directory? - - Yes. Unless the directory exists in the Repository, "update" will skip - over them and print a '?' the way it does for files you forgot to add. - You can avoid seeing the '?' by adding the name of the foreign - directory to the ./.cvsignore file, just ask you can do with files. - - If you explicitly mention a foreign directory on the "update" command - line, it will traverse the directory and waste a bit of time, but if - any directory or sub-directory lacks the ./CVS administrative - directory, CVS will print an error and abort. - - Last modified: _6/13/1997_ - - 2. How do I add new sub-directories to the Repository? - - The "add" command will work on directories. You type: - - mkdir <dir> - cvs add <dir> - - It will respond: - - Directory /Repos/<dir> added to the repository - - and will create both a matching directory in the Repository and a - ./CVS administrative directory within the local <dir> directory. - - Last modified: _6/13/1997_ - - 3. How do I remove a file I don't need? - - (See the questions in Section 4B on removing files from the - Repository.) - - You type: - - rm <file> - cvs remove <file> - - CVS registers the file for removal. To complete the removal, you must - type: - - cvs commit <file> - - CVS moves the file to the Attic associated with your working - directory. Each directory in the Repository stores its deleted files - in an Attic sub-directory. A normal "checkout" doesn't look in the - Attic, but if you specify a tag, a date or a revision, the "checkout" - (or "update") command will retrieve files from the Attic with that - tag, date or revision. - - Last modified: _6/13/1997_ - - 4. How do I rename a file? - - CVS does not offer a way to rename a file in a way that CVS can track - later. See Section 4B for more information. - - Here is the best (to some, the only acceptable) way to get the effect - of renaming, while preserving the change log: - - Copy the RCS (",v") file directly in the Repository. - - cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v - - By duplicating the file, you will preserve the change history and the - ability to retrieve earlier revisions of the old file via the "-r - <tag/rev>" or "-D <date>" options to "checkout" and "update". - - Remove the old file using CVS. - - cd <working-dir>/<odir> rm <ofile> - cvs remove <ofile> - cvs commit <ofile> - - This will move the <ofile> to the Attic associated with <odir>. - - Retrieve <nfile> and remove all the Tags from it. - - By stripping off all the old Tags, "checkout -r" and "update -r" won't - retrieve revisions Tagged before the renaming. - - cd <working-dir>/<ndir> - cvs update <nfile> - cvs log <nfile> # Save the list of Tags - cvs tag -d <tag1> <nfile> - cvs tag -d <tag2> <nfile> - . . . - - This technique can be used to rename files within one directory or - across different directories. You can apply this idea to directories - too, as long as you apply the above to each file and don't delete the - old directory. - - Of course, you have to change your build system (e.g. Makefile) in - your <working-dir> to know about the name change. - - Warning: Stripping the old tags from the copied file will allow "-r - <tag>" to do the right thing, but you will still have problems with - "-D <date>" because there is no place to store the "deletion time". - See 5B.3 for more details. - - Last modified: _6/13/1997_ - - 5. How do I make sure that all the files and directories in my working - directory are really in the Repository? - - A "cvs update", or "cvs -n update" (which won't modify your working - directory) will display foreign elements, which have no counterpart in - the Repository, preceded by a '?'. To register foreign directories, - you can use "cvs add". To register foreign files, you can use "cvs - add" followed by "cvs commit". - - You could also checkout your module, or the Repository directory - associated with your working directory, a second time into another - work area and compare it to your working directory using the (non-CVS) - "diff -r" command. - - By default many patterns of files are ignored. If you create a file - named "core" or a file ending in ".o", it is usually ignored. If you - really want to see all the files that aren't in the Repository, you - can use a special "ignore" pattern to say "ignore no files". Try - executing: (You may have to quote or backwhack (i.e. precede by '\') - the '!' in your shell.) - - cvs -n update -I ! - - The above command will display not only the normal modified, update - and conflict indicators ('M', 'U', and 'C' respectively) on files - within the Repository, but it will also display each file not in the - Repository preceded by a '?' character. - - The '-n' option will not allow "update" to alter your working - directory. - - Last modified: _6/13/1997_ - - 6. How do I create a branch? - - Type this in your working directory: - - cvs tag -b <branch_tag> - - and you will create a branch. No files have real branches in them yet, - but if you move onto the branch by typing: - - cvs update -r <branch_tag> - - and commit a file in the normal way: - - cvs commit <file> - - then a branch will be created in the underlying <file>,v file and the - new revision of <file> will appear only on that branch. - - See Section 4C, on Branching. - - Last modified: _6/13/1997_ - - 7. How do I modify the modules file? How about the other files in the - CVSROOT administrative area? - - A module named "modules" has been provided in the default modules - file, so you can type: - - cvs checkout modules - cd modules - - Another module named CVSROOT has been provided in the default modules - file, covering all the administrative files. Type: - - cvs checkout CVSROOT - cd CVSROOT - - Then you can edit your files, followed by: - - cvs commit - - If you start with the provided template for the "modules" file, the - CVSROOT and the "modules" module will have the "mkmodules" program as - a "commit helper". After a file is committed to such a module, - "mkmodules" will convert a number of standard files (See 4B.2) in the - CVSROOT directory inside the Repository into a form that is usable by - CVS. - - Last modified: _6/13/1997_ - - 8. How do I split a file into pieces, retaining revision histories? - - If you and a coworker find yourselves repeatedly committing the same - file, but never for changes in the same area of the file, you might - want to split the file into two or more pieces. If you are both - changing the same section of code, splitting the file is of no use. - You should talk to each other instead. - - If you decide to split the file, here's a suggestion. In many ways, it - is similar to multiple "renamings" as described in 2C.4 above. - - Say you want to split , which already in the Repository, into three - pieces, , and . - - Copy the RCS (",v") files directly in the Repository, creating the - new files, then bring readable copies of the new files into the - working directory via "update". - - cp $CVSROOT//,v $CVSROOT//,v cp $CVSROOT//,v $CVSROOT//,v - cvs update - - Then remove all the from the new files, either using: - - cvs log # Save the list of - cvs tag -d - cvs tag -d - . . . - - (eivind@freebsd.org) or using the following little script to - autmatically remove the tags directly from the repository files: - -#!/bin/sh -for file in $* -do - TAGS=`rlog $file | awk '/^symbolic names:/,/^keyword subst/' | awk 'BEG -IN {FS=":"} /^\t/ {print $1}'` - echo The tags in $file are - echo $TAGS - echo Is it OK to remove these? - read confirm - if [ "$confirm" = "y" -o "$confirm" = "yes" ] - then - for tag in $TAGS - do - echo Removing $file:$tag - rcs -n$tag $file - done - fi -done - - Edit each file until it has the data you want in it. This is a - hand-editing job, not something CVS can handle. Then commit all the - files. - - [From experience, I'd suggest making sure that only one copy of each - line of code exists among the three files, except for "include" - statements, which must be duplicated. And make sure the code - compiles.] - - emacs - cvs commit - - As in the "rename" case, by duplicating the files, you'll preserve the - change history and the ability to retrieve earlier revisions. - - Of course, you have to alter your build system (e.g. Makefiles) to - take the new names and the change in contents into account. - - Last modified: _3/11/1998_ - - Category: /What_is_CVS_/ - - " What is CVS? " - - Category: /What_is_CVS_/How_does_CVS_differ_/ - - " + How does CVS differ from other, similar software?" - - 1. How does CVS differ from RCS? - - CVS uses RCS to do much of its work and absolutely all the work of - changing the underlying RCS files in the Repository. - - RCS comprises a set of programs designed to keep track of changes to - individual files. Of course, it also allows you to refer to multiple - files on the command line, but they are handled by iterating over - individual files. There is no pretense of coordinated interaction - among groups of files. - - CVS's main intent is to provide a set of grouping functions that allow - you to treat a collection of RCS files as a single object. Of course, - CVS also has to do a lot of iteration, but it tries its best to hide - that it is doing so. In addition, CVS has some truly group-oriented - facets, such as the modules file and the CVS administrative files that - refer to a whole directory or module. - - One group aspect that can be a bit confusing is that a CVS branch is - not the same as an RCS branch. To support a CVS branch, CVS uses - "tags" (what RCS calls "symbols") and some local state, in addition to - RCS branches. - - Other features offered by CVS that are not supported directly by RCS - are - - Automatic determination of the state of a file, (e.g. modified, - up-to-date with the Repository, already tagged with the same string, - etc.) which helps in limiting the amount of displayed text you have to - wade through to figure out what changed and what to do next. - - A copy-modify-merge scheme that avoids locking the files and allows - simultaneous development on a single file. - - Serialization of commits. CVS requires you to merge all changes - committed (via "update") since you checked out your working copy of - the file. Although it is still possible to commit a file filled with - old data, it is less likely than when using raw RCS. - - Relatively easy merging of releases from external Vendors. - - Last modified: _6/13/1997_ - - 2. How does CVS differ from SCCS? - - SCCS is much closer to RCS than to CVS, so some of the previous entry - applies. - - You might want to take a look at Walter Tichy's papers on RCS, which - are referred to in the RCS man pages. - - [[More info here?]] - - Last modified: _6/13/1997_ - - 3. How does CVS differ from ClearCase? - - ClearCase is a distributed client-server version control system. - ClearCase is a variant DSEE tools, formerly available on Apollo - platforms. The ClearCase tool set includes a few X-based interface - tools, a command-line interface, and C programmer API. It is currently - available on Sun, HP, SGI and OSF/1 platforms. - - ClearCase uses a special Unix filesystem type, called "mvfs" for - "multi-version file system". Conceptually, mvfs adds another dimension - to a regular Unix filesystem. The new axis is used to store the - different versions of files and to provide a tree-hierarchical view of - a collection of objects that might be scattered across any number of - separate hosts on your local network. - - Each user acquires a "view" into the file database by creating a - special mvfs mount point on their machine. Each view has a - "configuration spec" containing a set of selection rules that specify - the particular version of each file to make visible in that view. You - can think of a "view" as a work area in CVS, except that the files - don't really exist on your local disk until you modify them. This - technique conserves disk space because it doesn't keep private copies - of read-only files. - - Another advantage is that a view is "transparent" in the sense that - all of the files in a "view" appear to be regular Unix files to other - tools and Unix system calls. An extended naming convention allows - access to particular versions of a file directly: - "test.cc@@/main/bugfix/3" identifies the third version of test.c on - the bugfix branch. - - ClearCase supports both the copy-modify-merge model of CVS (by using - what are called "unreserved checkouts" and the checkin/checkout - development model with file locking. Directories are - version-controlled objects as well as files. A graphical merge tool is - provided. Like RCS, ClearCase supports branches, symbolic tags, and - delta compression. ASCII as well as binary files are supported, and - converters from RCS, SCCS, DSEE formats are also included. - - A make-compatible build facility is provided that can identify common - object code and share it among developers. A build auditing feature - automatically records file dependencies by tracking every file that is - opened when producing a derived object, thus making explicit - dependency lists unnecessary. Pre- and post-event triggers are - available for most ClearCase operations to invoke user programs or - shell scripts. User-defined attributes can be assigned to any version - or object. Hyper-links between version controlled objects can record - their relationship. - - For more information, contact: - - Atria Software, Inc. 24 Prime Park Way Natick, MA 01760 info@atria.com - - (508) 650-1193 (phone) (508) 650-1196 (fax) - - Originally contributed by Steve Turner - Edited by the author of this FAQ. - - Last modified: _6/13/1997_ - - 4. How does CVS differ from TeamWare/SparcWorks? - - TeamWare is a configuration management tool from Sun Microsystems, a - part of SparcWorks. It uses the same copy and merge model as CVS. The - central abstraction is a workspace, which corresponds to either a CVS - branch or a checked out module. TeamWare allows you to manipulate - workspaces directly, including moving and merging code between - workspaces. You can put your workspace on tape and continue to work - with it at home, just like you can with CVS. TeamWare is built upon - and compatible with SCCS. - - TeamWare provides both a command line interface and a graphical - interface. The CodeManager tool will display the project as a tree of - workspaces, and allows you to manipulate them with drag and drop. The - other tools are VersionTool that displays and manipulates a dag with a - version history of a single file, CheckPoint that will create symbolic - tags, MakeTool, a make compatible tool with a GUI, and FileMerge which - will interactively merge files when needed (like emerge for emacs). If - you have a sun, you can try /usr/old/mergetool for an old SunView - version of FileMerge. - - Email: sunprosig@sun.com - - Originally extracted from TeamWare - Marketing literature by Per Abrahamsen. - Edited by the author of this FAQ. - - For more information, contact: - - SunExpress, Inc. P.O. Box 4426 Bridgeton, MO 63044-9863 (800)873-7869 - - Last modified: _6/13/1997_ - - 5. How does CVS differ from Aegis? - - Aegis appears to be a policy-setting tool that allows you to use other - sub-programs (make, RCS, etc.) to implement pieces of the imposed - policy. - - The initial document seems to say that most Unix tools are inadequate - for use under Aegis. - - It is not really similar to CVS and requires a different mindset. - - [[Need more info here.]] - - Last modified: _6/13/1997_ - - 6. How does CVS differ from Shapetools? - - Shapetools includes a build mechanism (called Shape, not surprisingly) - that is aware of the version mechanism, and some dependency tracking. - It is based on a file system extension called Attributed File System, - which allows arbitrary-sized "attributes" to be associated with a - file. Files are version controlled in a manner similar to RCS. - Configurations are managed through the Shapefile, an extension of the - Makefile syntax and functionality. Shape includes version selection - rules to allow sophisticated selection of component versions in a - build. - - Shapetools' concurrency control is pessimistic, in contrast to that of - CVS. Also, there's very limited support for branching and merging. It - has a built-in policy for transitioning a system from initial - development to production. - - Contributed by Don Dwiggins - - Last modified: _6/13/1997_ - - 7. How does CVS differ from TeamNet? - - TeamNet is a configuration management tool from TeamOne. - - For more information, contact: - - TeamOne 710 Lakeway Drive, Ste 100 Sunnyvale, CA 94086 (800) 442-6650 - - Contributed by Steve Turner - - Last modified: _6/13/1997_ - - 8. How does CVS differ from ProFrame? - - ProFrame is a new system integration framework from IBM. ProFrame is - compliant with the CFI (CAD Framework Initiative) industry standards, - including the Scheme extension language. - - ProFrame consists of three major components: (1) the Process Manager - that automates your local design methodology (2) the Design Data - Manager handles configuration management, and (3) Inter-tool - Communication to provide a communication path among tools running on - heterogeneous servers. - - The Design Data Manager(2) is probably the appropriate component to - compare to CVS. The Design Data Manager provides version control with - checkin/checkout capability, configuration management, and data - dependency tracking. A graphical data selection interface is provided. - Using this interface, you may create and manipulate objects and - hierarchy structures, view the revision history for an object, and - view and assign attributes to a design object. - - The ProFrame server currently runs only on RS6000, but clients may be - a wide variety of Unix platforms. Contact IBM for the latest platform - information. - - For more information, contact: - - IBM EDA Marketing and Sales P.O. Box 950, M/S P121 Poughkeepsie, NY - 12602 (800) 332-0066 - - Contributed by Steve Turner - [extracted from the ProFrame 1.1.0 datasheet] - - Last modified: _6/13/1997_ - - 9. How does CVS differ from CaseWare/CM? - - CaseWare/CM is a software configuration management product from - CaseWare, Inc. CaseWare/CM may be customized to support a wide variety - of methodologies, including various phases of the software lifecycle, - and different access rights for users. - - A GUI is provided to view version histories and configurations. A - merge tools is also included. CaseWare supports type-specific - lifecycles, which allows different types of files to move through - different lifecycles. Also provided is a build facility to support - automatic dependency analysis, parallel, distributed, and remote - builds, and variant releases. - - CaseWare/CM has been integrated with other CASE tools, including - FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP SoftBench, and - Software Through Pictures. CaseWare also offers CaseWare/PT, a problem - tracking system to integrate change requests with configuration - management. - - Multiple vendors and operating systems are supported. - - For more information, contact: - - CaseWare, Inc. 108 Pacifica, 2nd Floor Irvine, CA 92718-3332 (714) - 453-2200 (phone) (714) 453-2276 (fax) - - Contributed by Steve Turner - [extracted from the CaseWare/CM data sheet] - - Last modified: _6/13/1997_ - - 10. How does CVS differ from SABLIME? - - Produced by AT&T. Sablime uses SCCS as the underlying source code - control system. It uses some other control system (called sbcs I - think) for managing binary files. It uses lock, edit, comit, unlock - mechanism. It has a motif based GUI and curses based GUI (that works - only with ksh, not tcsh, or bash) to do more common tasks. It has even - a command line interface. - - Changing source happens as a result of MR. A testing person or a - developer assigns an MR (modification request) to a group of people. - They are allowed to take out files under that MR and change them and - check them back in. You can set up dependencies between and MR and do - release management to say "I want the sources to include these MRs" - etc. It is a reasonably good maintanance system. It is bit heavy - weight though, and the interface is not too polished and does not work - on windows (though that may have changed). rama@savera.com - - Last modified: _7/30/1998_ - - 11. How does CVS differ from PVCS? - - PVCS works on single files like RCS and SCCS, CVS works on complete - subsystems. PVCS has a make utility (called a configuration builder), - CVS does not. PVCS has a GUI interface for Unix, DOS, OS/2, and MS - Windows. - - Intersolv, Inc. - 1700 NW 167th Place - OR 97006 - - Contributed by Per Abrahamsen - [Extracted from Intersolv Marketing literature.] - - Last modified: _6/13/1997_ - - 12. How does CVS differ from CMVC? - - CMVC is an IBM Configuration Management and Version Control system. - (Though I'm not certain that's the right acronym expansion.) It runs - on Suns, HPs, RS6000s, OS/2 and Windows. - - Other than revision control, it apparently has features to manage - releases, bug tracking and the connection between alterations and - reported bugs and feature requests. It is a client/server system, - based on a choice of commercial Relational Database systems, and it - provides a Motif or command line interface. - - Unlike CVS, it uses a strict locking protocol to serialize source code - alterations. - - Last modified: _6/13/1997_ - - Category: /What_is_CVS_/What_do_you_mean_by_/ - - " + What do you mean by . . .? (Definitions)" - - 1. What are "The Repository", "$CVSROOT" and "CVSROOT"? - - The Repository is a directory tree containing the CVS administrative - files and all the RCS files that constitute "imported" or "committed" - work. The Repository is kept in a shared area, separate from the - working areas of all developers. - - Users of CVS must set their "CVSROOT" environment variable to the - absolute pathname of the head of the Repository. Most command line - interpreters replace an instance of "$CVSROOT" with the value of the - "CVSROOT" environment variable. By analogy, in this document - "$CVSROOT" is used as shorthand for "the absolute pathname of the - directory at the head of the Repository". - - One of the things found in $CVSROOT is a directory named CVSROOT. It - contains all the "state", the administrative files, that CVS needs - during execution. The "modules", "history", "commitinfo", "loginfo" - and other files can be found there. See 4B.2 for more information - about CVSROOT files. - - Last modified: _6/13/1997_ - - 2. What is an RCS file? - - An RCS file is a text file containing the source text and the revision - history for all committed revisions of a source file. It is stored - separately from the working files, in a directory hierarchy, called - the Repository. - - RCS is the "Revision Control System" that CVS uses to manage - individual files. RCS file names normally end in ",v", but that can be - altered (via the RCS -x option) to conform to file naming standards on - platforms with unusual filename limitations. - - Last modified: _6/13/1997_ - - 3. What is a working file? - - A working file is a disk file containing a checked-out copy of a - source file that earlier had been placed under CVS. If the working - file has been edited, the changes since the last committed revision - are invisible to other users of CVS. - - Last modified: _6/13/1997_ - - 4. What is a working directory (or working area)? - - A working directory is the place where you work and the place from - which you "commit" files. - - The "checkout" command creates a tree of working directories, filling - them with working files. Each working directory contains a - sub-directory named ./CVS containing three administrative files, which - are created by "checkout" and are always present: - - ./CVS/Entries - contains information about working files. - - ./CVS/Repository - contains the location of the directory within the - Repository that was used to create the working directory. - - ./CVS/Root - contains the value of $CVSROOT at the time you created - the working directory. - - Other files may also appear in ./CVS depending on the state of your - working directory: - - ./CVS/Tag - contains the "sticky tag" associated with the whole - directory. See 3A.2 for its main purpose. - [Created by "checkout" or "update" when using "-r <tag>".] - [Deleted by "checkout" or "update" when using '-A'.] - - ./CVS/Entries.Static - contains a fixed list of working files. If this file - exists, an "update" doesn't automatically bring newly - added files out of the Repository. - [Created and maintained by hand.] - - ./CVS/Checkin.prog - contains a program to run whenever anything in the - working directory is committed. - [Created by checkout if "-i <prog>" appears in the - modules file for the checked-out module.] - - ./CVS/Update.prog - contains a program to run whenever anything in the - working directory is updated. - [Created by checkout if "-u <prog>" appears in the - modules file for the checked-out module.] - - ./CVS/<file>,p ./CVS/<file>,t - contain (possibly zero-length) state information about an - "add" that has not been committed. - [Created by "add".] - [Deleted by "commit" or "remove".] - - Last modified: _6/13/1997_ - - 5. What is "checking out"? - - "Checking out" is the act of using the "checkout" command to copy a - particular revision from a set of RCS files into your working area. - You normally execute "checkout" only once per working directory (or - tree of working directories), maintaining them thereafter with the - "update" command. - - See section 3C on the "checkout" command. - - Last modified: _6/13/1997_ - - 6. What is a revision? - - A "revision" is a version of a file that was "committed" ("checked - in", in RCS terms) some time in the past. CVS (and RCS) can retrieve - any file that was committed by specifying its revision number or its - "tag" ("symbolic name", in RCS terms). - - In CVS, a "tag" is more useful than a revision number. It usually - marks a milestone in development represented by different revision - numbers in different files, all available as one "tagged" collection. - - Sometimes the word "revision" is used as shorthand for "the file you - get if you retrieve (via "checkout" or "update") the given revision - from the Repository." - - Last modified: _6/13/1997_ - - 7. What is a "Tag"? - - A "Tag" is a symbolic name, a synonym or alias for a particular - revision number in a file. The CVS "tag" command places the same "Tag" - on all files in a working directory, allowing you to retrieve those - files by name in the future. - - The CVS "Tag" is implemented by applying RCS "symbols" to each - individual file. The Tags on a file (or collection of files) may be - displayed using the "log" command. - - Last modified: _6/13/1997_ - - 8. What are "HEAD" and "BASE"? - - HEAD and BASE are built-in tags that don't show up in the "log" or - "status" listings. They are interpreted directly by CVS. - - "HEAD" refers to the latest revision on the current branch in the - Repository. The current branch is either the main line of development, - or a branch in development created by placing a branch tag on a set of - files and checking out that branch. - - "BASE" refers to the revision on the current branch you last checked - out, updated, or committed. If you have not modified your working - file, "BASE" is the committed revision matching it. - - Most of the time BASE and HEAD refer to the same revision. They can - become different in two ways: - - Someone else changed HEAD by committing a new revision of your file - to the Repository. You can pull BASE up to equal HEAD by executing - "update". - - You moved BASE backward by executing "checkout" or "update" with the - option "-r <rev/tag>" or "-D <date>". CVS records a sticky tag and - moves your files to the specified earlier revision. You can clear the - sticky tag and pull BASE up to equal HEAD again by executing "update - -A". - - Last modified: _6/13/1997_ - - 9. What is a Branch? - - In general, a branch is any mechanism that allows one or more - developers to modify a file without affecting anyone other than those - working on the same branch. - - There are four kinds of "branch" CVS can manage: - - The Vendor Branch. - - A single vendor branch is supported. The "import" command takes a - sequence of releases from a source code vendor (called a "vendor" even - if no money is involved), placing them on a special "Vendor" branch. - The Vendor branch is considered part of the "Main line" of - development, though it must be merged into locally modified files on - the RCS Main branch before the "import" is complete. - - See Section 3H ("import"). - - Your Working directory. - - A checked-out working directory, can be treated like a private branch. - No one but you can touch your files. You have complete control over - when you include work committed by others. However, you can't commit - or tag intermediate versions of your work. - - A Development branch. - - A group of developers can share changes among the group, without - affecting the Main line of development, by creating a branch. Only - those who have checked-out the branch see the changes committed to - that branch. This kind of branch is usually temporary, collapsing - (i.e. merge and forget) into the Main line when the project requiring - the branch is completed. - - You can also create a private branch of this type, allowing an - individual to commit (and tag) intermediate revisions without changing - the Main line. It should be managed exactly like a Development Branch - -- collapsed into the Main line (or its parent branch, if that is not - the Main Branch) and forgotten when the work is done. - - A Release branch. - - At release time, a branch should be created marking what was released. - Later, small changes (sometimes called "patches") can be made to the - release without including everything else on the Main line of - development. You avoid forcing the customer to accept new, possibly - untested, features added since the release. This is also the way to - correct bugs found during testing in an environment where other - developers have continued to commit to the Main line while you are - testing and packaging the release. - - Although the internal format of this type of branch (branch tag and - RCS branches) is the same as in a development branch, its purpose and - the way it is managed are different. The major difference is that a - Release branch is normally Permanent. Once you let a release out the - door to customers, or to the next stage of whatever process you are - using, you should retain forever the branch marking that release. - - Since the branch is permanent, you cannot incorporate the branch fixes - into the Main line by "collapsing" (merging and forgetting) the - release branch. For large changes to many files on the release branch, - you will have to perform a branch merge using "update -j <rev> -j - <rev>". (See 4C.7) - - The most common way to merge small changes back into Main line - development is to make the change in both places simultaneously. This - is faster than trying to perform a selective merge. - - See 1D.12 (merges) and Section 4C, on Branching for more info. - - Last modified: _6/13/1997_ - - 10. What is "the trunk"? - - Another name for the RCS Main Branch. The RCS Main Branch is related, - but not equivalent, to both the CVS Main branch and what developers - consider to be the Main line of development. See 3H.3 and Section 4C - on Branching. - - Last modified: _6/13/1997_ - - 11. What is a module? - - In essence, a module is a name you hand to the "checkout" command to - retrieve one or more files to work on. It was originally intended to - be a simple, unique name in the "modules" file attached to a directory - or a subset of files within a directory. - - The module idea is now a somewhat slippery concept that can be defined - in two different ways: - * A module is an argument to "checkout". There are three types: - 1. An entry in the modules file. A "module" name as described in - 'B.' below. - 2. A relative path to a directory or file in the Repository. - 3. A mixed-mode string of "modulename/relative-path". Everything - up to the first slash ('/') is looked up as a module. The - relative path is appended to the directory associated with - the module name and the resulting path is checked out as in - #2 above. - * A module is a unique (within the file) character string in the - first column of the modules file. There are five types: - 1. A name for a directory within the Repository that allows you - to ignore the parent directories above it. - Example: - emacs gnu/emacs - 2. A name for a subset of the files within such a directory. - Example: - ls unix/bin Makefile ls.c - The 2nd through Nth strings in the above can be files, - directories or module substitutions. No relative paths. - A module substitution occurs when you use a '&module-name' - reference. The module-name referred to is logically - substituted for the '&module-name' string. - 3. A relative pathname to a directory within the Repository - which, when checked out, creates an image of part of the - Repository structure in your current directory. - Example: - gnu/emacs -o /bin/emacs.helper gnu/emacs - The files checked out are exactly the same as the files - "checkout" would retrieve if the path weren't even in the - modules file. The only reason to put this kind of relative - pathname into the modules file is to hook one of the helper - functions onto it. - 4. A relative pathname to a single file within the Repository - which, when checked out, creates something you probably don't - want: It creates a directory by the name of the file and puts - the file in it. - Example: - gnu/emacs/Makefile -o /bin/emacs.helper gnu/emacs Makefile - The file checked out is the same as what you would get if you - handed the relative pathname to the "checkout" command. But - it puts it in a strange place. The only reason to do this is - to hook a helper function onto a specific file name. - 5. An alias consisting of a list of any of the above, including - other aliases, plus exceptions. - Example: - my_work -a emacs !emacs/tests gnu/bison unix/bin/ls.c - The exception "!emacs/test" above is functionally equivalent - to specifying "!emacs/tests" on the "checkout" command line. - - Another way to look at it is that the modules file is simply another - way to "name" files. The hierarchical directory structure provides - another. You should use whatever turns out to be simplest for your - development group. - - See 4G.2 for some specific ideas about how to use the modules file. - - Last modified: _11/12/1997_ - - 12. What does "merge" mean? - - A merge is a way of combining changes made in two independent copies - of a common starting file. Checking out an RCS revision produces a - file, so for the purposes of a merge "file" and "revision" are - equivalent. So, we can say there are always three "files" involved in - a merge: - - The original, starting, "base" or "branch point" file. - - A copy of the base file modified in one way. - - Another copy of the base file modified in a different way. - - Humans aren't very good at handling three things at once, so the - terminology dealing with merges can become strained. One way to think - about it is that all merges are performed by inserting the difference - between a base revision and a later revision (committed by someone - else) into your working file. Both the "later" revision and your - working file are presumed to have started life as a copy of the "base" - revision. - - In CVS, there are three main types of "merge": - - The "update" command automatically merges revisions committed by - others into your working file. In this case, the three files involved - in the merge are: - - Base: The revision you originally checked out. Later: A revision - committed onto the current branch after you checked out the Base - revision. Working: Your working file. The one lying in the working - directory containing changes you have made. - - The "update -j <branch_tag> {optional files}" command merges changes - made on the given branch into your working files, which is presumed to - be on the Main line of development. - - See 4C.6 - - The "update -j <rev> -j <rev> {optional files}" command merges the - difference between two specified revisions into files in your working - directory. The two revisions <rev> are usually on the same branch and, - when updating multiple files, they are most useful when they are Tag - names rather than numeric revisions. - - See 4C.7 - - Last modified: _6/13/1997_ - - Category: /What_is_CVS_/What_is_CVS_Whats_it/ - - " + What is CVS? What's it for? Why CVS?" - - 1. What does CVS stand for? Can you describe it in one sentence? - - "CVS" is an acronym for the "Concurrent Versions System". - - CVS is a "Source Control" or "Revision Control" tool designed to keep - track of source changes made by groups of developers working on the - same files, allowing them to stay in sync with each other as each - individual chooses. - - Last modified: _6/13/1997_ - - 2. What is CVS for? What does it do for me? - - CVS is used to keep track of collections of files in a shared - directory called "The Repository". Each collection of files can be - given a "module" name, which is used to "checkout" that collection. - - After checkout, files can be modified (using your favorite editor), - "committed" back into the Repository and compared against earlier - revisions. Collections of files can be "tagged" with a symbolic name - for later retrieval. - - You can add new files, remove files you no longer want, ask for - information about sets of files in three different ways, produce patch - "diffs" from a base revision and merge the committed changes of other - developers into your working files. - - Last modified: _6/13/1997_ - - 3. How does CVS work? - - CVS saves its version-control information in RCS files stored in a - directory hierarchy, called the Repository, which is separate from the - user's working directory. - - Files in the Repository are stored in a format dictated by the RCS - commands CVS uses to do much of its real work. RCS files are standard - byte-stream files with an internal format described by keywords stored - in the files themselves. - - To begin work, you execute a "checkout" command, handing it a module - name or directory path (relative to the $CVSROOT variable) you want to - work on. CVS copies the latest revision of each file in the specified - module or directory out of the Repository and into a directory tree - created in your current directory. You may specify a particular branch - to work on by symbolic name if you don't want to work on the default - (main or trunk) branch. - - You may then modify files in the new directory tree, build them into - output files and test the results. When you want to make your changes - available to other developers, you "commit" them back into the - Repository. - - Other developers can check out the same files at the same time. To - merge the committed work of others into your working files you use the - "update" command. When your merged files build and test correctly, you - may commit the merged result. This method is referred to as - "copy-modify-merge", which does not require locks on the source files. - - At any time, usually at some milestone, you can "tag" the committed - files, producing a symbolic name that can be handed to a future - "checkout" command. A special form of "tag" produces a branch in - development, as usually happens at "release" time. - - When you no longer plan to modify or refer to your local copy of the - files, they can be removed. - - Last modified: _6/13/1997_ - - 4. What is CVS useful for? - - CVS is intended to handle source control for files in three major - situations: - - Multiple developers working on the same files. - - The major advantage of using CVS over the simpler tools like RCS or - SCCS is that it allows multiple developers to work on the same sources - at the same time. - - The shared Repository provides a rendezvous for committed sources that - allows developers a fair amount of flexibility in how often to publish - (via the "commit" command) changes or include work committed by others - (via the "update" command). - - Tracking a stream of releases from a source vendor. - - If you are making changes to sources distributed by someone else, the - CVS feature, called the Vendor Branch, allows you to combine local - modifications with repeated vendor releases. - - I have found this most useful when dealing with sources from three - major classes of source vendor: - - Large companies who send you tapes full of the latest release (e.g. - Unix OS vendors, database companies). - - Public Domain software which *always* requires work. - - Pseudo-Public sources which may require work. (e.g. GNU programs, X, - CVS itself, etc.) - - Branching development. - - Aside from the "Vendor Branch", there are three kinds of "branches in - development" that CVS can support: - - Your working directory can be treated as a private branch. - - A Development branch can be shared by one or more developers. - - At release time, a branch is usually created for bug fixes. - - (See 1D.9 and Section 4C for more info on branches.) - - CVS's branch support is a bit primitive, but it was designed to allow - you to create branches, work on them for while and merge them back - into the main line of development. You should also be able to merge - work performed on the main branch into the branch you are working on. - Arbitrary sharing and merging between branches is not currently - supported. - - Last modified: _6/13/1997_ - - 5. What is CVS *not* useful for? - - CVS is not a build system. - - Though the structure of your Repository and modules file interact with - your build system (e.g. a tree of Makefiles), they are essentially - independent. - - CVS does not dictate how you build anything. It merely stores files - for retrieval in a tree structure you devise. - - CVS does not dictate how to use disk space in the checked out working - directories. If you require your Makefiles or build procedures to know - the relative positions of everything else, you wind up requiring the - entire Repository to be checked out. That's simply bad planning. - - If you modularize your work, and construct a build system that will - share files (via links, mounts, VPATH in Makefiles, etc.), you can - arrange your disk usage however you like. - - But you have to remember that *any* such system is a lot of work to - construct and maintain. CVS does not address the issues involved. You - must use your brain and a collection of other tools to provide a build - scheme to match your plans. - - Of course, you should use CVS to maintain the tools created to support - such a build system (scripts, Makefiles, etc). - - CVS is not a substitute for management. - - You and your project leaders are expected to plan what you are doing. - Everyone involved must be aware of schedules, merge points, branch - names, release dates and the range of procedures needed to build - products. (If you produce it and someone else uses it, it is a - product.) CVS can't cover for a failure to manage your project. - - CVS is an instrument for making sources dance to your tune. But you - are the piper and the composer. No instrument plays itself or writes - its own music. - - CVS is not a substitute for developer communication. - - When faced with conflicts within a single file, most developers manage - to resolve them without too much effort. But a more general definition - of "conflict" includes problems too difficult to solve without - communication between developers. - - CVS cannot determine when simultaneous changes within a single file, - or across a whole collection of files, will logically conflict with - one another. Its concept of a "conflict" is purely textual, arising - when two changes to the same base file are near enough to spook the - merge command into dropping conflict markers into the merged file. - - CVS is not capable of figuring out distributed conflicts in program - logic. For example, if you change the arguments to function X defined - in file A and, at the same time, edit file B, adding new calls to - function X using the old arguments. You are outside the realm of CVS's - competence. - - Acquire the habit of reading specs and talking to your peers. - - CVS is not a configuration management system. - - CVS is a source control system. The phrase "configuration management" - is a marketing term, not an industry-recognized set of functions. - - A true "configuration management system" would contain elements of the - following: - - * Source control. - * Dependency tracking. - * Build systems (i.e. What to build and how to find - things during a build. What is shared? What is local?) - * Bug tracking. - * Automated Testing procedures. - * Release Engineering documentation and procedures. - * Tape Construction. - * Customer Installation. - * A way for users to run different versions of the same - software on the same host at the same time. - - CVS provides only the first. - - Last modified: _6/13/1997_ - - Category: /What_is_CVS_/Where_do_I_find_CVS_/ - - " + Where do I find CVS? Where can I find Help?" - - 1. How do I get more information about CVS? - - The first thing I would do is to read the Info file that comes with - the CVS sources under "doc". You can format and read the cvs.texinfo - file in two ways: 1. Use TeX to format it and a "dvips" command to - print it and 2. Install the cvs.info files that are created by the - Makefile and read them online using the Emacs "info-mode" or a - stand-alone "info" reader. - - Then I'd run "cvsinit" to set up a Repository and read the man page - while trying out the commands. - - Type "cvs -H" for general help or "cvs -H command" for - command-specific help. - - For background, you can read the original CVS paper (in the source - tree, under "doc"). It describes the purpose of CVS and some of how it - was designed. Note that the emphasis of the document (especially on - multiple vendors providing the same sources) is somewhat out of date. - - For more detailed information about "internals", read the man pages - for RCS. If you are a programmer, you can also read the source code to - CVS. - - Other information and tutorials may be available in the "doc" - directory of the FTP archive described below. - - For current information, and a fair amount of detail, join the - info-cvs mailing list described below. - - Last modified: _6/13/1997_ - - 2. Is there an archive of CVS material? - - An anonymous FTP area has been set up. It contains many of the CVS - files you might want, including extra documentation, patches and a - copy of the latest release. - - ftp ftp.delos.com - >>> User: anonymous - >>> Passwd: - cd /pub/cvs - get README - get Index - - The README has more (and more up-to-date) information. The Index - contains a terse list of what is in the archive. - - A WWW home page is also available at http://www.delos.com/cvs. - - This Didn't Exist 6/23/1998 - - Last modified: _6/24/1998_ - - 3. How do I get files out of the archive if I don't have FTP? - - Use one of the FTP<->Email servers. These are the ones I've been told - about: - - FTPMAIL service is available from the same host as the FTP server - described above. Send mail to "ftpmail@delos.com" containing "help" in - the body of the message. For example, on most Unix systems, you can - type: - - echo help | Mail ftpmail@delos.com - - The FTPMAIL server will respond with a document describing how to use - the server. If the "Mail" command doesn't exist on your system, try - "mailx", "/usr/ucb/mail" or "/bin/mail". - - If you are on BITNET, use Princeton's BITFTP server. Type - - echo 'send help' | Mail bitftp@pucc.princeton.edu - - (It is likely that only BITNET addresses can use this one.) - - Other possibilities I've heard of from the net: (Try the one closest - to you.) - - ftpmail@decwrl.dec.com ftpmail@sunsite.unc.edu ftpmail@cs.arizona.edu - ftpmail@cs.uow.edu.au ftpmail@doc.ic.ac.uk - - Last modified: _6/13/1997_ - - 4. How do I get a copy of the latest version of CVS? - - The latest released version of CVS and all the programs it depends on - should be available through anonymous FTP on any FSF archive. The main - FSF archive is at "prep.ai.mit.edu". There are mirrors of the FSF - archive on UUNET and other large Internet sites. - - Program(s) Suggested revision - ----------- ----------------------- - CVS 1.5 - RCS 5.7 (latest version available today) - GNU diff 2.7 (or later) [contained in diffutils-2.7] - GDBM 1.5 (or later) [optional] - - The GNU version of diff is suggested by both the RCS and CVS - configuration instructions because it works better than the standard - version. - - It is a good idea not to accept the versions of CVS, RCS or diff you - find lying on your system unless you have checked out their - provenance. Using inconsistent collections of tools can cause you more - trouble than you can probably afford. - - The FTP archive mentioned above should contain the latest official - release of CVS, some official and unofficial patches and possibly - complete patched versions of CVS in use somewhere. - - Last modified: _6/13/1997_ - - 5. Is there a mailing list devoted to CVS? How do I find it? - - An Internet mailing list named "info-cvs" grew out of the private - mailing list used by the CVS 1.3 alpha testers in early 1992. - Throughout 1994, the list received an average of 100 messages per - month. - - You can add yourself to the mailing list by sending an Email message - to: - - info-cvs-request@prep.ai.mit.edu - - (Don't forget the "-request" or you'll send a message to the whole - list, some of whom are capable of remote execution.) - - Mail to the whole list should be sent to: - - info-cvs@prep.ai.mit.edu - - An archive of the mailing list is maintained in the FTP archive - mentioned above. - - Last modified: _6/13/1997_ - - 6. What happened to the CVS Usenet newsgroup I heard about? - - - A Usenet newsgroup named "gnu.cvs.info" was announced in April - 1993, with an expected creation date of August, 1993. However, - nothing came of this. - - If you want to discuss CVS on usenet, the correct group is - comp.software.config-mgmt (which also covers other configuration - management systems). Someday it might be possible to create a - comp.software.config-mgmt.cvs, but only if there is sufficient - CVS traffic on comp.software.config-mgmt. - - kingdon@cyclic.com - - Last modified: _9/6/1997_ - _________________________________________________________________ - - [Add an answer to this category] - - [Category /] - _________________________________________________________________ - - _Search the FAQ-O-Matic:_ ____________________ Search - [matching all words] - Or look for questions modified in the last: [7.] Days - _________________________________________________________________ - - The FAQ-O-Matic lives at http://gille.loria.fr:7000/cgi-bin/faqomatic. - The code was written by Jon Howell, and the content by folks from all - over the web. - _________________________________________________________________ |
