1This is cvs.info, produced by makeinfo version 4.0 from ./cvs.texinfo. 2 3START-INFO-DIR-ENTRY 4* CVS: (cvs). Concurrent Versions System 5END-INFO-DIR-ENTRY 6 7 Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994 8Free Software Foundation, Inc. 9 10 Permission is granted to make and distribute verbatim copies of this 11manual provided the copyright notice and this permission notice are 12preserved on all copies. 13 14 Permission is granted to copy and distribute modified versions of 15this manual under the conditions for verbatim copying, provided also 16that the entire resulting derived work is distributed under the terms 17of a permission notice identical to this one. 18 19 Permission is granted to copy and distribute translations of this 20manual into another language, under the above conditions for modified 21versions, except that this permission notice may be stated in a 22translation approved by the Free Software Foundation. 23 24 25File: cvs.info, Node: Tags, Next: Tagging the working directory, Prev: Assigning revisions, Up: Revisions 26 27Tags-Symbolic revisions 28======================= 29 30 The revision numbers live a life of their own. They need not have 31anything at all to do with the release numbers of your software 32product. Depending on how you use CVS the revision numbers might 33change several times between two releases. As an example, some of the 34source files that make up RCS 5.6 have the following revision numbers: 35 36 ci.c 5.21 37 co.c 5.9 38 ident.c 5.3 39 rcs.c 5.12 40 rcsbase.h 5.11 41 rcsdiff.c 5.10 42 rcsedit.c 5.11 43 rcsfcmp.c 5.9 44 rcsgen.c 5.10 45 rcslex.c 5.11 46 rcsmap.c 5.2 47 rcsutil.c 5.10 48 49 You can use the `tag' command to give a symbolic name to a certain 50revision of a file. You can use the `-v' flag to the `status' command 51to see all tags that a file has, and which revision numbers they 52represent. Tag names must start with an uppercase or lowercase letter 53and can contain uppercase and lowercase letters, digits, `-', and `_'. 54The two tag names `BASE' and `HEAD' are reserved for use by CVS. It is 55expected that future names which are special to CVS will be specially 56named, for example by starting with `.', rather than being named 57analogously to `BASE' and `HEAD', to avoid conflicts with actual tag 58names. 59 60 You'll want to choose some convention for naming tags, based on 61information such as the name of the program and the version number of 62the release. For example, one might take the name of the program, 63immediately followed by the version number with `.' changed to `-', so 64that CVS 1.9 would be tagged with the name `cvs1-9'. If you choose a 65consistent convention, then you won't constantly be guessing whether a 66tag is `cvs-1-9' or `cvs1_9' or what. You might even want to consider 67enforcing your convention in the taginfo file (*note user-defined 68logging::). 69 70 The following example shows how you can add a tag to a file. The 71commands must be issued inside your working directory. That is, you 72should issue the command in the directory where `backend.c' resides. 73 74 $ cvs tag rel-0-4 backend.c 75 T backend.c 76 $ cvs status -v backend.c 77 =================================================================== 78 File: backend.c Status: Up-to-date 79 80 Version: 1.4 Tue Dec 1 14:39:01 1992 81 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 82 Sticky Tag: (none) 83 Sticky Date: (none) 84 Sticky Options: (none) 85 86 Existing Tags: 87 rel-0-4 (revision: 1.4) 88 89 For a complete summary of the syntax of `cvs tag', including the 90various options, see *Note Invoking CVS::. 91 92 There is seldom reason to tag a file in isolation. A more common 93use is to tag all the files that constitute a module with the same tag 94at strategic points in the development life-cycle, such as when a 95release is made. 96 97 $ cvs tag rel-1-0 . 98 cvs tag: Tagging . 99 T Makefile 100 T backend.c 101 T driver.c 102 T frontend.c 103 T parser.c 104 105 (When you give CVS a directory as argument, it generally applies the 106operation to all the files in that directory, and (recursively), to any 107subdirectories that it may contain. *Note Recursive behavior::.) 108 109 The `checkout' command has a flag, `-r', that lets you check out a 110certain revision of a module. This flag makes it easy to retrieve the 111sources that make up release 1.0 of the module `tc' at any time in the 112future: 113 114 $ cvs checkout -r rel-1-0 tc 115 116This is useful, for instance, if someone claims that there is a bug in 117that release, but you cannot find the bug in the current working copy. 118 119 You can also check out a module as it was at any given date. *Note 120checkout options::. When specifying `-r' to any of these commands, you 121will need beware of sticky tags; see *Note Sticky tags::. 122 123 When you tag more than one file with the same tag you can think 124about the tag as "a curve drawn through a matrix of filename vs. 125revision number." Say we have 5 files with the following revisions: 126 127 file1 file2 file3 file4 file5 128 129 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 130 1.2*- 1.2 1.2 -1.2*- 131 1.3 \- 1.3*- 1.3 / 1.3 132 1.4 \ 1.4 / 1.4 133 \-1.5*- 1.5 134 1.6 135 136 At some time in the past, the `*' versions were tagged. You can 137think of the tag as a handle attached to the curve drawn through the 138tagged revisions. When you pull on the handle, you get all the tagged 139revisions. Another way to look at it is that you "sight" through a set 140of revisions that is "flat" along the tagged revisions, like this: 141 142 file1 file2 file3 file4 file5 143 144 1.1 145 1.2 146 1.1 1.3 _ 147 1.1 1.2 1.4 1.1 / 148 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here 149 1.3 1.6 1.3 \_ 150 1.4 1.4 151 1.5 152 153 154File: cvs.info, Node: Tagging the working directory, Next: Tagging by date/tag, Prev: Tags, Up: Revisions 155 156Specifying what to tag from the working directory 157================================================= 158 159 The example in the previous section demonstrates one of the most 160common ways to choose which revisions to tag. Namely, running the `cvs 161tag' command without arguments causes CVS to select the revisions which 162are checked out in the current working directory. For example, if the 163copy of `backend.c' in working directory was checked out from revision 1641.4, then CVS will tag revision 1.4. Note that the tag is applied 165immediately to revision 1.4 in the repository; tagging is not like 166modifying a file, or other operations in which one first modifies the 167working directory and then runs `cvs commit' to transfer that 168modification to the repository. 169 170 One potentially surprising aspect of the fact that `cvs tag' 171operates on the repository is that you are tagging the checked-in 172revisions, which may differ from locally modified files in your working 173directory. If you want to avoid doing this by mistake, specify the 174`-c' option to `cvs tag'. If there are any locally modified files, CVS 175will abort with an error before it tags any files: 176 177 $ cvs tag -c rel-0-4 178 cvs tag: backend.c is locally modified 179 cvs [tag aborted]: correct the above errors first! 180 181 182File: cvs.info, Node: Tagging by date/tag, Next: Modifying tags, Prev: Tagging the working directory, Up: Revisions 183 184Specifying what to tag by date or revision 185========================================== 186 187 The `cvs rtag' command tags the repository as of a certain date or 188time (or can be used to tag the latest revision). `rtag' works 189directly on the repository contents (it requires no prior checkout and 190does not look for a working directory). 191 192 The following options specify which date or revision to tag. See 193*Note Common options::, for a complete description of them. 194 195`-D DATE' 196 Tag the most recent revision no later than DATE. 197 198`-f' 199 Only useful with the `-D DATE' or `-r TAG' flags. If no matching 200 revision is found, use the most recent revision (instead of 201 ignoring the file). 202 203`-r TAG' 204 Only tag those files that contain existing tag TAG. 205 206 The `cvs tag' command also allows one to specify files by revision 207or date, using the same `-r', `-D', and `-f' options. However, this 208feature is probably not what you want. The reason is that `cvs tag' 209chooses which files to tag based on the files that exist in the working 210directory, rather than the files which existed as of the given tag/date. 211Therefore, you are generally better off using `cvs rtag'. The 212exceptions might be cases like: 213 214 cvs tag -r 1.4 backend.c 215 216 217File: cvs.info, Node: Modifying tags, Next: Tagging add/remove, Prev: Tagging by date/tag, Up: Revisions 218 219Deleting, moving, and renaming tags 220=================================== 221 222 Normally one does not modify tags. They exist in order to record 223the history of the repository and so deleting them or changing their 224meaning would, generally, not be what you want. 225 226 However, there might be cases in which one uses a tag temporarily or 227accidentally puts one in the wrong place. Therefore, one might delete, 228move, or rename a tag. Warning: the commands in this section are 229dangerous; they permanently discard historical information and it can 230difficult or impossible to recover from errors. If you are a CVS 231administrator, you may consider restricting these commands with taginfo 232(*note user-defined logging::). 233 234 To delete a tag, specify the `-d' option to either `cvs tag' or `cvs 235rtag'. For example: 236 237 cvs rtag -d rel-0-4 tc 238 239 deletes the tag `rel-0-4' from the module `tc'. 240 241 When we say "move" a tag, we mean to make the same name point to 242different revisions. For example, the `stable' tag may currently point 243to revision 1.4 of `backend.c' and perhaps we want to make it point to 244revision 1.6. To move a tag, specify the `-F' option to either `cvs 245tag' or `cvs rtag'. For example, the task just mentioned might be 246accomplished as: 247 248 cvs tag -r 1.6 -F stable backend.c 249 250 When we say "rename" a tag, we mean to make a different name point 251to the same revisions as the old tag. For example, one may have 252misspelled the tag name and want to correct it (hopefully before others 253are relying on the old spelling). To rename a tag, first create a new 254tag using the `-r' option to `cvs rtag', and then delete the old name. 255This leaves the new tag on exactly the same files as the old tag. For 256example: 257 258 cvs rtag -r old-name-0-4 rel-0-4 tc 259 cvs rtag -d old-name-0-4 tc 260 261 262File: cvs.info, Node: Tagging add/remove, Next: Sticky tags, Prev: Modifying tags, Up: Revisions 263 264Tagging and adding and removing files 265===================================== 266 267 The subject of exactly how tagging interacts with adding and 268removing files is somewhat obscure; for the most part CVS will keep 269track of whether files exist or not without too much fussing. By 270default, tags are applied to only files which have a revision 271corresponding to what is being tagged. Files which did not exist yet, 272or which were already removed, simply omit the tag, and CVS knows to 273treat the absence of a tag as meaning that the file didn't exist as of 274that tag. 275 276 However, this can lose a small amount of information. For example, 277suppose a file was added and then removed. Then, if the tag is missing 278for that file, there is no way to know whether the tag refers to the 279time before the file was added, or the time after it was removed. If 280you specify the `-r' option to `cvs rtag', then CVS tags the files 281which have been removed, and thereby avoids this problem. For example, 282one might specify `-r HEAD' to tag the head. 283 284 On the subject of adding and removing files, the `cvs rtag' command 285has a `-a' option which means to clear the tag from removed files that 286would not otherwise be tagged. For example, one might specify this 287option in conjunction with `-F' when moving a tag. If one moved a tag 288without `-a', then the tag in the removed files might still refer to 289the old revision, rather than reflecting the fact that the file had 290been removed. I don't think this is necessary if `-r' is specified, as 291noted above. 292 293 294File: cvs.info, Node: Sticky tags, Prev: Tagging add/remove, Up: Revisions 295 296Sticky tags 297=========== 298 299 Sometimes a working copy's revision has extra data associated with 300it, for example it might be on a branch (*note Branching and 301merging::), or restricted to versions prior to a certain date by 302`checkout -D' or `update -D'. Because this data persists - that is, it 303applies to subsequent commands in the working copy - we refer to it as 304"sticky". 305 306 Most of the time, stickiness is an obscure aspect of CVS that you 307don't need to think about. However, even if you don't want to use the 308feature, you may need to know _something_ about sticky tags (for 309example, how to avoid them!). 310 311 You can use the `status' command to see if any sticky tags or dates 312are set: 313 314 $ cvs status driver.c 315 =================================================================== 316 File: driver.c Status: Up-to-date 317 318 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 319 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v 320 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 321 Sticky Date: (none) 322 Sticky Options: (none) 323 324 The sticky tags will remain on your working files until you delete 325them with `cvs update -A'. The `-A' option retrieves the version of 326the file from the head of the trunk, and forgets any sticky tags, 327dates, or options. 328 329 The most common use of sticky tags is to identify which branch one 330is working on, as described in *Note Accessing branches::. However, 331non-branch sticky tags have uses as well. For example, suppose that 332you want to avoid updating your working directory, to isolate yourself 333from possibly destabilizing changes other people are making. You can, 334of course, just refrain from running `cvs update'. But if you want to 335avoid updating only a portion of a larger tree, then sticky tags can 336help. If you check out a certain revision (such as 1.4) it will become 337sticky. Subsequent `cvs update' commands will not retrieve the latest 338revision until you reset the tag with `cvs update -A'. Likewise, use 339of the `-D' option to `update' or `checkout' sets a "sticky date", 340which, similarly, causes that date to be used for future retrievals. 341 342 People often want to retrieve an old version of a file without 343setting a sticky tag. This can be done with the `-p' option to 344`checkout' or `update', which sends the contents of the file to 345standard output. For example: 346 $ cvs update -p -r 1.1 file1 >file1 347 =================================================================== 348 Checking out file1 349 RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v 350 VERS: 1.1 351 *************** 352 $ 353 354 However, this isn't the easiest way, if you are asking how to undo a 355previous checkin (in this example, put `file1' back to the way it was 356as of revision 1.1). In that case you are better off using the `-j' 357option to `update'; for further discussion see *Note Merging two 358revisions::. 359 360 361File: cvs.info, Node: Branching and merging, Next: Recursive behavior, Prev: Revisions, Up: Top 362 363Branching and merging 364********************* 365 366 CVS allows you to isolate changes onto a separate line of 367development, known as a "branch". When you change files on a branch, 368those changes do not appear on the main trunk or other branches. 369 370 Later you can move changes from one branch to another branch (or the 371main trunk) by "merging". Merging involves first running `cvs update 372-j', to merge the changes into the working directory. You can then 373commit that revision, and thus effectively copy the changes onto 374another branch. 375 376* Menu: 377 378* Branches motivation:: What branches are good for 379* Creating a branch:: Creating a branch 380* Accessing branches:: Checking out and updating branches 381* Branches and revisions:: Branches are reflected in revision numbers 382* Magic branch numbers:: Magic branch numbers 383* Merging a branch:: Merging an entire branch 384* Merging more than once:: Merging from a branch several times 385* Merging two revisions:: Merging differences between two revisions 386* Merging adds and removals:: What if files are added or removed? 387* Merging and keywords:: Avoiding conflicts due to keyword substitution 388 389 390File: cvs.info, Node: Branches motivation, Next: Creating a branch, Up: Branching and merging 391 392What branches are good for 393========================== 394 395 Suppose that release 1.0 of tc has been made. You are continuing to 396develop tc, planning to create release 1.1 in a couple of months. 397After a while your customers start to complain about a fatal bug. You 398check out release 1.0 (*note Tags::) and find the bug (which turns out 399to have a trivial fix). However, the current revision of the sources 400are in a state of flux and are not expected to be stable for at least 401another month. There is no way to make a bugfix release based on the 402newest sources. 403 404 The thing to do in a situation like this is to create a "branch" on 405the revision trees for all the files that make up release 1.0 of tc. 406You can then make modifications to the branch without disturbing the 407main trunk. When the modifications are finished you can elect to 408either incorporate them on the main trunk, or leave them on the branch. 409 410 411File: cvs.info, Node: Creating a branch, Next: Accessing branches, Prev: Branches motivation, Up: Branching and merging 412 413Creating a branch 414================= 415 416 You can create a branch with `tag -b'; for example, assuming you're 417in a working copy: 418 419 $ cvs tag -b rel-1-0-patches 420 421 This splits off a branch based on the current revisions in the 422working copy, assigning that branch the name `rel-1-0-patches'. 423 424 It is important to understand that branches get created in the 425repository, not in the working copy. Creating a branch based on 426current revisions, as the above example does, will _not_ automatically 427switch the working copy to be on the new branch. For information on how 428to do that, see *Note Accessing branches::. 429 430 You can also create a branch without reference to any working copy, 431by using `rtag': 432 433 $ cvs rtag -b -r rel-1-0 rel-1-0-patches tc 434 435 `-r rel-1-0' says that this branch should be rooted at the revision 436that corresponds to the tag `rel-1-0'. It need not be the most recent 437revision - it's often useful to split a branch off an old revision (for 438example, when fixing a bug in a past release otherwise known to be 439stable). 440 441 As with `tag', the `-b' flag tells `rtag' to create a branch (rather 442than just a symbolic revision name). Note that the numeric revision 443number that matches `rel-1-0' will probably be different from file to 444file. 445 446 So, the full effect of the command is to create a new branch - named 447`rel-1-0-patches' - in module `tc', rooted in the revision tree at the 448point tagged by `rel-1-0'. 449 450 451File: cvs.info, Node: Accessing branches, Next: Branches and revisions, Prev: Creating a branch, Up: Branching and merging 452 453Accessing branches 454================== 455 456 You can retrieve a branch in one of two ways: by checking it out 457fresh from the repository, or by switching an existing working copy 458over to the branch. 459 460 To check out a branch from the repository, invoke `checkout' with 461the `-r' flag, followed by the tag name of the branch (*note Creating a 462branch::): 463 464 $ cvs checkout -r rel-1-0-patches tc 465 466 Or, if you already have a working copy, you can switch it to a given 467branch with `update -r': 468 469 $ cvs update -r rel-1-0-patches tc 470 471 or equivalently: 472 473 $ cd tc 474 $ cvs update -r rel-1-0-patches 475 476 It does not matter if the working copy was originally on the main 477trunk or on some other branch - the above command will switch it to the 478named branch. And similarly to a regular `update' command, `update -r' 479merges any changes you have made, notifying you of conflicts where they 480occur. 481 482 Once you have a working copy tied to a particular branch, it remains 483there until you tell it otherwise. This means that changes checked in 484from the working copy will add new revisions on that branch, while 485leaving the main trunk and other branches unaffected. 486 487 To find out what branch a working copy is on, you can use the 488`status' command. In its output, look for the field named `Sticky tag' 489(*note Sticky tags::) - that's CVS's way of telling you the branch, if 490any, of the current working files: 491 492 $ cvs status -v driver.c backend.c 493 =================================================================== 494 File: driver.c Status: Up-to-date 495 496 Version: 1.7 Sat Dec 5 18:25:54 1992 497 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v 498 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 499 Sticky Date: (none) 500 Sticky Options: (none) 501 502 Existing Tags: 503 rel-1-0-patches (branch: 1.7.2) 504 rel-1-0 (revision: 1.7) 505 506 =================================================================== 507 File: backend.c Status: Up-to-date 508 509 Version: 1.4 Tue Dec 1 14:39:01 1992 510 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 511 Sticky Tag: rel-1-0-patches (branch: 1.4.2) 512 Sticky Date: (none) 513 Sticky Options: (none) 514 515 Existing Tags: 516 rel-1-0-patches (branch: 1.4.2) 517 rel-1-0 (revision: 1.4) 518 rel-0-4 (revision: 1.4) 519 520 Don't be confused by the fact that the branch numbers for each file 521are different (`1.7.2' and `1.4.2' respectively). The branch tag is the 522same, `rel-1-0-patches', and the files are indeed on the same branch. 523The numbers simply reflect the point in each file's revision history at 524which the branch was made. In the above example, one can deduce that 525`driver.c' had been through more changes than `backend.c' before this 526branch was created. 527 528 See *Note Branches and revisions:: for details about how branch 529numbers are constructed. 530 531 532File: cvs.info, Node: Branches and revisions, Next: Magic branch numbers, Prev: Accessing branches, Up: Branching and merging 533 534Branches and revisions 535====================== 536 537 Ordinarily, a file's revision history is a linear series of 538increments (*note Revision numbers::): 539 540 +-----+ +-----+ +-----+ +-----+ +-----+ 541 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 542 +-----+ +-----+ +-----+ +-----+ +-----+ 543 544 However, CVS is not limited to linear development. The "revision 545tree" can be split into "branches", where each branch is a 546self-maintained line of development. Changes made on one branch can 547easily be moved back to the main trunk. 548 549 Each branch has a "branch number", consisting of an odd number of 550period-separated decimal integers. The branch number is created by 551appending an integer to the revision number where the corresponding 552branch forked off. Having branch numbers allows more than one branch 553to be forked off from a certain revision. 554 555 All revisions on a branch have revision numbers formed by appending 556an ordinal number to the branch number. The following figure 557illustrates branching with an example. 558 559 +-------------+ 560 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! 561 / +-------------+ 562 / 563 / 564 +---------+ +---------+ +---------+ 565 Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 566 / +---------+ +---------+ +---------+ 567 / 568 / 569 +-----+ +-----+ +-----+ +-----+ +-----+ 570 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 571 +-----+ +-----+ +-----+ +-----+ +-----+ 572 ! 573 ! 574 ! +---------+ +---------+ +---------+ 575 Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! 576 +---------+ +---------+ +---------+ 577 578 The exact details of how the branch number is constructed is not 579something you normally need to be concerned about, but here is how it 580works: When CVS creates a branch number it picks the first unused even 581integer, starting with 2. So when you want to create a branch from 582revision 6.4 it will be numbered 6.4.2. All branch numbers ending in a 583zero (such as 6.4.0) are used internally by CVS (*note Magic branch 584numbers::). The branch 1.1.1 has a special meaning. *Note Tracking 585sources::. 586 587 588File: cvs.info, Node: Magic branch numbers, Next: Merging a branch, Prev: Branches and revisions, Up: Branching and merging 589 590Magic branch numbers 591==================== 592 593 This section describes a CVS feature called "magic branches". For 594most purposes, you need not worry about magic branches; CVS handles 595them for you. However, they are visible to you in certain 596circumstances, so it may be useful to have some idea of how it works. 597 598 Externally, branch numbers consist of an odd number of dot-separated 599decimal integers. *Note Revision numbers::. That is not the whole 600truth, however. For efficiency reasons CVS sometimes inserts an extra 0 601in the second rightmost position (1.2.4 becomes 1.2.0.4, 8.9.10.11.12 602becomes 8.9.10.11.0.12 and so on). 603 604 CVS does a pretty good job at hiding these so called magic branches, 605but in a few places the hiding is incomplete: 606 607 * The magic branch number appears in the output from `cvs log'. 608 609 * You cannot specify a symbolic branch name to `cvs admin'. 610 611 612 You can use the `admin' command to reassign a symbolic name to a 613branch the way RCS expects it to be. If `R4patches' is assigned to the 614branch 1.4.2 (magic branch number 1.4.0.2) in file `numbers.c' you can 615do this: 616 617 $ cvs admin -NR4patches:1.4.2 numbers.c 618 619 It only works if at least one revision is already committed on the 620branch. Be very careful so that you do not assign the tag to the wrong 621number. (There is no way to see how the tag was assigned yesterday). 622 623 624File: cvs.info, Node: Merging a branch, Next: Merging more than once, Prev: Magic branch numbers, Up: Branching and merging 625 626Merging an entire branch 627======================== 628 629 You can merge changes made on a branch into your working copy by 630giving the `-j BRANCH' flag to the `update' command. With one `-j 631BRANCH' option it merges the changes made between the point where the 632branch forked and newest revision on that branch (into your working 633copy). 634 635 The `-j' stands for "join". 636 637 Consider this revision tree: 638 639 +-----+ +-----+ +-----+ +-----+ 640 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk 641 +-----+ +-----+ +-----+ +-----+ 642 ! 643 ! 644 ! +---------+ +---------+ 645 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 646 +---------+ +---------+ 647 648The branch 1.2.2 has been given the tag (symbolic name) `R1fix'. The 649following example assumes that the module `mod' contains only one file, 650`m.c'. 651 652 $ cvs checkout mod # Retrieve the latest revision, 1.4 653 654 $ cvs update -j R1fix m.c # Merge all changes made on the branch, 655 # i.e. the changes between revision 1.2 656 # and 1.2.2.2, into your working copy 657 # of the file. 658 659 $ cvs commit -m "Included R1fix" # Create revision 1.5. 660 661 A conflict can result from a merge operation. If that happens, you 662should resolve it before committing the new revision. *Note Conflicts 663example::. 664 665 If your source files contain keywords (*note Keyword substitution::), 666you might be getting more conflicts than strictly necessary. See *Note 667Merging and keywords::, for information on how to avoid this. 668 669 The `checkout' command also supports the `-j BRANCH' flag. The same 670effect as above could be achieved with this: 671 672 $ cvs checkout -j R1fix mod 673 $ cvs commit -m "Included R1fix" 674 675 676File: cvs.info, Node: Merging more than once, Next: Merging two revisions, Prev: Merging a branch, Up: Branching and merging 677 678Merging from a branch several times 679=================================== 680 681 Continuing our example, the revision tree now looks like this: 682 683 +-----+ +-----+ +-----+ +-----+ +-----+ 684 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 685 +-----+ +-----+ +-----+ +-----+ +-----+ 686 ! * 687 ! * 688 ! +---------+ +---------+ 689 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 690 +---------+ +---------+ 691 692 where the starred line represents the merge from the `R1fix' branch 693to the main trunk, as just discussed. 694 695 Now suppose that development continues on the `R1fix' branch: 696 697 +-----+ +-----+ +-----+ +-----+ +-----+ 698 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 699 +-----+ +-----+ +-----+ +-----+ +-----+ 700 ! * 701 ! * 702 ! +---------+ +---------+ +---------+ 703 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 704 +---------+ +---------+ +---------+ 705 706 and then you want to merge those new changes onto the main trunk. 707If you just use the `cvs update -j R1fix m.c' command again, CVS will 708attempt to merge again the changes which you have already merged, which 709can have undesirable side effects. 710 711 So instead you need to specify that you only want to merge the 712changes on the branch which have not yet been merged into the trunk. 713To do that you specify two `-j' options, and CVS merges the changes from 714the first revision to the second revision. For example, in this case 715the simplest way would be 716 717 cvs update -j 1.2.2.2 -j R1fix m.c # Merge changes from 1.2.2.2 to the 718 # head of the R1fix branch 719 720 The problem with this is that you need to specify the 1.2.2.2 721revision manually. A slightly better approach might be to use the date 722the last merge was done: 723 724 cvs update -j R1fix:yesterday -j R1fix m.c 725 726 Better yet, tag the R1fix branch after every merge into the trunk, 727and then use that tag for subsequent merges: 728 729 cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 730 731 732File: cvs.info, Node: Merging two revisions, Next: Merging adds and removals, Prev: Merging more than once, Up: Branching and merging 733 734Merging differences between any two revisions 735============================================= 736 737 With two `-j REVISION' flags, the `update' (and `checkout') command 738can merge the differences between any two revisions into your working 739file. 740 741 $ cvs update -j 1.5 -j 1.3 backend.c 742 743will undo all changes made between revision 1.3 and 1.5. Note the 744order of the revisions! 745 746 If you try to use this option when operating on multiple files, 747remember that the numeric revisions will probably be very different 748between the various files. You almost always use symbolic tags rather 749than revision numbers when operating on multiple files. 750 751 Specifying two `-j' options can also undo file removals or 752additions. For example, suppose you have a file named `file1' which 753existed as revision 1.1, and you then removed it (thus adding a dead 754revision 1.2). Now suppose you want to add it again, with the same 755contents it had previously. Here is how to do it: 756 757 $ cvs update -j 1.2 -j 1.1 file1 758 U file1 759 $ cvs commit -m test 760 Checking in file1; 761 /tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 762 new revision: 1.3; previous revision: 1.2 763 done 764 $ 765 766 767File: cvs.info, Node: Merging adds and removals, Next: Merging and keywords, Prev: Merging two revisions, Up: Branching and merging 768 769Merging can add or remove files 770=============================== 771 772 If the changes which you are merging involve removing or adding some 773files, `update -j' will reflect such additions or removals. 774 775 For example: 776 cvs update -A 777 touch a b c 778 cvs add a b c ; cvs ci -m "added" a b c 779 cvs tag -b branchtag 780 cvs update -r branchtag 781 touch d ; cvs add d 782 rm a ; cvs rm a 783 cvs ci -m "added d, removed a" 784 cvs update -A 785 cvs update -jbranchtag 786 787 After these commands are executed and a `cvs commit' is done, file 788`a' will be removed and file `d' added in the main branch. 789 790 791File: cvs.info, Node: Merging and keywords, Prev: Merging adds and removals, Up: Branching and merging 792 793Merging and keywords 794==================== 795 796 If you merge files containing keywords (*note Keyword 797substitution::), you will normally get numerous conflicts during the 798merge, because the keywords are expanded differently in the revisions 799which you are merging. 800 801 Therefore, you will often want to specify the `-kk' (*note 802Substitution modes::) switch to the merge command line. By 803substituting just the name of the keyword, not the expanded value of 804that keyword, this option ensures that the revisions which you are 805merging will be the same as each other, and avoid spurious conflicts. 806 807 For example, suppose you have a file like this: 808 809 +---------+ 810 _! 1.1.2.1 ! <- br1 811 / +---------+ 812 / 813 / 814 +-----+ +-----+ 815 ! 1.1 !----! 1.2 ! 816 +-----+ +-----+ 817 818 and your working directory is currently on the trunk (revision 1.2). 819Then you might get the following results from a merge: 820 821 $ cat file1 822 key $Revision: 1.1.1.17 $ 823 . . . 824 $ cvs update -j br1 825 U file1 826 RCS file: /cvsroot/first-dir/file1,v 827 retrieving revision 1.1 828 retrieving revision 1.1.2.1 829 Merging differences between 1.1 and 1.1.2.1 into file1 830 rcsmerge: warning: conflicts during merge 831 $ cat file1 832 <<<<<<< file1 833 key $Revision: 1.1.1.17 $ 834 ======= 835 key $Revision: 1.1.1.17 $ 836 >>>>>>> 1.1.2.1 837 . . . 838 839 What happened was that the merge tried to merge the differences 840between 1.1 and 1.1.2.1 into your working directory. So, since the 841keyword changed from `Revision: 1.1' to `Revision: 1.1.2.1', CVS tried 842to merge that change into your working directory, which conflicted with 843the fact that your working directory had contained `Revision: 1.2'. 844 845 Here is what happens if you had used `-kk': 846 847 $ cat file1 848 key $Revision: 1.1.1.17 $ 849 . . . 850 $ cvs update -kk -j br1 851 U file1 852 RCS file: /cvsroot/first-dir/file1,v 853 retrieving revision 1.1 854 retrieving revision 1.1.2.1 855 Merging differences between 1.1 and 1.1.2.1 into file1 856 $ cat file1 857 key $Revision: 1.1.1.17 $ 858 . . . 859 860 What is going on here is that revision 1.1 and 1.1.2.1 both expand 861as plain `Revision', and therefore merging the changes between them 862into the working directory need not change anything. Therefore, there 863is no conflict. 864 865 There is, however, one major caveat with using `-kk' on merges. 866Namely, it overrides whatever keyword expansion mode CVS would normally 867have used. In particular, this is a problem if the mode had been `-kb' 868for a binary file. Therefore, if your repository contains binary 869files, you will need to deal with the conflicts rather than using `-kk'. 870 871 872File: cvs.info, Node: Recursive behavior, Next: Adding and removing, Prev: Branching and merging, Up: Top 873 874Recursive behavior 875****************** 876 877 Almost all of the subcommands of CVS work recursively when you 878specify a directory as an argument. For instance, consider this 879directory structure: 880 881 `$HOME' 882 | 883 +--tc 884 | | 885 +--CVS 886 | (internal CVS files) 887 +--Makefile 888 +--backend.c 889 +--driver.c 890 +--frontend.c 891 +--parser.c 892 +--man 893 | | 894 | +--CVS 895 | | (internal CVS files) 896 | +--tc.1 897 | 898 +--testing 899 | 900 +--CVS 901 | (internal CVS files) 902 +--testpgm.t 903 +--test2.t 904 905If `tc' is the current working directory, the following is true: 906 907 * `cvs update testing' is equivalent to 908 909 cvs update testing/testpgm.t testing/test2.t 910 911 * `cvs update testing man' updates all files in the subdirectories 912 913 * `cvs update .' or just `cvs update' updates all files in the `tc' 914 directory 915 916 If no arguments are given to `update' it will update all files in 917the current working directory and all its subdirectories. In other 918words, `.' is a default argument to `update'. This is also true for 919most of the CVS subcommands, not only the `update' command. 920 921 The recursive behavior of the CVS subcommands can be turned off with 922the `-l' option. Conversely, the `-R' option can be used to force 923recursion if `-l' is specified in `~/.cvsrc' (*note ~/.cvsrc::). 924 925 $ cvs update -l # Don't update files in subdirectories 926 927 928File: cvs.info, Node: Adding and removing, Next: History browsing, Prev: Recursive behavior, Up: Top 929 930Adding, removing, and renaming files and directories 931**************************************************** 932 933 In the course of a project, one will often add new files. Likewise 934with removing or renaming, or with directories. The general concept to 935keep in mind in all these cases is that instead of making an 936irreversible change you want CVS to record the fact that a change has 937taken place, just as with modifying an existing file. The exact 938mechanisms to do this in CVS vary depending on the situation. 939 940* Menu: 941 942* Adding files:: Adding files 943* Removing files:: Removing files 944* Removing directories:: Removing directories 945* Moving files:: Moving and renaming files 946* Moving directories:: Moving and renaming directories 947 948 949File: cvs.info, Node: Adding files, Next: Removing files, Up: Adding and removing 950 951Adding files to a directory 952=========================== 953 954 To add a new file to a directory, follow these steps. 955 956 * You must have a working copy of the directory. *Note Getting the 957 source::. 958 959 * Create the new file inside your working copy of the directory. 960 961 * Use `cvs add FILENAME' to tell CVS that you want to version 962 control the file. If the file contains binary data, specify `-kb' 963 (*note Binary files::). 964 965 * Use `cvs commit FILENAME' to actually check in the file into the 966 repository. Other developers cannot see the file until you 967 perform this step. 968 969 You can also use the `add' command to add a new directory. 970 971 Unlike most other commands, the `add' command is not recursive. You 972cannot even type `cvs add foo/bar'! Instead, you have to 973 974 $ cd foo 975 $ cvs add bar 976 977 - Command: cvs add [`-k' kflag] [`-m' message] files ... 978 Schedule FILES to be added to the repository. The files or 979 directories specified with `add' must already exist in the current 980 directory. To add a whole new directory hierarchy to the source 981 repository (for example, files received from a third-party 982 vendor), use the `import' command instead. *Note import::. 983 984 The added files are not placed in the source repository until you 985 use `commit' to make the change permanent. Doing an `add' on a 986 file that was removed with the `remove' command will undo the 987 effect of the `remove', unless a `commit' command intervened. 988 *Note Removing files::, for an example. 989 990 The `-k' option specifies the default way that this file will be 991 checked out; for more information see *Note Substitution modes::. 992 993 The `-m' option specifies a description for the file. This 994 description appears in the history log (if it is enabled, *note 995 history file::). It will also be saved in the version history 996 inside the repository when the file is committed. The `log' 997 command displays this description. The description can be changed 998 using `admin -t'. *Note admin::. If you omit the `-m 999 DESCRIPTION' flag, an empty string will be used. You will not be 1000 prompted for a description. 1001 1002 For example, the following commands add the file `backend.c' to the 1003repository: 1004 1005 $ cvs add backend.c 1006 $ cvs commit -m "Early version. Not yet compilable." backend.c 1007 1008 When you add a file it is added only on the branch which you are 1009working on (*note Branching and merging::). You can later merge the 1010additions to another branch if you want (*note Merging adds and 1011removals::). 1012 1013 1014File: cvs.info, Node: Removing files, Next: Removing directories, Prev: Adding files, Up: Adding and removing 1015 1016Removing files 1017============== 1018 1019 Directories change. New files are added, and old files disappear. 1020Still, you want to be able to retrieve an exact copy of old releases. 1021 1022 Here is what you can do to remove a file, but remain able to 1023retrieve old revisions: 1024 1025 * Make sure that you have not made any uncommitted modifications to 1026 the file. *Note Viewing differences::, for one way to do that. 1027 You can also use the `status' or `update' command. If you remove 1028 the file without committing your changes, you will of course not 1029 be able to retrieve the file as it was immediately before you 1030 deleted it. 1031 1032 * Remove the file from your working copy of the directory. You can 1033 for instance use `rm'. 1034 1035 * Use `cvs remove FILENAME' to tell CVS that you really want to 1036 delete the file. 1037 1038 * Use `cvs commit FILENAME' to actually perform the removal of the 1039 file from the repository. 1040 1041 When you commit the removal of the file, CVS records the fact that 1042the file no longer exists. It is possible for a file to exist on only 1043some branches and not on others, or to re-add another file with the same 1044name later. CVS will correctly create or not create the file, based on 1045the `-r' and `-D' options specified to `checkout' or `update'. 1046 1047 - Command: cvs remove [options] files ... 1048 Schedule file(s) to be removed from the repository (files which 1049 have not already been removed from the working directory are not 1050 processed). This command does not actually remove the file from 1051 the repository until you commit the removal. For a full list of 1052 options, see *Note Invoking CVS::. 1053 1054 Here is an example of removing several files: 1055 1056 $ cd test 1057 $ rm *.c 1058 $ cvs remove 1059 cvs remove: Removing . 1060 cvs remove: scheduling a.c for removal 1061 cvs remove: scheduling b.c for removal 1062 cvs remove: use 'cvs commit' to remove these files permanently 1063 $ cvs ci -m "Removed unneeded files" 1064 cvs commit: Examining . 1065 cvs commit: Committing . 1066 1067 As a convenience you can remove the file and `cvs remove' it in one 1068step, by specifying the `-f' option. For example, the above example 1069could also be done like this: 1070 1071 $ cd test 1072 $ cvs remove -f *.c 1073 cvs remove: scheduling a.c for removal 1074 cvs remove: scheduling b.c for removal 1075 cvs remove: use 'cvs commit' to remove these files permanently 1076 $ cvs ci -m "Removed unneeded files" 1077 cvs commit: Examining . 1078 cvs commit: Committing . 1079 1080 If you execute `remove' for a file, and then change your mind before 1081you commit, you can undo the `remove' with an `add' command. 1082 1083 $ ls 1084 CVS ja.h oj.c 1085 $ rm oj.c 1086 $ cvs remove oj.c 1087 cvs remove: scheduling oj.c for removal 1088 cvs remove: use 'cvs commit' to remove this file permanently 1089 $ cvs add oj.c 1090 U oj.c 1091 cvs add: oj.c, version 1.1.1.1, resurrected 1092 1093 If you realize your mistake before you run the `remove' command you 1094can use `update' to resurrect the file: 1095 1096 $ rm oj.c 1097 $ cvs update oj.c 1098 cvs update: warning: oj.c was lost 1099 U oj.c 1100 1101 When you remove a file it is removed only on the branch which you 1102are working on (*note Branching and merging::). You can later merge 1103the removals to another branch if you want (*note Merging adds and 1104removals::). 1105 1106 1107File: cvs.info, Node: Removing directories, Next: Moving files, Prev: Removing files, Up: Adding and removing 1108 1109Removing directories 1110==================== 1111 1112 In concept removing directories is somewhat similar to removing 1113files--you want the directory to not exist in your current working 1114directories, but you also want to be able to retrieve old releases in 1115which the directory existed. 1116 1117 The way that you remove a directory is to remove all the files in 1118it. You don't remove the directory itself; there is no way to do that. 1119Instead you specify the `-P' option to `cvs update' or `cvs checkout', 1120which will cause CVS to remove empty directories from working 1121directories. (Note that `cvs export' always removes empty directories.) 1122Probably the best way to do this is to always specify `-P'; if you want 1123an empty directory then put a dummy file (for example `.keepme') in it 1124to prevent `-P' from removing it. 1125 1126 Note that `-P' is implied by the `-r' or `-D' options of `checkout'. 1127This way CVS will be able to correctly create the directory or not 1128depending on whether the particular version you are checking out 1129contains any files in that directory. 1130 1131 1132File: cvs.info, Node: Moving files, Next: Moving directories, Prev: Removing directories, Up: Adding and removing 1133 1134Moving and renaming files 1135========================= 1136 1137 Moving files to a different directory or renaming them is not 1138difficult, but some of the ways in which this works may be non-obvious. 1139(Moving or renaming a directory is even harder. *Note Moving 1140directories::.). 1141 1142 The examples below assume that the file OLD is renamed to NEW. 1143 1144* Menu: 1145 1146* Outside:: The normal way to Rename 1147* Inside:: A tricky, alternative way 1148* Rename by copying:: Another tricky, alternative way 1149 1150 1151File: cvs.info, Node: Outside, Next: Inside, Up: Moving files 1152 1153The Normal way to Rename 1154------------------------ 1155 1156 The normal way to move a file is to copy OLD to NEW, and then issue 1157the normal CVS commands to remove OLD from the repository, and add NEW 1158to it. 1159 1160 $ mv OLD NEW 1161 $ cvs remove OLD 1162 $ cvs add NEW 1163 $ cvs commit -m "Renamed OLD to NEW" OLD NEW 1164 1165 This is the simplest way to move a file, it is not error-prone, and 1166it preserves the history of what was done. Note that to access the 1167history of the file you must specify the old or the new name, depending 1168on what portion of the history you are accessing. For example, `cvs 1169log OLD' will give the log up until the time of the rename. 1170 1171 When NEW is committed its revision numbers will start again, usually 1172at 1.1, so if that bothers you, use the `-r rev' option to commit. For 1173more information see *Note Assigning revisions::. 1174 1175 1176File: cvs.info, Node: Inside, Next: Rename by copying, Prev: Outside, Up: Moving files 1177 1178Moving the history file 1179----------------------- 1180 1181 This method is more dangerous, since it involves moving files inside 1182the repository. Read this entire section before trying it out! 1183 1184 $ cd $CVSROOT/DIR 1185 $ mv OLD,v NEW,v 1186 1187Advantages: 1188 1189 * The log of changes is maintained intact. 1190 1191 * The revision numbers are not affected. 1192 1193Disadvantages: 1194 1195 * Old releases cannot easily be fetched from the repository. (The 1196 file will show up as NEW even in revisions from the time before it 1197 was renamed). 1198 1199 * There is no log information of when the file was renamed. 1200 1201 * Nasty things might happen if someone accesses the history file 1202 while you are moving it. Make sure no one else runs any of the CVS 1203 commands while you move it. 1204 1205 1206File: cvs.info, Node: Rename by copying, Prev: Inside, Up: Moving files 1207 1208Copying the history file 1209------------------------ 1210 1211 This way also involves direct modifications to the repository. It 1212is safe, but not without drawbacks. 1213 1214 # Copy the RCS file inside the repository 1215 $ cd $CVSROOT/DIR 1216 $ cp OLD,v NEW,v 1217 # Remove the old file 1218 $ cd ~/DIR 1219 $ rm OLD 1220 $ cvs remove OLD 1221 $ cvs commit OLD 1222 # Remove all tags from NEW 1223 $ cvs update NEW 1224 $ cvs log NEW # Remember the non-branch tag names 1225 $ cvs tag -d TAG1 NEW 1226 $ cvs tag -d TAG2 NEW 1227 ... 1228 1229 By removing the tags you will be able to check out old revisions. 1230 1231Advantages: 1232 1233 * Checking out old revisions works correctly, as long as you use 1234 `-rTAG' and not `-DDATE' to retrieve the revisions. 1235 1236 * The log of changes is maintained intact. 1237 1238 * The revision numbers are not affected. 1239 1240Disadvantages: 1241 1242 * You cannot easily see the history of the file across the rename. 1243 1244 1245