Use cvs for Version Management

Use cvs for Version Management

Translation: Liao Bin

#/////////////////////////////////////// /// // # Use cvs for Version Management #2000-6-30 # CVS 1.10.7 #### per cederqvist et al # Translated by Liao bin # thanks to Huang Ke for his input and typographical work # copyrigh: GPL ##///////////////////////////////////// /// // Quick Content Index 1. overview ....................................... .................. 1 2. code repository ...................................... ............... 7 3. start a project with CVS ........................................ .. 29 4. main version (revision )................................... ...... 33 5. branch and merge ..................................... .............. 41 6. recarsive behavior ...................................... ..... 49 7. add, delete, rename the file and directory ................................... 51 8. review the development history ..................................... ............ 57 9. place the binary file ........................................ ....... 59 more than 10 developers work at the same time ................................ ........ 61 11 main version management ................................... .......... 71 12 keyword substitution .................................... ............ 73 13 tracking third-party code ................................... ............ 77 14 how does your system interact with CVS ............................... ......... 81 15 special files .................................... ................. 83 16 Appendix 1) CVs command orientation ..................... ............................. 85 2) for details about the CVS command, see .................................... ........ 115 3) document management reference .................................. ....... 127 4) all environment variables that affect CVS .................................. .... 141 5) compatibility between different versions of CVS .................................. .... 143 6) the problem ..................................... ............ 145 7) credits ....................................... ............. 153) for CVs and The manual is always handled .................................. 155 directory ...................................... ..................... 157 1 Introduction This chapter is written by people who have never used CVs, and may have never used any version control tools before. 1.1 What is CVs? CVS is a version control system that records the history of your original code files. For example, when the software is modified, problems may occur (* the bugs is translated here), and you may not find these problems for a long time after the modification. With CVs, you can easily review the old code version to find out which modification causes these problems. Sometimes this will be very helpful. You may keep your code version every time, which may waste a lot of your code space. CVS uses a smart way to save multiple of your versions in one file. It only retains different versions. If you are a member of a project group, cvs can also help you. Unless you are very careful, you can easily cover others' work. Some editors, such as gnuemacs, try to determine whether a file has been modified by both of them at the same time. Unfortunately, this security method will no longer work If one uses another editor. CVS solves this problem by allowing different developers to work independently. Every developer's work is in his/her own directory, and CVs will merge after each developer's work is completed. CVS was created by Dick grune as a branch of shell scripts. In October 1986, it was shipped to the newsgroup Comp. soures. UNIX when it released 6th volumes. However, no code in the current CVS conflict algorithm comes from these scripts. In March 1989, Brian berlinor designed and compiled the CVS code. Jett. Polk later helped Brian complete the CVS model design and commercial version support. You can obtain CVS in different ways, including free download on the Internet. If you want to download CVs and other CVS articles for more information, see: http://www.cyxlic.com http://www.loria.fr /~ Molli/cvs-index.html. There is a list of emails called Info-CVS about CVs. Subscribe to or unsubscribe to this list please mail to info-cvs-request@gnu.org if you prefer USENET newsgroup, CVS discussion group is comp. software. confg. mgmt. a comp may be created in the future. software. confg. mgmt. CVS newsgroup, but it may be comp. software. confg. MGMT has too many discussions. You may want to subscribe to the bug-CVS email list, which contains more information in Appendix H [BUGS. Please email it to the bug-cvs-reqnest@gnu.org to subscribe to it. 1.2 What CVS cannot do (untranslated) 2 3 Use CVS to start a project =========================== because the file names are changed and they are moved to another directory not often, therefore, the first thing you need to do when starting a new project is to consider your file organization. It is not impossible to change the file name or move the file, but it increases the potential for confusion, and CVS is particularly sensitive in the directory where the name is changed. See section 7.4 [move a file]. (* Note: in UNIX, renaming and moving are the same ). The next step depends on the situation in your hands. 3.1 The first step for file creation is to create a file in the repository. This can be done in a variety of ways. -------------------------------------------------------------------- 3.1.1 create a directory tree. When you start using CVS, you may already have several projects that can be managed using CVS. In this case, the easiest way is to use the "import" command. One example is the easiest way to explain how to use it. Suppose you have some files you want to put in CVS in "wdir", and you want them to be placed in the following directory in the data warehouse: "$ cvsroot/yoyodyne/rdir" you can use the following command: $ CD wdir $ CVS inport-M "inported sources" yoyoyodyne/rdir Yoyo start if you do not use the "-M" parameter to record a log, CVS calls an Editor (* Note: Usually VI) and prompts you to enter information. The "Yoyo" string is the developer's tab, and "start" is the release tab. They have no special significance, but they are only put here because of the need of CVS. For more information, see Chapter 2 [tracking code. Now you can check whether it is valid and then delete your original code directory. $ CD $ MV dir. orig $ CVS checkout yoyodyne/DIR $ diff-r dir. orig yoyodyne/DIR $ Rm-r dir. orig. to avoid accidental access to your original directory to edit files, it is a good idea to delete the original code. Of course, it is wise to keep a backup to another place before you delete it. The "checkout" command can use the module name as a parameter (as in all previous examples) or a path relative to $ cvsroot, as shown in the preceding example. You should check whether the permissions in the CVS directory are appropriate and make them belong to a specific group. See section 2.2.2 [file permissions]. If you want to "import" some files are binary code, you can use some special methods to indicate whether these files are binary files. See section C.2 [wrappers]. 4.1.3.1.2 create files from other version control systems. If you have a Project maintained by another version control system, such as the RCs, you may want to put these files in CVS, and keep the history of these files. The following are some discussions. From the RCS: if you use the RCs, find the RCS file ?? Generally, an object named "foo. c" contains an RC file named "RCS/Foo. C, V. (However, it may be elsewhere. Please refer to the documents of the RCS for relevant information ). If the file directory is not stored in CVS, create it in CVS. Then copy these files to the CVS warehouse directory (the name in the warehouse must be the original file with ", V"; these files are directly placed under the directory in CVS, rather than the sub-directory of "RCS ). This is one of the few cases in CVs that directly access the CVS warehouse, instead of using the CVS command. Then you can "checkout" them in the new directory. When you move an RFM file to CVS, it should be unlocked. Otherwise, some problems may occur during the moving operation. From other version control tools, many version control tools can output standard documents in the "RCS" format. If your version control tool can do this, directly output the RCS file, and then follow the example above. If your version tool cannot output the RCS file, you must write a script file to retrieve a version and put it into CVs. The "sccsarcs" script mentioned below is a good example. From SCCs: there is a "sccsarcs" script file that can be used to convert the SCCs file into an RCS file. This file is placed in the "contrib" directory of the original CVS code directory. Note: You must run it on a machine that has both the RCs and SCCs installed. And, just like other scripts in the "contrib." directory. (Your method may be changeable ). From PVCs: In "contrb", a script named "pves-to-RCS" can be used to convert PVCs to the RCS file. You must run it on a machine with both PVCs and RCS. See the notes in the script for more details. 3.1.3 create a directory tree from scratch to create a new project. The easiest way is to create an empty directory tree, as shown below: $ mkdir TC/man $ mkdir TC/testing after this, you can "import" This (empty) directory to the repository. $ Cd tc $ CVS import-M "Created directory structure" yoyoyodyne/DIR Yoyo start. Then, when a file is added, add the file (or directory) to the repository. Check whether the permissions in $ cvsroot are correct. Define module 3.2 the next step is to define the module in the "moduyes" file. This is not strictly required, but the module can easily associate related directories and files. The following example shows how to define a module. 1. obtain a copy of the module File. $ CVS checkout cvsroot/modules $ CD cvsroot 2. Edit this file and write the lines of the definition module. For details, see section 2.4 [Introduction to file management]. For a brief introduction, see section C.1 [module File]. Has its detailed description. You can use the following line definition module "Tc": TC yoyodyne/TC 3. submit your changes to the repository $ CVS commit-M "added TC module. "Modules 4. release module File $ CD $ CVS release-D cvsroot 4 ===== 5 branch and merge ============== = CVS allows you to extract a derived code to a separate development version --- branch. When you change the file in a branch, these changes will not appear in the primary development version or other branch versions. After that, you can use merging to move these changes from one branch to another (or the primary development version ). Merging involves using the "CVS Update-J" command to merge these changes to a working directory. You can confirm (COMMIT) This version, and thus affect copying these changes to other branches. When should I create a branch in release 5.1 assume that the TC. c release is complete. You are continuing to develop TC. C and plan to release version 1.1 in 2 months. Soon after, your customer began to complain that the code was faulty. You checked the 1.0 Release (see section 4.4 [note]). and found this error (this will have a small correction ). However, the current version is in a unstable state and will be stable in the next month. In this way, there is no way to release the latest version to correct the problem. Then you can create a branch based on this version tree Version 1.0. You can modify the branches of the tree without affecting the trunk. When the revision is completed, you can choose whether to merge it with the trunk or continue to keep it in this branch. When creating a branch in container 5.2, you can use "tag-B" to create a branch. For example, if you are working on a work copy: $ CVS tag-B rel_00000_patches, this Splits a branch based on the current copy and assigns the name "rel_00000_patches. It is very important to know that a branch is created in the CVS Repository rather than in a work copy. In the preceding example, creating a branch based on the current version will not automatically copy the current job to the new branch. For more information, see section 5.3 [go to a branch]. You can also create a branch without reference to any work copy. You can use the rtag command: CVs rtag-B-r rel-1-0 rel-1-0-patches TC. "-r rel-1-0" indicates that this branch is based on the version file that marks the rel-1-0 and it does not start from the latest version. this is useful for branching from an old version (for example, when a previous stable version is revised) when the "tag" flag is used, this "-B" flag tells rtag to create a branch (rather than a symbolic connection of this version ). Note that marking rel-1-0 may have different version numbers for different files. Therefore, the result of this command is a new version branch named "rel-1-0-patches" for the TC module, which is based on the version tree labeled as "rel-1-0. In branch 5.3, you can go to the branch in two ways: Re-checkout or from an existing copy. Run the checkout command again and carry the "-R" identifier. The Tag Name of the Branch will be followed. (See 5.2 [Create a branch]): $ CVS checkout-r rel-1-0-patches TC. or if you already have a copy, you can use the "Update-R" command to go to this branch. $ CVS update-r rel-1-0-patches TC. or use another equivalent command: $ cd tc $ CVS update-r rel-1-0-patches, which is valid for existing copies of the master code or other branches. the above command will transfer it to the branch of the Life name. Similar to the "Update" command. "Update-R" merges any changes you have made. Please note whether a conflict exists. 1. However, your copy of work has been switched to a specific branch. It will remain in this branch until you perform other operations. This means that the change to copy the checkin from this job will be added to the new version of this branch, without affecting the master version and other branch code. You can run the "status" command to see which branch a copy task is based on. Search for a "Sticky tag" field in their output (see Section 4.9 ["Sticky tag"], page 38th). That is your current branch number. $ CVS status-V driver. c backend. c ======================================================== ================================ file: driver. c Status: up-to-date version: 1.7 sat dec s 18:25:54 1992 RCS version: 1.7/u/cvsroot/yoyodyne/TC/driver. c, V sticky Tag: rel-1-0-patches (branch: 1.7.2) sticky date: (none) stick option: (none) Existing Tag: rel-1-0-patches (branck: 1.7.2) rel-1-0 (Revision: 1.7) ================================ ========================================================== ======== File: backend. c Status: up-to-date version: 1.4 Tue Dec 1 14:39:01 RCS version: 1.4/u/cvsroot/yoyodyne/TC/sticky Tag: rel-1-0patches (branch: 1.4.2) sticky Date: (none) sticky option: (none) Existing Tag: Rel-1-0-patches (branch: 1.4.2) Rel-1-0 (Revision: 1.4) Rel-0-4 (Revision: 1.4) do not be confused because the branches of each file are different ("1.7.2" and "1.4.2. The tab of the branch is the same: "rel-1-0-patches", and the files with the Same tab are the same branch. In the preceding example, "driver. c" has more changes than "backend. c" before Branch establishment, so their version numbers are different. For details about how to build a branch, see section 5.4 [branch and trunk version. Generally, the history of the trunk version of a file is a growth line (see the 5.4 [Trunk version] page ): + ----- ++ ----- +! 1.1! ----! 1.2! ----! 1.3! ----! 1.4! ----! 1.5! + ----- ++ ----- + However, CVS is not limited to linear development. The main version can be divided into different branches, each of which can be an independent self-maintenance development line. Changes in a branch can be easily transferred to the trunk. Each branch has a branch number, which is composed of an odd number in decimal format separated by ".". The branch number is arranged according to the main line version separated. You can use the branch number to separate multiple branches from a specific version. All branch versions depend on the original version number. The following example shows this. + ------------- + 1.2.2.3.2 branch-> + --! 1.2.2.3.2.1!! + ------------- +! + --------- ++ --------- + 1.2.2 branch-> + --! 1.2.2.1! ----! 1.2.2.2! ----! 1.2.2.2!! + --------- ++ --------- +!! + ----- ++ ----- +! 1.1! ----! 1.2! ----! 1.3! ----! 1.4! ----! 1.5! <-Trunk + ----- ++ ----- +!!! + --------- ++ --------- + 1.2.4 branch-> + --! 1.2.4.1! ----! 1.2.4.2! ----! 1.2.4.2! + --------- ++ --------- + The details of how you create a specific branch number are not usually considered, but here we will talk about how it works. When CVS creates a branch number, it first obtains the first unused even number and the start number is 2. For example, when you create a branch from the master version 6.4, if the branch number is 6.4.2, all branch numbers whose last digit is 0 are used in the CVS internal part (for example, 6.4.0 ). (See section 5.5 [internal branch number] Page 44) for special meanings of branch 1.1.1, see Chapter 13 [tracking code]. The section 5.5 internal branch number describes the features of the internal branch (MAGIC branches) of CVS. In most cases, you do not need to consider the internal branch number. CVs will manage it for you. However, it will appear under certain conditions, so it is useful to understand how it works. Generally, the branch number consists of an odd number of "." separated decimal integers. See section 4.1 [version number]. However, this is not exactly the case. For efficiency reasons, CVS sometimes inserts an additional "0" in the second position at the end of the right (1.2.4 to 1.2.0.4, 8.9.10.11.12 to 8.9.10.11.0.12 ). CVs will well hide these transformations behind the scenes, but in some places, this concealment is not completely: * internal branch numbers will appear in CVS log files. * You cannot use the symbolic branch name for "CVS admin. You can use the admin command to re-allocate a symbolic name as expected by the RCS for a branch. If r4patches is a file "numbers. C "name, you can use the following command: $ CVS admin-nr4patches: 1.4.2 numbers. C is valid only when at least one version has been submitted to this branch. Please be careful not to assign a tag to an error ID (I have not seen how a tag was assigned yesterday ). -------------------------------------------------------------------------------- 5.6 merge an entire branch. You can merge a branch to your working directory and click "-J branch number" in the "Update" command. Use "-J branch number" to merge the changes between the derived Pivot Point and the latest version of the original version to your working directory "-J", which means "join ". Now let's take a look at the following tree: + ----- ++! 1.1! ----! 1.2! ----! 1.3! ----! 1.4! <-Trunk + ----- ++ ----- +!!! + --------- ++ --------- + R1fix branch-> + --! 1.2.2.1! ----! 1.2.2.2! + --------- ++ --------- + Branch 1.2.2 is assigned a rifix name. the following example assumes that the module "Mod" contains only one file "M. C "$ CVS checkout mod # Get the latest version 1.4 $ CVS Update-J r1fix M. C # merge all changes in the branch, that is, the changes between 1.2 and 1.2.2.2 # To the working directory of this file. $ CVS commit-M "included r1fix # conflicts may occur when version 1.5 is created during merge. If this happens, you can resolve it before submitting a new version. For details, see section 10.3 [conflicting examples]. If your original file contains keywords (See Chapter 12th [keyword substitution]). You may get more conflict information than strict conflicts. See section 5.10 [merge and keyword] To learn how to avoid this problem. The "checkout" command also supports the "-J" parameter. The following example shows the same effect as the above example. $ CVS checkout-J r1fix mod. $ CVS commit-M "included r1fix" Limit 5.7 is merged from one branch multiple times. Continue with the above example. Now this tree looks like this: + ----- ++! 1.1! ----! 1.2! ----! 1.3! ----! 1.4! ----! 1.5! <-Trunk + ----- ++ ----- +! *! *! + --------- ++ --------- + R1fix branch-> + --! 1.2.2.1! ----! 1.2.2.2! + --------- ++ --------- + As discussed above, the "*" number guided by the branch 1.2.2.2 indicates the merge from the rifix branch to the trunk. Now we continue to develop the rifix branch: + ----- ++! 1.1! ----! 1.2! ----! 1.3! ----! 1.4! ----! 1.5! <-Trunk + ----- ++ ----- +! *! *! + --------- ++ --------- + R1fix branch-> + --! 1.2.2.1! ----! 1.2.2.2! ----! 1.2.2.3! + --------- ++ --------- + Then you may want to merge new changes to the trunk. If you still use "CVS Update-J javasix M. c" CVs, you will try to merge the items you have already merged, which may cause something unexpected. Therefore, you must make it clear that you want to merge only unmerged content. In this case, two "-J" parameters are required. CVS merges the changes from the first "-J" version to the second "-J" version. For example, in our example above: CVs Update-J 1.2.2.2-J r1fix M. c If the problem occurs, you need to manually specify the version 1.2.2.2. A better way is to use: CVs Update-J r1fix: yesterday-J r1fix M. c. However, the better way is to re-place a token to the rifix branch after each merge, and then use the token for the merge: CVs Update-J merged_from_rifix_to_trunk-J r1fix M. c producer 5.8 merges two different versions using two "-J" signs. This update (and checkout) command can merge two different versions to your working directory. $ CVS Update-J 1.3 backend. C will restore version 1.5 to version 1.3, so pay attention to the version sequence. If you use this option when operating on multiple files, you must understand that the numbers of versions may be completely different between different files. You must use a tag instead of a version number to perform operations on multiple files. Using two "-J" operations can also restore the added or deleted files. For example, assume that you have a file named "file1" in version 1.1 and delete it in version 1.2. The following is an example of how to perform this operation: $ CVS Update-J 1.2-J 1.1 file1 file1 $ CVS commit-m Test Checking in file1;/tmp/CVS-sanity/cvsroot/first-DIR/file1 file1, v New Revision: 1.3; previous revision: 1.2 done $ merge 5.9 merge to add and delete files. If your changes during merge involve adding or deleting some files, "Update-J" will reflect these changes. Example: CVs update-A touch a B c CVS Add a B c; CVS ci-M "added" a B c cvs tag-B branchtag CVS update-r branchtag touch D; CVS add d rm a; CVS rm a CVS ci-M "added D, removed a" CVS Update-a CVS Update-J branchtag after these commands (note commit ), file 'A' will be deleted, and file 'D' will be added to the trunk. Merge 5.10 merge and keywords if the merged file contains keywords (See Chapter 12th [keyword substitution], Page 73), you will usually get numerous conflict reports during the merge, because it is very different in different versions. Therefore, you often need to use "-KK" When merging (see section 12.4 [alternative mode], 75) to select an item. Use a keyword name instead of a method to extend the value of a keyword. This option ensures that the versions you merge are consistent with each other and avoid conflicts. For example, suppose you have a file: + --------- + br1-> + --! 1.1.2.1!! + --------- +!! + ----- ++ ----- +! 1.1! ----! 1.2! + ----- ++ ----- + And copy your current working directory to the master node (version 1.2 ). Then, the following merge results will produce a conflict. Please refer to the example: $ cat file1 key $ revision: 1.3 $... $ CVS Update-J br1 U file1 RCS file:/cvsroot/first-DIR/file1, V retrieving Revision 1.1 retrieving revision 1.1.2.1 meging differences between 1.1 and 1.1.2.1 into file1 rscmerge: Warning: conflicts during merge $ cat file1 ___ fckpd ___ 0lt; <file1 key $ revision: 1.3 $ ====== key $ rerision: 1.1.2.1 $ ___ fckpd ___ 0gt; >>>>>> 1.1.2.1... the conflict occurs when an attempt is made to change 1.1 and 1.1.2.1 Merge to your working directory. Therefore, when this keyword ranges from "Revision: 1.1" to "Revision: 1.1.2.1", CVs will try to merge this change to your working directory, this conflicts with the change "Revision: 1.2" in your directory. The following example uses "-KK": $ cat file1 key $ revision: 1.3 $... $ CVS Update-KK-J br1 v file1 RCS file:/cvsroot/first-DIR/file1, V retrieving Revision 1.1 retrieving revision 1.1.2.1 merging differences between 1.1 and 1.1.2.1 into file1 $ cat file1 key $ revision: 1.3 $... in this example, both version 1.1 and 1.1.2.1 are extended to pure "revision", so there will be no conflict during merge. However, using the "-KK" parameter is still a major problem. That is, it uses the key-word extension mode commonly used by CVS. In special cases, if the mode uses the "-kb" parameter for binary files. This will cause problems. Therefore, if your database contains binary files, you must manually handle these problems, instead of using "-KK ". More than 10 developers work at the same time ----------------- conflicts often occur when multiple developers participate in a project at the same time. Generally, when two people want to edit a file at the same time. One of its solutions is to lock the file or use a retained checkout, which allows only one person to edit the file at a time. This is the only solution for some version control systems, including RCs and SCCs. Currently, in CVS, the common way to use a retained checkout is to use the "CVS admin-1" command (see A-6-1AB [admin selection]). It will be explained below that this is not a good Smart solution, when it is a method that many people like to use. The following describes how to use appropriate methods to prevent two people from simultaneously editing a file, rather than using software to force this. In CVs, the default method is "unreserved checkout" -- non-reserved export. In this way, developers can edit an object in their work copy at the same time. There is no automatic way for the first job to be submitted to know that another person is editing the file. Another person may get an error message when trying to submit the file. They must use the CVS command to keep their work copies updated from the same repository. This operation is automatic. CVS supports multiple communication mechanisms of facilitate without forcing certain rules, such as "resered checkouts. The following sections describe how these different methods work and the problems involved in choosing multiple methods. 10.1 The File status is based on the operations you have performed on the exported files and the operations you have performed on these files in the repository version. We can divide a file into several States. This status can be obtained by the "status" command, which is: up-to-date: for this branch in use, the file is consistent with the last version in the repository. Locally modified: You have modified the file but have not "commit ". Locally added: the "add" command is used to add files, but no "commit" locally removed: You used the "Remove" command, but no "commit" needs checkout: others submitted an updated version. The name of this status is misleading. You should use "Update" instead of "checkout" to update a new version. Needs Patch: Like "needs checkout", but the CVS service only provides the patch file, not the entire file. The effect of the patch is the same as that of the entire file. Needs merge: Some people submit an updated version, but you have modified these files. File had conflicts on merge: This is similar to "locally modified", but the "Update" command provides a conflict information. If you have not resolved the conflict, you need to solve the problem. For the solution, see section 10.3 [conflict example]. unkown: CVs does not know about this file. for example, if you create a new file without using the "add" command to help identify the File status, "status" also reports the working version (working vevision ), this is the version from which the file is generated, and the "repository version" (repository vevision) is also reported ). This is the final version of the branch of this file in the repository. Select an example of the "status" command in appendix B [invoking CVS]. For information about the output content of "Sticky tag" and "Sticky date", see Section 4.9 [sticky tags]. For details about the output content of "Sticky options", see "-k". For details, see [update selection] In section a.16.1. You should put the "Update" and "status" commands together. You can use "Update" to update your file to the latest state. You can use the "status" command to obtain the operations that the "Update" command will perform. (Of course, the status in the repository may change before you run update ). In fact, if you want to use a command to obtain more formal State information than "status", you can use: $ CVS-n-Q-update the "-n" option indicates that the update is not executed but only the status is displayed. The "-Q" option indicates that the name of each directory is not printed. For more information about the "Update" command, see Appendix B [Use CVS]. 10.2 update a file to the latest version. If you want to update or merge a file, run the update command. For a file that is not the latest version, this command is roughly the same as the "checkout" command: the latest version is proposed from the repository and put into the working directory. When you use the "Update" command, the files you modified will not be damaged under any circumstances. If no new version is available in the repository, your code will not be affected during "Update. When you edit a file and update the version in the repository, "Update" merges all the changes to your working directory. For example, imagine that you have exported a file of version 1.4 and started editing it. At some time, others submitted version 1.5, and then submitted version 1.6, if you run the update command, CVs will put the changes between version 1.4 and version 1.6 into your files. If some of your changes are too close to those between version 1.4 and version 1.6, a "overlop" conflict will occur. In this case, a warning message is output, and the files retained in the result contain two versions of conflicting code, separated by special symbols. See section A.16 [update] for a complete description of the "Update" command.