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 BRANCHNAME' flag to the `update' subcommand. With one 631`-j BRANCHNAME' option it merges the changes made between the point 632where the branch forked and newest revision on that branch (into your 633working copy). 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 BRANCHNAME' flag. The 670same effect as above could be achieved with this: 671 672 $ cvs checkout -j R1fix mod 673 $ cvs commit -m "Included R1fix" 674 675 It should be noted that `update -j TAGNAME' will also work but may 676not produce the desired result. *Note Merging adds and removals::, for 677more. 678 679 680File: cvs.info, Node: Merging more than once, Next: Merging two revisions, Prev: Merging a branch, Up: Branching and merging 681 682Merging from a branch several times 683=================================== 684 685 Continuing our example, the revision tree now looks like this: 686 687 +-----+ +-----+ +-----+ +-----+ +-----+ 688 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 689 +-----+ +-----+ +-----+ +-----+ +-----+ 690 ! * 691 ! * 692 ! +---------+ +---------+ 693 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 694 +---------+ +---------+ 695 696 where the starred line represents the merge from the `R1fix' branch 697to the main trunk, as just discussed. 698 699 Now suppose that development continues on the `R1fix' branch: 700 701 +-----+ +-----+ +-----+ +-----+ +-----+ 702 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 703 +-----+ +-----+ +-----+ +-----+ +-----+ 704 ! * 705 ! * 706 ! +---------+ +---------+ +---------+ 707 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 708 +---------+ +---------+ +---------+ 709 710 and then you want to merge those new changes onto the main trunk. 711If you just use the `cvs update -j R1fix m.c' command again, CVS will 712attempt to merge again the changes which you have already merged, which 713can have undesirable side effects. 714 715 So instead you need to specify that you only want to merge the 716changes on the branch which have not yet been merged into the trunk. 717To do that you specify two `-j' options, and CVS merges the changes from 718the first revision to the second revision. For example, in this case 719the simplest way would be 720 721 cvs update -j 1.2.2.2 -j R1fix m.c # Merge changes from 1.2.2.2 to the 722 # head of the R1fix branch 723 724 The problem with this is that you need to specify the 1.2.2.2 725revision manually. A slightly better approach might be to use the date 726the last merge was done: 727 728 cvs update -j R1fix:yesterday -j R1fix m.c 729 730 Better yet, tag the R1fix branch after every merge into the trunk, 731and then use that tag for subsequent merges: 732 733 cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 734 735 736File: cvs.info, Node: Merging two revisions, Next: Merging adds and removals, Prev: Merging more than once, Up: Branching and merging 737 738Merging differences between any two revisions 739============================================= 740 741 With two `-j REVISION' flags, the `update' (and `checkout') command 742can merge the differences between any two revisions into your working 743file. 744 745 $ cvs update -j 1.5 -j 1.3 backend.c 746 747will undo all changes made between revision 1.3 and 1.5. Note the 748order of the revisions! 749 750 If you try to use this option when operating on multiple files, 751remember that the numeric revisions will probably be very different 752between the various files. You almost always use symbolic tags rather 753than revision numbers when operating on multiple files. 754 755 Specifying two `-j' options can also undo file removals or 756additions. For example, suppose you have a file named `file1' which 757existed as revision 1.1, and you then removed it (thus adding a dead 758revision 1.2). Now suppose you want to add it again, with the same 759contents it had previously. Here is how to do it: 760 761 $ cvs update -j 1.2 -j 1.1 file1 762 U file1 763 $ cvs commit -m test 764 Checking in file1; 765 /tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 766 new revision: 1.3; previous revision: 1.2 767 done 768 $ 769 770 771File: cvs.info, Node: Merging adds and removals, Next: Merging and keywords, Prev: Merging two revisions, Up: Branching and merging 772 773Merging can add or remove files 774=============================== 775 776 If the changes which you are merging involve removing or adding some 777files, `update -j' will reflect such additions or removals. 778 779 For example: 780 cvs update -A 781 touch a b c 782 cvs add a b c ; cvs ci -m "added" a b c 783 cvs tag -b branchtag 784 cvs update -r branchtag 785 touch d ; cvs add d 786 rm a ; cvs rm a 787 cvs ci -m "added d, removed a" 788 cvs update -A 789 cvs update -jbranchtag 790 791 After these commands are executed and a `cvs commit' is done, file 792`a' will be removed and file `d' added in the main branch. 793 794 Note that using a single static tag (`-j TAGNAME') rather than a 795dynamic tag (`-j BRANCHNAME') to merge changes from a branch will 796usually not remove files which were removed on the branch since CVS 797does not automatically add static tags to dead revisions. The 798exception to this rule occurs when a static tag has been attached to a 799dead revision manually. Use the branch tag to merge all changes from 800the branch or use two static tags as merge endpoints to be sure that 801all intended changes are propogated in the merge. 802 803 804File: cvs.info, Node: Merging and keywords, Prev: Merging adds and removals, Up: Branching and merging 805 806Merging and keywords 807==================== 808 809 If you merge files containing keywords (*note Keyword 810substitution::), you will normally get numerous conflicts during the 811merge, because the keywords are expanded differently in the revisions 812which you are merging. 813 814 Therefore, you will often want to specify the `-kk' (*note 815Substitution modes::) switch to the merge command line. By 816substituting just the name of the keyword, not the expanded value of 817that keyword, this option ensures that the revisions which you are 818merging will be the same as each other, and avoid spurious conflicts. 819 820 For example, suppose you have a file like this: 821 822 +---------+ 823 _! 1.1.2.1 ! <- br1 824 / +---------+ 825 / 826 / 827 +-----+ +-----+ 828 ! 1.1 !----! 1.2 ! 829 +-----+ +-----+ 830 831 and your working directory is currently on the trunk (revision 1.2). 832Then you might get the following results from a merge: 833 834 $ cat file1 835 key $Revision: 1.3 $ 836 . . . 837 $ cvs update -j br1 838 U file1 839 RCS file: /cvsroot/first-dir/file1,v 840 retrieving revision 1.1 841 retrieving revision 1.1.2.1 842 Merging differences between 1.1 and 1.1.2.1 into file1 843 rcsmerge: warning: conflicts during merge 844 $ cat file1 845 <<<<<<< file1 846 key $Revision: 1.3 $ 847 ======= 848 key $Revision: 1.3 $ 849 >>>>>>> 1.1.2.1 850 . . . 851 852 What happened was that the merge tried to merge the differences 853between 1.1 and 1.1.2.1 into your working directory. So, since the 854keyword changed from `Revision: 1.1' to `Revision: 1.1.2.1', CVS tried 855to merge that change into your working directory, which conflicted with 856the fact that your working directory had contained `Revision: 1.2'. 857 858 Here is what happens if you had used `-kk': 859 860 $ cat file1 861 key $Revision: 1.3 $ 862 . . . 863 $ cvs update -kk -j br1 864 U file1 865 RCS file: /cvsroot/first-dir/file1,v 866 retrieving revision 1.1 867 retrieving revision 1.1.2.1 868 Merging differences between 1.1 and 1.1.2.1 into file1 869 $ cat file1 870 key $Revision: 1.3 $ 871 . . . 872 873 What is going on here is that revision 1.1 and 1.1.2.1 both expand 874as plain `Revision', and therefore merging the changes between them 875into the working directory need not change anything. Therefore, there 876is no conflict. 877 878 There is, however, one major caveat with using `-kk' on merges. 879Namely, it overrides whatever keyword expansion mode CVS would normally 880have used. In particular, this is a problem if the mode had been `-kb' 881for a binary file. Therefore, if your repository contains binary 882files, you will need to deal with the conflicts rather than using `-kk'. 883 884 885File: cvs.info, Node: Recursive behavior, Next: Adding and removing, Prev: Branching and merging, Up: Top 886 887Recursive behavior 888****************** 889 890 Almost all of the subcommands of CVS work recursively when you 891specify a directory as an argument. For instance, consider this 892directory structure: 893 894 `$HOME' 895 | 896 +--tc 897 | | 898 +--CVS 899 | (internal CVS files) 900 +--Makefile 901 +--backend.c 902 +--driver.c 903 +--frontend.c 904 +--parser.c 905 +--man 906 | | 907 | +--CVS 908 | | (internal CVS files) 909 | +--tc.1 910 | 911 +--testing 912 | 913 +--CVS 914 | (internal CVS files) 915 +--testpgm.t 916 +--test2.t 917 918If `tc' is the current working directory, the following is true: 919 920 * `cvs update testing' is equivalent to 921 922 cvs update testing/testpgm.t testing/test2.t 923 924 * `cvs update testing man' updates all files in the subdirectories 925 926 * `cvs update .' or just `cvs update' updates all files in the `tc' 927 directory 928 929 If no arguments are given to `update' it will update all files in 930the current working directory and all its subdirectories. In other 931words, `.' is a default argument to `update'. This is also true for 932most of the CVS subcommands, not only the `update' command. 933 934 The recursive behavior of the CVS subcommands can be turned off with 935the `-l' option. Conversely, the `-R' option can be used to force 936recursion if `-l' is specified in `~/.cvsrc' (*note ~/.cvsrc::). 937 938 $ cvs update -l # Don't update files in subdirectories 939 940 941File: cvs.info, Node: Adding and removing, Next: History browsing, Prev: Recursive behavior, Up: Top 942 943Adding, removing, and renaming files and directories 944**************************************************** 945 946 In the course of a project, one will often add new files. Likewise 947with removing or renaming, or with directories. The general concept to 948keep in mind in all these cases is that instead of making an 949irreversible change you want CVS to record the fact that a change has 950taken place, just as with modifying an existing file. The exact 951mechanisms to do this in CVS vary depending on the situation. 952 953* Menu: 954 955* Adding files:: Adding files 956* Removing files:: Removing files 957* Removing directories:: Removing directories 958* Moving files:: Moving and renaming files 959* Moving directories:: Moving and renaming directories 960 961 962File: cvs.info, Node: Adding files, Next: Removing files, Up: Adding and removing 963 964Adding files to a directory 965=========================== 966 967 To add a new file to a directory, follow these steps. 968 969 * You must have a working copy of the directory. *Note Getting the 970 source::. 971 972 * Create the new file inside your working copy of the directory. 973 974 * Use `cvs add FILENAME' to tell CVS that you want to version 975 control the file. If the file contains binary data, specify `-kb' 976 (*note Binary files::). 977 978 * Use `cvs commit FILENAME' to actually check in the file into the 979 repository. Other developers cannot see the file until you 980 perform this step. 981 982 You can also use the `add' command to add a new directory. 983 984 Unlike most other commands, the `add' command is not recursive. You 985cannot even type `cvs add foo/bar'! Instead, you have to 986 987 $ cd foo 988 $ cvs add bar 989 990 - Command: cvs add [`-k' kflag] [`-m' message] files ... 991 Schedule FILES to be added to the repository. The files or 992 directories specified with `add' must already exist in the current 993 directory. To add a whole new directory hierarchy to the source 994 repository (for example, files received from a third-party 995 vendor), use the `import' command instead. *Note import::. 996 997 The added files are not placed in the source repository until you 998 use `commit' to make the change permanent. Doing an `add' on a 999 file that was removed with the `remove' command will undo the 1000 effect of the `remove', unless a `commit' command intervened. 1001 *Note Removing files::, for an example. 1002 1003 The `-k' option specifies the default way that this file will be 1004 checked out; for more information see *Note Substitution modes::. 1005 1006 The `-m' option specifies a description for the file. This 1007 description appears in the history log (if it is enabled, *note 1008 history file::). It will also be saved in the version history 1009 inside the repository when the file is committed. The `log' 1010 command displays this description. The description can be changed 1011 using `admin -t'. *Note admin::. If you omit the `-m 1012 DESCRIPTION' flag, an empty string will be used. You will not be 1013 prompted for a description. 1014 1015 For example, the following commands add the file `backend.c' to the 1016repository: 1017 1018 $ cvs add backend.c 1019 $ cvs commit -m "Early version. Not yet compilable." backend.c 1020 1021 When you add a file it is added only on the branch which you are 1022working on (*note Branching and merging::). You can later merge the 1023additions to another branch if you want (*note Merging adds and 1024removals::). 1025 1026 1027File: cvs.info, Node: Removing files, Next: Removing directories, Prev: Adding files, Up: Adding and removing 1028 1029Removing files 1030============== 1031 1032 Directories change. New files are added, and old files disappear. 1033Still, you want to be able to retrieve an exact copy of old releases. 1034 1035 Here is what you can do to remove a file, but remain able to 1036retrieve old revisions: 1037 1038 * Make sure that you have not made any uncommitted modifications to 1039 the file. *Note Viewing differences::, for one way to do that. 1040 You can also use the `status' or `update' command. If you remove 1041 the file without committing your changes, you will of course not 1042 be able to retrieve the file as it was immediately before you 1043 deleted it. 1044 1045 * Remove the file from your working copy of the directory. You can 1046 for instance use `rm'. 1047 1048 * Use `cvs remove FILENAME' to tell CVS that you really want to 1049 delete the file. 1050 1051 * Use `cvs commit FILENAME' to actually perform the removal of the 1052 file from the repository. 1053 1054 When you commit the removal of the file, CVS records the fact that 1055the file no longer exists. It is possible for a file to exist on only 1056some branches and not on others, or to re-add another file with the same 1057name later. CVS will correctly create or not create the file, based on 1058the `-r' and `-D' options specified to `checkout' or `update'. 1059 1060 - Command: cvs remove [options] files ... 1061 Schedule file(s) to be removed from the repository (files which 1062 have not already been removed from the working directory are not 1063 processed). This command does not actually remove the file from 1064 the repository until you commit the removal. For a full list of 1065 options, see *Note Invoking CVS::. 1066 1067 Here is an example of removing several files: 1068 1069 $ cd test 1070 $ rm *.c 1071 $ cvs remove 1072 cvs remove: Removing . 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 As a convenience you can remove the file and `cvs remove' it in one 1081step, by specifying the `-f' option. For example, the above example 1082could also be done like this: 1083 1084 $ cd test 1085 $ cvs remove -f *.c 1086 cvs remove: scheduling a.c for removal 1087 cvs remove: scheduling b.c for removal 1088 cvs remove: use 'cvs commit' to remove these files permanently 1089 $ cvs ci -m "Removed unneeded files" 1090 cvs commit: Examining . 1091 cvs commit: Committing . 1092 1093 If you execute `remove' for a file, and then change your mind before 1094you commit, you can undo the `remove' with an `add' command. 1095 1096 $ ls 1097 CVS ja.h oj.c 1098 $ rm oj.c 1099 $ cvs remove oj.c 1100 cvs remove: scheduling oj.c for removal 1101 cvs remove: use 'cvs commit' to remove this file permanently 1102 $ cvs add oj.c 1103 U oj.c 1104 cvs add: oj.c, version 1.1.1.1, resurrected 1105 1106 If you realize your mistake before you run the `remove' command you 1107can use `update' to resurrect the file: 1108 1109 $ rm oj.c 1110 $ cvs update oj.c 1111 cvs update: warning: oj.c was lost 1112 U oj.c 1113 1114 When you remove a file it is removed only on the branch which you 1115are working on (*note Branching and merging::). You can later merge 1116the removals to another branch if you want (*note Merging adds and 1117removals::). 1118 1119 1120File: cvs.info, Node: Removing directories, Next: Moving files, Prev: Removing files, Up: Adding and removing 1121 1122Removing directories 1123==================== 1124 1125 In concept removing directories is somewhat similar to removing 1126files--you want the directory to not exist in your current working 1127directories, but you also want to be able to retrieve old releases in 1128which the directory existed. 1129 1130 The way that you remove a directory is to remove all the files in 1131it. You don't remove the directory itself; there is no way to do that. 1132Instead you specify the `-P' option to `cvs update' or `cvs checkout', 1133which will cause CVS to remove empty directories from working 1134directories. (Note that `cvs export' always removes empty directories.) 1135Probably the best way to do this is to always specify `-P'; if you want 1136an empty directory then put a dummy file (for example `.keepme') in it 1137to prevent `-P' from removing it. 1138 1139 Note that `-P' is implied by the `-r' or `-D' options of `checkout'. 1140This way CVS will be able to correctly create the directory or not 1141depending on whether the particular version you are checking out 1142contains any files in that directory. 1143 1144 1145File: cvs.info, Node: Moving files, Next: Moving directories, Prev: Removing directories, Up: Adding and removing 1146 1147Moving and renaming files 1148========================= 1149 1150 Moving files to a different directory or renaming them is not 1151difficult, but some of the ways in which this works may be non-obvious. 1152(Moving or renaming a directory is even harder. *Note Moving 1153directories::.). 1154 1155 The examples below assume that the file OLD is renamed to NEW. 1156 1157* Menu: 1158 1159* Outside:: The normal way to Rename 1160* Inside:: A tricky, alternative way 1161* Rename by copying:: Another tricky, alternative way 1162 1163 1164File: cvs.info, Node: Outside, Next: Inside, Up: Moving files 1165 1166The Normal way to Rename 1167------------------------ 1168 1169 The normal way to move a file is to copy OLD to NEW, and then issue 1170the normal CVS commands to remove OLD from the repository, and add NEW 1171to it. 1172 1173 $ mv OLD NEW 1174 $ cvs remove OLD 1175 $ cvs add NEW 1176 $ cvs commit -m "Renamed OLD to NEW" OLD NEW 1177 1178 This is the simplest way to move a file, it is not error-prone, and 1179it preserves the history of what was done. Note that to access the 1180history of the file you must specify the old or the new name, depending 1181on what portion of the history you are accessing. For example, `cvs 1182log OLD' will give the log up until the time of the rename. 1183 1184 When NEW is committed its revision numbers will start again, usually 1185at 1.1, so if that bothers you, use the `-r rev' option to commit. For 1186more information see *Note Assigning revisions::. 1187 1188 1189File: cvs.info, Node: Inside, Next: Rename by copying, Prev: Outside, Up: Moving files 1190 1191Moving the history file 1192----------------------- 1193 1194 This method is more dangerous, since it involves moving files inside 1195the repository. Read this entire section before trying it out! 1196 1197 $ cd $CVSROOT/DIR 1198 $ mv OLD,v NEW,v 1199 1200Advantages: 1201 1202 * The log of changes is maintained intact. 1203 1204 * The revision numbers are not affected. 1205 1206Disadvantages: 1207 1208 * Old releases cannot easily be fetched from the repository. (The 1209 file will show up as NEW even in revisions from the time before it 1210 was renamed). 1211 1212 * There is no log information of when the file was renamed. 1213 1214 * Nasty things might happen if someone accesses the history file 1215 while you are moving it. Make sure no one else runs any of the CVS 1216 commands while you move it. 1217 1218 1219File: cvs.info, Node: Rename by copying, Prev: Inside, Up: Moving files 1220 1221Copying the history file 1222------------------------ 1223 1224 This way also involves direct modifications to the repository. It 1225is safe, but not without drawbacks. 1226 1227 # Copy the RCS file inside the repository 1228 $ cd $CVSROOT/DIR 1229 $ cp OLD,v NEW,v 1230 # Remove the old file 1231 $ cd ~/DIR 1232 $ rm OLD 1233 $ cvs remove OLD 1234 $ cvs commit OLD 1235 # Remove all tags from NEW 1236 $ cvs update NEW 1237 $ cvs log NEW # Remember the non-branch tag names 1238 $ cvs tag -d TAG1 NEW 1239 $ cvs tag -d TAG2 NEW 1240 ... 1241 1242 By removing the tags you will be able to check out old revisions. 1243 1244Advantages: 1245 1246 * Checking out old revisions works correctly, as long as you use 1247 `-rTAG' and not `-DDATE' to retrieve the revisions. 1248 1249 * The log of changes is maintained intact. 1250 1251 * The revision numbers are not affected. 1252 1253Disadvantages: 1254 1255 * You cannot easily see the history of the file across the rename. 1256 1257 1258