maintaining.texi 97.6 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1
@c This is part of the Emacs manual.
2
@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2011
3
@c   Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
4 5 6 7 8
@c See file emacs.texi for copying conditions.
@node Maintaining, Abbrevs, Building, Top
@chapter Maintaining Large Programs

  This chapter describes Emacs features for maintaining large
9
programs.
Glenn Morris's avatar
Glenn Morris committed
10 11

@menu
12
* Version Control::     Using version control systems.
13 14 15
* Change Log::          Maintaining a change history for your program.
* Tags::                Go directly to any function in your program in one
                          command.  Tags remembers which file it is in.
16
* EDE::                 An integrated development environment for Emacs.
Glenn Morris's avatar
Glenn Morris committed
17 18 19 20 21
@ifnottex
* Emerge::              A convenient way of merging two versions of a program.
@end ifnottex
@end menu

22 23 24 25
@node Version Control
@section Version Control
@cindex version control

26
  A @dfn{version control system} is a program that can record multiple
27
versions of a source file, storing information such as the creation
28 29 30 31 32 33 34 35 36 37 38 39
time of each version, who made it, and a description of what was
changed.

  The Emacs version control interface is called @dfn{VC}.  VC commands
work with several different version control systems; currently, it
supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS,
SCCS/CSSC, and Subversion.  Of these, the GNU project distributes CVS,
Arch, RCS, and Bazaar.

  VC is enabled automatically whenever you visit a file governed by a
version control system.  To disable VC entirely, set the customizable
variable @code{vc-handled-backends} to @code{nil}
40 41 42 43 44 45 46 47 48 49 50
@iftex
(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Customizing VC}).
@end ifnottex

@menu
* Introduction to VC::  How version control works in general.
* VC Mode Line::        How the mode line shows version control status.
* Basic VC Editing::    How to edit a file under version control.
51
* Log Buffer::          Features available in log entry buffers.
52 53 54 55 56 57
* Old Revisions::       Examining and comparing old versions.
* Secondary VC Commands::    The commands used a little less frequently.
* VC Directory Mode::   Listing files managed by version control.
* Branches::            Multiple lines of development.
@ifnottex
* Remote Repositories:: Efficient access to remote CVS servers.
58
* Revision Tags::       Symbolic names for revisions.
59 60 61 62 63 64 65 66 67
* Miscellaneous VC::    Various other commands and features of VC.
* Customizing VC::      Variables that change VC's behavior.
@end ifnottex
@end menu

@node Introduction to VC
@subsection Introduction to Version Control

  VC allows you to use a version control system from within Emacs,
68 69 70 71 72 73 74
integrating the version control operations smoothly with editing.  It
provides a uniform interface for common operations in many version
control operations.

  Some uncommon or intricate version control operations, such as
altering repository settings, are not supported in VC.  You should
perform such tasks outside Emacs, e.g. via the command line.
75 76 77 78 79 80 81

  This section provides a general overview of version control, and
describes the version control systems that VC supports.  You can skip
this section if you are already familiar with the version control system
you want to use.

@menu
82
* Why Version Control?::    Understanding the problems it addresses.
83 84
* Version Control Systems:: Supported version control back-end systems.
* VCS Concepts::            Words and concepts related to version control.
85 86 87
* VCS Merging::             How file conflicts are handled.
* VCS Changesets::          How changes are grouped.
* VCS Repositories::        Where version control repositories are stored.
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
* Types of Log File::       The VCS log in contrast to the ChangeLog.
@end menu

@node Why Version Control?
@subsubsection Understanding the problems it addresses

  Version control systems provide you with three important
capabilities:

@itemize @bullet
@item
@dfn{Reversibility}: the ability to back up to a previous state if you
discover that some modification you did was a mistake or a bad idea.

@item
@dfn{Concurrency}: the ability to have many people modifying the same
collection of files knowing that conflicting modifications can be
detected and resolved.

@item
@dfn{History}: the ability to attach historical data to your data,
such as explanatory comments about the intention behind each change to
it.  Even for a programmer working solo, change histories are an
important aid to memory; for a multi-person project, they are a
vitally important form of communication among developers.
@end itemize

@node Version Control Systems
@subsubsection Supported Version Control Systems

@cindex back end (version control)
119 120
  VC currently works with many different version control systems,
which it refers to as @dfn{back ends}:
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140

@itemize @bullet

@cindex SCCS
@item
SCCS was the first version control system ever built, and was long ago
superseded by more advanced ones.  VC compensates for certain features
missing in SCCS (e.g., tag names for releases) by implementing them
itself.  Other VC features, such as multiple branches, are simply
unavailable.  Since SCCS is non-free, we recommend avoiding it.

@cindex CSSC
@item
CSSC is a free replacement for SCCS.  You should use CSSC only if, for
some reason, you cannot use a more recent and better-designed version
control system.

@cindex RCS
@item
RCS is the free version control system around which VC was initially
141 142 143
built.  It is relatively primitive: it cannot be used over the
network, and works at the level of individual files.  Almost
everything you can do with RCS can be done through VC.
144 145 146 147 148 149

@cindex CVS
@item
CVS is the free version control system that was, until recently (circa
2008), used by the majority of free software projects.  Nowadays, it
is slowly being superseded by newer systems.  CVS allows concurrent
150 151 152
multi-user development either locally or over the network.  Unlike
newer systems, it lacks support for atomic commits and file
moving/renaming.  VC supports all basic editing operations under CVS.
153 154 155 156 157

@cindex SVN
@cindex Subversion
@item
Subversion (SVN) is a free version control system designed to be
158 159 160
similar to CVS but without its problems (e.g., it supports atomic
commits of filesets, and versioning of directories, symbolic links,
meta-data, renames, copies, and deletes).
161 162 163 164

@cindex GNU Arch
@cindex Arch
@item
165 166 167 168
GNU Arch is one of the earliest @dfn{distributed} version control
systems (the other being Monotone).  @xref{VCS Concepts}, for a
description of distributed version control systems.  It is no longer
under active development, and has been deprecated in favor of Bazaar.
169 170 171

@cindex git
@item
172 173
Git is a distributed version control system originally invented by
Linus Torvalds to support development of Linux (his kernel).  VC
174 175
supports many common git operations, but others, such as repository
syncing, must be done from the command line.
176 177 178 179 180

@cindex hg
@cindex Mercurial
@item
Mercurial (hg) is a distributed version control system broadly
181 182
resembling git.  VC supports most Mercurial commands, with the
exception of repository sync operations.
183 184 185 186

@cindex bzr
@cindex Bazaar
@item
187 188 189
Bazaar (bzr) is a distributed version control system that supports
both repository-based and distributed versioning.  VC supports most
basic editing operations under Bazaar.
190 191 192
@end itemize

  Previous versions of VC supported a version control system known as
193 194
Meta-CVS.  This support was dropped due to limited interest from users
and developers.
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209

@node VCS Concepts
@subsubsection Concepts of Version Control

@cindex repository
@cindex registered file
   When a file is under version control, we say that it is
@dfn{registered} in the version control system.  The system has a
@dfn{repository} which stores both the file's present state and its
change history---enough to reconstruct the current version or any
earlier version.  The repository also contains other information, such
as @dfn{log entries} that describe the changes made to each file.

@cindex work file
@cindex checking out files
210 211 212 213 214
  The copy of a version-controlled file that you actually edit is
called the @dfn{work file}.  You can change each work file as you
would an ordinary file.  After you are done with a set of changes, you
@dfn{commit} (or @dfn{check in}) the changes; this records the changes
in the repository, along with a descriptive log entry.
215 216 217 218

@cindex revision
@cindex revision ID
  A copy of a file stored in a repository is called a @dfn{revision}.
219
The history of a file is a sequence of revisions.  Each revision is
220 221 222 223 224
named by a @dfn{revision ID}.  The format of the revision ID depends
on the version control system; in the simplest case, it is just an
integer.

  To go beyond these basic concepts, you will need to understand three
225 226 227 228
aspects in which version control systems differ.  As explained in the
next three sections, they can be lock-based or merge-based; file-based
or changeset-based; and centralized or decentralized.  VC handles all
these modes of operation, but it cannot hide the differences.
229

230 231
@node VCS Merging
@subsubsection Merge-based vs lock-based Version Control
232
@cindex locking versus merging
233

234 235 236 237 238 239 240
  A version control system typically has some mechanism to coordinate
between users who want to change the same file.  There are two ways to
do this: merging and locking.

  In a version control system that uses merging, each user may check
out and modify a work file at any time.  The system lets you
@dfn{merge} your work file, which may contain changes that have not
241
been committed, with the latest changes that others have committed.
242 243 244 245 246 247 248

  Older version control systems use a @dfn{locking} scheme instead.
Here, work files are normally read-only.  To edit a file, you ask the
version control system to make it writable for you by @dfn{locking}
it; only one user can lock a given file at any given time.  This
procedure is analogous to, but different from, the locking that Emacs
uses to detect simultaneous editing of ordinary files
249
(@pxref{Interlocking}).  When you commit your changes, that unlocks
250 251 252 253 254 255 256
the file, and the work file becomes read-only again.  Other users may
then lock the file to make their own changes.

  Both locking and merging systems can have problems when multiple
users try to modify the same file at the same time.  Locking systems
have @dfn{lock conflicts}; a user may try to check a file out and be
unable to because it is locked.  In merging systems, @dfn{merge
257 258
conflicts} happen when you commit a change to a file that conflicts
with a change committed by someone else after your checkout.  Both
259
kinds of conflict have to be resolved by human judgment and
260 261 262
communication.  Experience has shown that merging is superior to
locking, both in convenience to developers and in minimizing the
number and severity of conflicts that actually occur.
263 264 265 266 267

  SCCS always uses locking.  RCS is lock-based by default but can be
told to operate in a merging style.  CVS and Subversion are
merge-based by default but can be told to operate in a locking mode.
Distributed version control systems, such as GNU Arch, git, and
268
Mercurial, are exclusively merging-based.
269

270
  VC mode supports both locking and merging version control.  The
271 272 273 274 275 276 277
terms ``commit'' and ``update'' are used in newer version control
systems; older lock-based systems use the terms ``check in'' and
``check out''.  VC hides the differences between them as much as
possible.

@node VCS Changesets
@subsubsection Changeset-based vs File-based Version Control
278

279
@cindex changesets
280 281
  On SCCS, RCS, CVS, and other early version control systems, version
control operations are @dfn{file-based}: each file has its own comment
282 283 284 285 286
and revision history separate from that of all other files.  Newer
systems, beginning with Subversion, are @dfn{changeset-based}: a
checkin may include changes to several files, and the entire set of
changes is handled as a unit.  Any comment associated with the change
does not belong to a single file, but to the changeset itself.
287 288 289 290

  Changeset-based version control is more flexible and powerful than
file-based version control; usually, when a change to multiple files
has to be reversed, it's good to be able to easily identify and remove
291
all of it.
292

293 294 295 296 297
@node VCS Repositories
@subsubsection Decentralized vs Centralized Repositories

@cindex centralized version control
@cindex decentralized version control
298 299 300
  Early version control systems were designed around a
@dfn{centralized} model in which each project has only one repository
used by all developers.  SCCS, RCS, CVS, and Subversion share this
301 302
kind of model.  One of its drawbacks is that the repository is a choke
point for reliability and efficiency.
303

304 305 306 307
  GNU Arch pioneered the concept of @dfn{decentralized} version
control, later implemented in git, Mercurial, and Bazaar.  A project
may have several different repositories, and these systems support a
sort of super-merge between repositories that tries to reconcile their
308 309
change histories.  In effect, there is one repository for each
developer, and repository merges take the place of commit operations.
310

311 312 313
  VC helps you manage the traffic between your personal workfiles and
a repository.  Whether the repository is a single master, or one of a
network of peer repositories, is not something VC has to care about.
314 315 316 317 318 319 320 321 322

@node Types of Log File
@subsubsection Types of Log File
@cindex types of log file
@cindex log File, types of
@cindex version control log

  Projects that use a version control system can have two types of log
for changes.  One is the log maintained by the version control system:
323 324 325
each time you commit a change, you fill out a @dfn{log entry} for the
change (@pxref{Log Buffer}).  This is called the @dfn{version control
log}.
326 327 328 329 330 331

  The other kind of log is the file @file{ChangeLog} (@pxref{Change
Log}).  It provides a chronological record of all changes to a large
portion of a program---typically one directory and its subdirectories.
A small program would use one @file{ChangeLog} file; a large program
may have a @file{ChangeLog} file in each major directory.
332 333 334 335 336 337 338 339
@xref{Change Log}.  Programmers have used change logs since long
before version control systems.

  Changeset-based version systems typically maintain a changeset-based
modification log for the entire system, which makes change log files
somewhat redundant.  One advantage that they retain is that it is
sometimes useful to be able to view the transaction history of a
single directory separately from those of other directories.
340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361

  A project maintained with version control can use just the version
control log, or it can use both kinds of logs.  It can handle some
files one way and some files the other way.  Each project has its
policy, which you should follow.

  When the policy is to use both, you typically want to write an entry
for each change just once, then put it into both logs.  You can write
the entry in @file{ChangeLog}, then copy it to the log buffer with
@kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}).  Or
you can write the entry in the log buffer while checking in the
change, and later use the @kbd{C-x v a} command to copy it to
@file{ChangeLog}
@iftex
(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Change Logs and VC}).
@end ifnottex

@node VC Mode Line
@subsection Version Control and the Mode Line
362
@cindex VC, mode line indicator
363 364

  When you visit a file that is under version control, Emacs indicates
365 366
this on the mode line.  For example, @samp{Bzr-1223} says that Bazaar
is used for that file, and the current revision ID is 1223.
367 368

  The character between the back-end name and the revision ID
369 370
indicates the status of the work file.  In a merge-based version
control system, a @samp{-} character indicates that the work file is
371 372 373 374 375 376 377 378
unmodified, and @samp{:} indicates that it has been modified.
@samp{!} indicates that the file contains conflicts as result of a
recent merge operation (@pxref{Merging}), or that the file was removed
from the version control.  Finally, @samp{?}  means that the file is
under version control, but is missing from the working tree.

  In a lock-based system, @samp{-} indicates an unlocked file, and
@samp{:} a locked file; if the file is locked by another user (for
379
instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
380
@samp{@@} means that the file was locally added, but not yet committed
381
to the master repository.
382 383 384 385

  On a graphical display, you can move the mouse over this mode line
indicator to pop up a ``tool-tip'', which displays a more verbose
description of the version control status.  Pressing @kbd{Mouse-1}
386 387
over the indicator pops up a menu of VC commands, identical to
@samp{Tools / Version Control} on the menu bar.
388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403

@vindex auto-revert-check-vc-info
  When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
under version control, it updates the version control information in
the mode line.  However, Auto Revert mode may not properly update this
information if the version control status changes without changes to
the work file, from outside the current Emacs session.  If you set
@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
the version control status information every
@code{auto-revert-interval} seconds, even if the work file itself is
unchanged.  The resulting CPU usage depends on the version control
system, but is usually not excessive.

@node Basic VC Editing
@subsection Basic Editing under Version Control

404
@cindex filesets, VC
405
   Most VC commands operate on @dfn{VC filesets}.  A VC fileset is a
406 407 408 409
collection of one or more files that a VC operation acts on.  When you
type VC commands in a buffer visiting a version-controlled file, the
VC fileset is simply that one file.  When you type them in a VC
Directory buffer, and some files in it are marked, the VC fileset
410 411 412
consists of the marked files (@pxref{VC Directory Mode}).

  The principal VC command is an all-purpose command, @kbd{C-x v v}
413 414 415 416
(@code{vc-next-action}), that performs either registration, locking,
merging or a check-in (depending on the situation) on the current VC
fileset.  You can use @kbd{C-x v v} in a file-visiting buffer or in a
VC Directory buffer.
417 418 419

@table @kbd
@itemx C-x v v
420
Perform the appropriate next version control operation on the VC fileset.
421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463
@end table

@findex vc-next-action
@kindex C-x v v
  The precise action of @kbd{C-x v v} depends on the state of the VC
fileset, and whether the version control system uses locking or
merging.  This is described in detail in the subsequent sections.

  VC filesets are the way that VC mode bridges the gap between
file-based and changeset-based version control systems.  They are,
essentially, a way to pass multiple file arguments as a group to
version control commands.  For example, on Subversion, a checkin with
a multi-file VC fileset becomes a joint commit, as though you had
typed @command{svn commit} with those file arguments at the shell
command line.  All files in a VC fileset must be under the same
version control system; if they are not, Emacs signals an error when
you attempt to execute a command on the fileset.

  VC filesets are distinct from the ``named filesets'' used for
viewing and visiting files in functional groups (@pxref{Filesets}).
Unlike named filesets, VC filesets are not named and don't persist
across sessions.

@menu
* VC With A Merging VCS::  Without locking: default mode for CVS.
* VC With A Locking VCS::  RCS in its default mode, SCCS, and optionally CVS.
* Advanced C-x v v::       Advanced features available with a prefix argument.
@end menu

@node VC With A Merging VCS
@subsubsection Basic Version Control with Merging

  When your version control system is merging-based (the default for
CVS and all newer version control systems), work files are always
writable; you need not do anything special to begin editing a file.
The status indicator on the mode line is @samp{-} if the file is
unmodified; it flips to @samp{:} as soon as you save any changes
(@pxref{VC Mode Line}).

  Here is what @kbd{C-x v v} does when using a merging-based system:

@itemize @bullet
@item
464 465 466 467 468 469 470 471 472 473
If the work file is in a directory that is not controlled by any
version control system, prompt for a repository type.  Then, create a
version control repository of that type and register the file with it.

@item
If the work file is in a directory that is controlled by a version
control system but not registered with it, register the file.

@item
If the work file is the same as in the repository, do nothing.
474 475 476

@item
If you have not changed the work file, but some other user has checked
477
in changes to the repository, merge those changes into the work file.
478 479

@item
480 481 482
If you have made modifications to the work file, attempt to commit
the changes.  To do this, Emacs first reads the log entry for the new
revision (@pxref{Log Buffer}).  If some other user has committed
483 484 485 486 487 488
changes to the repository since you last checked it out, the checkin
fails.  In that case, type @kbd{C-x v v} again to merge those changes
into your own work file; this puts the work file into a ``conflicted''
state.  Type @kbd{C-x v v} to clear the ``conflicted'' state; VC then
regards the file as up-to-date and modified, and you can try to check
it in again.
489 490 491 492 493 494 495

To pick up any recent changes from the repository @emph{without}
trying to commit your own changes, type @kbd{C-x v m @key{RET}}.
@xref{Merging}.
@end itemize

  These rules also apply when you use RCS in its ``non-locking'' mode,
496
except that changes are not automatically merged from the repository.
497 498
Nothing informs you if another user has committed changes in the same
file since you began editing it; when you commit your revision, his
499 500 501 502 503 504
changes are removed (however, they remain in the repository and are
thus not irrevocably lost).  Therefore, you must verify that the
current revision is unchanged before checking in your changes.  In
addition, locking is possible with RCS even in this mode: @kbd{C-x v
v} with an unmodified file locks the file, just as it does with RCS in
its normal locking mode (@pxref{VC With A Locking VCS}).
505 506 507 508 509 510 511

@node VC With A Locking VCS
@subsubsection Basic Version Control with Locking

  Under a locking-based version control system (such as SCCS, and RCS
in its default mode), @kbd{C-x v v} does the following:

512
@itemize @bullet
513
@item
514 515
If the file is not locked, lock it and make it writable, so that you
can change it.
516 517

@item
518
If the file is locked by you, and contains changes, commit the
519 520
changes.  In order to do this, Emacs first reads the log entry for the
new revision.  @xref{Log Buffer}.
521 522 523

@item
If the file is locked by you, but you have not changed it since you
524
locked it, release the lock and makes the file read-only again.
525 526

@item
527 528 529 530
If the file is locked by some other user, ask whether you want to
``steal the lock'' from that user.  If you say yes, the file becomes
locked by you, but a message is sent to the person who had formerly
locked the file, to inform him of what has happened.
531 532 533
@end itemize

  These rules also apply when you use CVS in locking mode, except
Bob Rogers's avatar
Bob Rogers committed
534
that CVS does not support stealing a lock.
535 536 537 538

@node Advanced C-x v v
@subsubsection Advanced Control in @kbd{C-x v v}

539
@cindex revision ID in version control
540 541 542 543 544 545 546 547
  When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
C-x v v}), it still performs the next logical version control
operation, but accepts additional arguments to specify precisely how
to do the operation.

@itemize @bullet
@item
If the file is modified (or locked), you can specify the revision ID
548 549
to use for the new version that you commit.  This is one way to create
a new branch (@pxref{Branches}).
550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574

@item
If the file is not modified (and unlocked), you can specify the
revision to select; this lets you start working from an older
revision, or on another branch.  If you do not enter any revision,
that takes you to the highest (``head'') revision on the current
branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to
get the latest version of a file from the repository.

@item
@cindex specific version control system
Instead of the revision ID, you can also specify the name of a
version control system.  This is useful when one file is being managed
with two version control systems at the same time
@iftex
(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
Features}).
@end iftex
@ifnottex
(@pxref{Local Version Control}).
@end ifnottex

@end itemize

@node Log Buffer
575 576 577 578 579 580 581 582 583 584 585 586 587 588 589
@subsection Features of the Log Entry Buffer

  When you tell VC to commit a change, it pops up a buffer called
@samp{*VC-Log*}.  In this buffer, you should write a @dfn{log entry}
describing the changes you have made (@pxref{Why Version Control?}).
After you are done, type @kbd{C-c C-c}; this exits the buffer and
commits the change, together with your log entry.

  While in the @samp{*VC-Log*} buffer, you can write one or more
@dfn{header lines}, specifying additional information to be supplied
to the version control system.  Each header line must occupy a single
line at the top of the buffer; the first line that is not a header
line is treated as the start of the log entry.  For example, the
following header line states that the present change was not written
by you, but by another developer:
590

591 592 593
@smallexample
Author: J. R. Hacker <jrh@@example.com>
@end smallexample
594

595 596 597 598 599 600 601 602
@noindent
Apart from the @samp{Author} header, Emacs recognizes the headers
@samp{Date} (a manually-specified commit time) and @samp{Fixes} (a
reference to a bug fixed by the change).  Not all version control
systems recognize all headers: Bazaar recognizes all three headers,
while git, Mercurial, and Monotone recognizes only @samp{Author} and
@samp{Summary}.  If you specify a header for a version control that
does not support it, the header is treated as part of the log entry.
603 604 605

@findex log-edit-show-files
@findex log-edit-show-diff
606 607 608 609 610
  Type @kbd{C-c C-f} (@code{log-edit-show-files}) to display a list of
files in the current VC fileset.  If you called @kbd{C-x v v} directly
from a work file, the fileset consists of that single file; if you
called @kbd{C-x v v} from a VC directory buffer (@pxref{VC Directory
Mode}), the fileset may consist of multiple files.
611 612

@findex log-edit-insert-changelog
613 614 615 616 617 618 619 620 621
  Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a @dfn{diff}
of the changes you have made (i.e., the differences between the work
file and the repository revision from which you started editing).
@xref{Old Revisions}.

  If the current VC fileset includes one or more @file{ChangeLog}
files (@pxref{Change Log}), type @kbd{C-c C-a}
(@code{log-edit-insert-changelog}) to pull the relevant entries into
the @samp{*VC-Log*} buffer.  If the topmost item in each
622 623 624 625 626 627 628 629 630 631 632 633 634 635
@file{ChangeLog} was made under your user name on the current date,
this command searches that item for entries that match the file(s) to
be committed; if found, these entries are inserted.
@iftex
@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features},
@end iftex
@ifnottex
@xref{Change Logs and VC},
@end ifnottex
for the opposite way of working---generating ChangeLog entries from
the revision control log.

  To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that
buffer.  You can switch buffers and do other editing.  As long as you
636
don't try to commit another file, the entry you were editing remains
637 638 639 640 641 642 643 644
in the @samp{*VC-Log*} buffer, and you can go back to that buffer at
any time to complete the check-in.

  If you change several source files for the same reason, it is often
convenient to specify the same log entry for many of the files.  (This
is the normal way to do things on a changeset-oriented system, where
comments are attached to changesets rather than the history of
individual files.)  The most convenient way to do this is to mark all
645
the files in VC Directory Mode and commit from there; the log buffer
646 647 648 649 650 651 652 653 654 655 656
will carry the fileset information with it and do a group commit when
you type @kbd{C-c C-c}.

  You can also browse the history of previous log entries to duplicate
a checkin comment. This can be useful when you want several files to
have checkin comments that vary only slightly from each other. The
commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this
work just like the minibuffer history commands (except that these
versions are used outside the minibuffer).

@vindex vc-log-mode-hook
657
  Each time you commit a change, the log entry buffer is put into VC
658 659 660 661 662 663 664 665 666 667
Log Edit mode, which involves running two hooks: @code{text-mode-hook}
and @code{vc-log-mode-hook}.  @xref{Hooks}.

@node Old Revisions
@subsection Examining And Comparing Old Revisions

  One of the convenient features of version control is the ability
to examine any revision of a file, or compare two revisions.

@table @kbd
668
@item C-x v ~
669
Prompt for a revision of the current file, and visit it in a buffer of
670
its own (@code{vc-revision-other-window}).
671 672

@item C-x v =
673 674
Compare the files in the current fileset with the working revision(s)
you started from (@code{vc-diff}).  With a prefix argument, prompt for
675 676
two revisions of the current fileset and compare them.  You can call
this command from a Dired buffer (@pxref{Dired}).
677 678 679 680 681

@item C-x v D
Compare the entire tree corresponding to the current fileset with the
tree you started from (@code{vc-root-diff}).  With a prefix argument,
prompt for two revisions and compare their trees.
682 683 684

@item C-x v g
Display an annotated version of the file: for each line, show the
685
latest revision in which it was modified (@code{vc-annotate}).
686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705
@end table

@findex vc-revision-other-window
@kindex C-x v ~
  To examine an old revision, visit the work file and type @kbd{C-x v
~ @var{revision} @key{RET}} (@code{vc-revision-other-window}).  Here,
@var{revision} is either the desired revision ID (@pxref{VCS
Concepts}), or the name of a tag or branch
@iftex
(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Tags}).
@end ifnottex
This command puts the text of the old revision in a file named
@file{@var{filename}.~@var{revision}~}, and visits it in its own
buffer in a separate window.

@findex vc-diff
@kindex C-x v =
706 707 708
  @kbd{C-x v =} (@code{vc-diff}) compares each file in the current VC
fileset (saving them if necessary) with the repository revision(s)
from which you started editing.  Note that the latter may or may not
709 710 711 712 713 714
be the latest revision of the file(s).

  The diff is displayed in another window, in a Diff mode buffer
(@pxref{Diff Mode}) named @file{*vc-diff*}.  In this buffer, the
@kbd{g} (@code{revert-buffer}) command performs the file comparison
again, generating a new diff.
715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735

@findex vc-diff
@kindex C-u C-x v =
  To compare two arbitrary revisions of the current VC fileset, call
@code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}.  This
prompts for two revision IDs, using the minibuffer, and displays the
diff in a special buffer in another window.  Instead of providing a
revision ID, you can give an empty input, which specifies the current
contents of the work file; or a tag or branch name
@iftex
(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Tags}).
@end ifnottex
If your version control system is file-based (e.g. CVS) rather than
changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a
revision ID for a multi-file fileset (as opposed to a symbolic tag
name) is unlikely to return diffs that are connected in any meaningful
way.

736 737 738 739 740 741
  The command @kbd{C-x v D} (@code{vc-root-diff}) is similar to
@kbd{C-x v =}, but it compares the entire tree associated with the
current VC fileset with the tree you started with.  This means all the
files controlled by the current version control repository, even those
that are not part of the current VC fileset.

742 743 744 745 746 747 748 749
  If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that
is neither visiting a version-controlled file nor a VC directory
buffer, these commands generate a diff of all registered files in the
current directory and its subdirectories.

@vindex vc-diff-switches
@vindex vc-rcs-diff-switches
  @kbd{C-x v =} works by running a variant of the @code{diff} utility
750 751 752 753 754 755
designed to work with the version control system in use.  The options
to pass to the @code{diff} command are taken from the first non-@code{nil}
value of @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches},
and @code{diff-switches} (@pxref{Comparing Files}), in that order.
Since @code{nil} means to check the next variable in the sequence,
either of the first two may use the value @code{t} to mean no switches at all.
756 757 758 759 760
Most of the @samp{vc@dots{}diff-switches} variables default to
@code{nil}, but some default to @code{t}.  These are for those version
control systems (e.g. SVN) whose @code{diff} implementations do not
accept common options (e.g. @samp{-c}) likely to be in
@code{diff-switches}.
761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842

  The buffer produced by @kbd{C-x v =} supports the commands of
Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and
@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always
find the corresponding locations in the current work file.  (Older
revisions are not, in general, present as files on your disk.)

@findex vc-annotate
@kindex C-x v g
  For some back ends, you can display the file @dfn{annotated} with
per-line revision information, by typing @kbd{C-x v g}
(@code{vc-annotate}).  This creates a new buffer (the ``annotate
buffer'') displaying the file's text, with each part colored to show
how old it is.  Text colored red is new, blue means old, and
intermediate colors indicate intermediate ages.  By default, the color
is scaled over the full range of ages, such that the oldest changes
are blue, and the newest changes are red.

  When you give a prefix argument to this command, Emacs reads two
arguments using the minibuffer: the ID of which revision to display and
annotate (instead of the current file contents), and the time span in
days the color range should cover.

  From the annotate buffer, these and other color scaling options are
available from the @samp{VC-Annotate} menu.  In this buffer, you can
also use the following keys to browse the annotations of past revisions,
view diffs, or view log entries:

@table @kbd
@item p
Annotate the previous revision, that is to say, the revision before
the one currently annotated.  A numeric prefix argument is a repeat
count, so @kbd{C-u 10 p} would take you back 10 revisions.

@item n
Annotate the next revision---the one after the revision currently
annotated.  A numeric prefix argument is a repeat count.

@item j
Annotate the revision indicated by the current line.

@item a
Annotate the revision before the one indicated by the current line.
This is useful to see the state the file was in before the change on
the current line was made.

@item f
Show in a buffer the file revision indicated by the current line.

@item d
Display the diff between the current line's revision and the previous
revision.  This is useful to see what the current line's revision
actually changed in the file.

@item D
Display the diff between the current line's revision and the previous
revision for all files in the changeset (for VC systems that support
changesets).  This is useful to see what the current line's revision
actually changed in the tree.

@item l
Show the log of the current line's revision.  This is useful to see
the author's description of the changes in the revision on the current
line.

@item w
Annotate the working revision--the one you are editing.  If you used
@kbd{p} and @kbd{n} to browse to other revisions, use this key to
return to your working revision.

@item v
Toggle the annotation visibility.  This is useful for looking just at
the file contents without distraction from the annotations.
@end table

@node Secondary VC Commands
@subsection The Secondary Commands of VC

  This section explains the secondary commands of VC.

@menu
* Registering::         Putting a file under version control.
843
* VC Change Log::       Viewing the VC Change Log.
844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898
* VC Undo::             Canceling changes before or after check-in.
@end menu

@node Registering
@subsubsection Registering a File for Version Control

@kindex C-x v i
@findex vc-register
  You can put any file under version control by simply visiting it, and
then typing @w{@kbd{C-x v i}} (@code{vc-register}).

@table @kbd
@item C-x v i
Register the visited file for version control.
@end table

  To register the file, Emacs must choose which version control system
to use for it.  If the file's directory already contains files
registered in a version control system, Emacs uses that system.  If
there is more than one system in use for a directory, Emacs uses the
one that appears first in @code{vc-handled-backends}
@iftex
(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Customizing VC}).
@end ifnottex
On the other hand, if there are no files already registered, Emacs uses
the first system from @code{vc-handled-backends} that could register
the file (for example, you cannot register a file under CVS if its
directory is not already part of a CVS tree); with the default value
of @code{vc-handled-backends}, this means that Emacs uses RCS in this
situation.

  If locking is in use, @kbd{C-x v i} leaves the file unlocked and
read-only.  Type @kbd{C-x v v} if you wish to start editing it.  After
registering a file with CVS, you must subsequently commit the initial
revision by typing @kbd{C-x v v}.  Until you do that, the revision ID
appears as @samp{@@@@} in the mode line.

@vindex vc-default-init-revision
@cindex initial revision ID to register
  The default initial revision ID for a newly registered file
varies by what VCS you are using; normally it will be 1.1 on VCSes
that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs.
You can specify a different default by setting the variable
@code{vc-default-init-revision}, or you can give @kbd{C-x v i} a
numeric argument; then it reads the initial revision ID for this
particular file using the minibuffer.

@vindex vc-initial-comment
  If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
initial comment to describe the purpose of this source file.  Reading
the initial comment works like reading a log entry (@pxref{Log Buffer}).

899 900
@node VC Change Log
@subsubsection VC Change Log
901 902 903

@table @kbd
@item C-x v l
904 905 906 907 908 909
Display revision control state and change history
(@code{vc-print-log}).

@item C-x v L
Display the change history for the current repository
(@code{vc-print-root-log}).
910 911 912 913 914 915 916 917

@item C-x v I
Display the changes that will be received with a pull operation
(@code{vc-log-incoming}).

@item C-x v O
Display the changes that will be sent by the next push operation
(@code{vc-log-outgoing}).
918 919 920 921
@end table

@kindex C-x v l
@findex vc-print-log
922 923 924 925 926 927 928 929
  The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer
named @samp{*vc-change-log*} in a new window.  This buffer lists the
changes to the current file, including the associated log entries.
(These are the log entries associated with the version control system,
i.e. the ones you enter via the @samp{*VC-Log*} buffer.  @xref{Log
Buffer}.)  Point is centered at the revision of the file currently
being visited.  With a prefix argument, the command prompts for the
revision to center on, and the maximum number of revisions to display.
930
You can call this command from a Dired buffer (@pxref{Dired}).
931 932 933 934 935 936 937

@findex vc-print-root-log
  Type @kbd{C-x v L} (@code{vc-print-root-log}) to display a
@samp{*vc-change-log*} buffer showing the history of the
version-controlled directory tree as a whole.  With a prefix argument,
the command prompts for the maximum number of revisions to display.
RCS, SCCS, and CVS do not support this feature.
938

939 940 941 942 943 944 945 946 947 948 949 950 951
  On a distributed version control system, the @kbd{C-x v I}
(@code{vc-log-incoming}) command displays a log buffer showing the
changes that will be applied, the next time you run the version
control system's ``pull'' command to get new revisions from another
repository.  This other repository is the default one from which
changes are pulled, as defined by the version control system; with a
prefix argument, @code{vc-log-incoming} prompts for a specific
repository from which changes would be pulled, and lists the changes
accordingly.  Similarly, @kbd{C-x v O} (@code{vc-log-outgoing}) shows
the changes that will be sent to another repository, the next time you
run the ``push'' command; with a prefix argument, it prompts for a
specific repository to which changes would be pushed.

952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003
  In the @samp{*vc-change-log*} buffer, you can use the following keys
to move between the logs of revisions and of files, to view past
revisions, to modify change comments, to view annotations and to view
diffs:

@table @kbd
@item p
Move to the previous revision-item in the buffer.  (Revision entries in the log
buffer are usually in reverse-chronological order, so the previous
revision-item usually corresponds to a newer revision.)  A numeric
prefix argument is a repeat count.

@item n
Move to the next revision-item (which most often corresponds to the
previous revision of the file).  A numeric prefix argument is a repeat
count.

@item P
Move to the log of the previous file, when the logs of multiple files
are in the log buffer (@pxref{VC Directory Mode}).  Otherwise, just
move to the beginning of the log.  A numeric prefix argument is a
repeat count, so @kbd{C-u 10 P} would move backward 10 files.

@item N
Move to the log of the next file, when the logs of multiple files are
in the log buffer (@pxref{VC Directory Mode}).  It also takes a
numeric prefix argument as a repeat count.

@item a
Annotate the revision indicated by the current line.

@item e
Modify the change comment displayed at point.  Note that not all VC
systems support modifying change comments.

@item f
Visit the revision indicated at the current line, like typing @kbd{C-x
v ~} and specifying this revision's ID (@pxref{Old Revisions}).

@item d
Display the diff (@pxref{Comparing Files}) between the revision
indicated at the current line and the next earlier revision.  This is
useful to see what actually changed in the file when the revision
indicated on the current line was committed.

@item D
Display the changeset diff (@pxref{Comparing Files}) between the
revision indicated at the current line and the next earlier revision.
This is useful to see all the changes to all files that the revision
indicated on the current line did when it was committed.
@end table

1004 1005 1006 1007 1008 1009 1010 1011 1012 1013
@vindex vc-log-show-limit
Because fetching many log entries can be slow, the
@samp{*vc-change-log*} buffer displays no more than 2000 revisions by
default.  The variable @code{vc-log-show-limit} specifies this limit;
if you set the value to zero, that removes the limit.  You can also
increase the number of revisions shown in an existing
@samp{*vc-change-log*} buffer by clicking on the @samp{Show 2X
entries} or @samp{Show unlimited entries} buttons at the end of the
buffer.  However, RCS, SCCS, and CVS do not support this feature.

1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041
@node VC Undo
@subsubsection Undoing Version Control Actions

@table @kbd
@item C-x v u
Revert the buffer and the file to the working revision from which you started
editing the file.

@item C-x v c
Remove the last-entered change from the master for the visited file.
This undoes your last check-in.
@end table

@kindex C-x v u
@findex vc-revert-buffer
  If you want to discard your current set of changes and revert to the
working revision from which you started editing the file, use @kbd{C-x
v u} (@code{vc-revert-buffer}).  If the version control system is
locking-based, this leaves the file unlocked, and you must lock it
again before making new changes.  @kbd{C-x v u} requires confirmation,
unless it sees that you haven't made any changes with respect to the
master copy of the working revision.

  @kbd{C-x v u} is also the command to unlock a file if you lock it and
then decide not to change it.

@kindex C-x v c
@findex vc-rollback
1042
  To cancel a change that you already committed, use @kbd{C-x v c}
1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066
(@code{vc-rollback}).  This command discards all record of the most
recent checked-in revision, but only if your work file corresponds to
that revision---you cannot use @kbd{C-x v c} to cancel a revision that
is not the latest on its branch.  Note that many version control
systems do not support rollback at all; this command is something of a
historical relic.

@node VC Directory Mode
@subsection VC Directory Mode

@kindex C-x v d
@findex vc-dir
  When you are working on a large program, it is often useful to find
out which files have changed within an entire directory tree, or to
view the status of all files under version control at once, and to
perform version control operations on collections of files.  You can
use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory
listing that includes only files relevant for version control.  This
creates a @dfn{VC Directory buffer} and displays it in a separate
window.

@cindex PCL-CVS
@pindex cvs
@cindex CVS directory mode
1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078
  The VC Directory buffer works with all the version control systems
that VC supports.  For CVS, Emacs also offers a more powerful facility
called PCL-CVS.  @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The
Emacs Front-End to CVS}.

@menu
* Buffer: VC Directory Buffer.      What the buffer looks like and means.
* Commands: VC Directory Commands.  Commands to use in a VC directory buffer.
@end menu

@node VC Directory Buffer
@subsubsection The VC Directory Buffer
1079 1080 1081 1082

  The VC Directory buffer contains a list of version-controlled files
in the current directory and its subdirectories.  Files which are
up-to-date (have no local differences from the repository copy) are
1083 1084 1085 1086
usually hidden; if all files in a subdirectory are up-to-date, the
subdirectory is hidden as well.  There is an exception to this rule:
if VC mode detects that a file has changed to an up-to-date state
since you last looked at it, that file and its state are shown.
1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108

  If a directory uses more that one version control system, you can
select which system to use for the @code{vc-dir} command by invoking
@code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}.

  The line for an individual file shows the version control state of
the file.  Under RCS and SCCS, the name of the user locking the file
is shown; under CVS, an abbreviated version of the @samp{cvs status}
output is used.  Here is an example using CVS:

@smallexample
@group
                       ./
    modified           file1.c
    needs-update       file2.c
    needs-merge        file3.c
@end group
@end smallexample

@noindent
In this example, @samp{file1.c} is modified with respect to the
repository, and @samp{file2.c} is not.  @samp{file3.c} is modified,
1109 1110
but other changes have also been committed---you need to merge them
with the work file before you can check it in.
1111 1112 1113 1114 1115

@vindex vc-stay-local
@vindex vc-cvs-stay-local
  In the above, if the repository were on a remote machine, VC only
contacts it when the variable @code{vc-stay-local} (or
1116 1117 1118 1119 1120 1121 1122 1123 1124
@code{vc-cvs-stay-local}) is @code{nil}
@iftex
(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{CVS Options}).
@end ifnottex
This is because access to the repository may be slow, or you may be
working offline and not have access to the repository at all.  As a
1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147
consequence, VC would not be able to tell you that @samp{file3.c} is
in the ``merge'' state; you would learn that only when you try to
check-in your modified copy of the file, or use a command such as
@kbd{C-x v m}.

  In practice, this is not a problem because CVS handles this case
consistently whenever it arises.  In VC, you'll simply get prompted to
merge the remote changes into your work file first.  The benefits of
less network communication usually outweigh the disadvantage of not
seeing remote changes immediately.

@vindex vc-directory-exclusion-list
  When a VC directory displays subdirectories it omits some that
should never contain any files under version control.  By default,
this includes Version Control subdirectories such as @samp{RCS} and
@samp{CVS}; you can customize this by setting the variable
@code{vc-directory-exclusion-list}.

@node VC Directory Commands
@subsubsection VC Directory Commands

  VC Directory mode has a full set of navigation and marking commands
for picking out filesets.  Some of these are also available in a
1148
context menu invoked by @kbd{mouse-2}.
1149 1150 1151 1152 1153 1154 1155 1156 1157 1158

  Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p}  also
move vertically as in other list-browsing modes.  @key{SPC} and
@key{TAB} behave like down-arrow, and @key{BackTab} behaves like
up-arrow.

  Both @kbd{C-m} and @kbd{f} visit the file on the current
line.  @kbd{o} visits that file in another window.  @kbd{q} dismisses
the directory buffer.

1159
  @kbd{x} hides up-to-date files.
1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191

  @kbd{m} marks the file or directory on the current line.  If the
region is active, @kbd{m} marks all the files in the region.  There
are some restrictions when marking: a file cannot be marked if any of
its parent directories are marked, and a directory cannot be marked if
any files in it or in its child directories are marked.

  @kbd{M} marks all the files with the same VC state as the current
file if the cursor is on a file.  If the cursor is on a directory, it
marks all child files.  With a prefix argument: marks all files and
directories.

  @kbd{u} unmarks the file or directory on the current line.  If the
region is active, it unmarks all the files in the region.

  @kbd{U} marks all the files with the same VC state as the current file
if the cursor is on a file.  If the cursor is on a directory, it
unmarks all child files.  With a prefix argument: unmarks all marked
files and directories.

  It is possible to do search, search and replace, incremental search,
and incremental regexp search on multiple files.  These commands will
work on all the marked files or the current file if nothing is marked.
If a directory is marked, the files in that directory shown in the VC
directory buffer will be used.

  @kbd{S} searches the marked files.

  @kbd{Q} does a query replace on the marked files.

  @kbd{M-s a C-s} does an incremental search on the marked files.

Bob Rogers's avatar
Bob Rogers committed
1192 1193
  @kbd{M-s a C-M-s} does an incremental regular expression search
on the marked files.
1194

1195 1196 1197 1198 1199 1200 1201 1202
@cindex stashes in version control
@cindex shelves in version control
  Commands are also accessible from the VC-dir menu.  Note that some
VC backends use the VC-dir menu to make available extra,
backend-specific, commands.  For example, Git and Bazaar allow you to
manipulate @dfn{stashes} and @dfn{shelves}.  (These provide a
mechanism to temporarily store uncommitted changes somewhere out of
the way, and bring them back at a later time.)
1203 1204 1205 1206 1207 1208

  Normal VC commands with the @kbd{C-x v} prefix work in VC directory
buffers.  Some single-key shortcuts are available as well; @kbd{=},
@kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with
@kbd{C-x v}.

1209 1210 1211 1212 1213
  The command @kbd{C-x v v} (@code{vc-next-action}) operates on all
the marked files, so that you can commit several files at once.  If
the underlying VC supports atomic commits of multiple-file changesets,
@kbd{C-x v v} with a selected set of modified but not committed files
will commit all of them at once as a single changeset.
1214

1215 1216 1217 1218 1219 1220
  When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple
files, all of those files must be either in the same state or in
compatible states (added, modified and removed states are considered
compatible).  Otherwise it signals an error.  This differs from the
behavior of older versions of VC, which did not have fileset
operations and simply did @code{vc-next-action} on each file
1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295
individually.

  If any files are in a state that calls for commit, @kbd{C-x v v} reads a
single log entry and uses it for the changeset as a whole.  If the
underling VCS is file- rather than changeset-oriented, the log entry
will be replicated into the history of each file.

@node Branches
@subsection Multiple Branches of a File
@cindex branch (version control)
@cindex trunk (version control)

  One use of version control is to maintain multiple ``current''
revisions of a file.  For example, you might have different revisions of a
program in which you are gradually adding various unfinished new
features.  Each such independent line of development is called a
@dfn{branch}.  VC allows you to create branches, switch between
different branches, and merge changes from one branch to another.
Please note, however, that branches are not supported for SCCS.

  A file's main line of development is usually called the @dfn{trunk}.
You can create multiple branches from the trunk.  How the difference
between trunk and branch is made visible is dependent on whether the
VCS uses dot-pair or monotonic version IDs.

  In VCSes with dot-pair revision IDs, the revisions on the trunk are
normally IDed 1.1, 1.2, 1.3, etc.  At any such revision, you can
start an independent branch.  A branch starting at revision 1.2 would
have revision ID 1.2.1.1, and consecutive revisions on this branch
would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on.  If there is
a second branch also starting at revision 1.2, it would consist of
revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.

   In VCSes with monotonic revision IDs, trunk revisions are IDed as
1, 2, 3, etc.  A branch from (say) revision 2 might start with 2.1 and
continue through 2.2, 2.3, etc.  But naming conventions for branches
and subbranches vary widely on these systems, and some (like
Mercurial) never depart from the monotonic integer sequence at all.
Consult the documentation of the VCS you are using.

@cindex head revision
  If you omit the final component of a dot-pair revision ID, that is called a
@dfn{branch ID}.  It refers to the highest existing revision on that
branch---the @dfn{head revision} of that branch.  The branches in the
dot-pair example above have branch IDs 1.2.1 and 1.2.2.

@menu
* Switching Branches::    How to get to another existing branch.
* Creating Branches::     How to start a new branch.
* Merging::               Transferring changes between branches.
* Multi-User Branching::  Multiple users working at multiple branches
                            in parallel.
@end menu

@node Switching Branches
@subsubsection Switching between Branches

  To switch between branches, type @kbd{C-u C-x v v} and specify the
revision ID you want to select.  On a locking-based system, this
version is then visited @emph{unlocked} (write-protected), so you can
examine it before locking it.  Switching branches in this way is allowed
only when the file is not locked.

  On a VCS with dot-pair IDs, you can omit the minor part, thus giving
only the branch ID; this takes you to the head version on the
chosen branch.  If you only type @key{RET}, Emacs goes to the highest
version on the trunk.

  After you have switched to any branch (including the main branch), you
stay on it for subsequent VC commands, until you explicitly select some
other branch.

@node Creating Branches
@subsubsection Creating New Branches

1296 1297 1298 1299 1300 1301 1302 1303 1304
  To create a new branch from a head revision (one that is the latest
in the branch that contains it), first select that revision if
necessary, lock it with @kbd{C-x v v}, and make whatever changes you
want.  Then, when you commit the changes, use @kbd{C-u C-x v v}.  This
lets you specify the revision ID for the new revision.  You should
specify a suitable branch ID for a branch starting at the current
revision.  For example, if the current revision is 2.5, the branch ID
should be 2.5.1, 2.5.2, and so on, depending on the number of existing
branches at that point.
1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316

  To create a new branch at an older revision (one that is no longer the
head of a branch), first select that revision (@pxref{Switching
Branches}).  Your procedure will then differ depending on whether you
are using a locking or merging-based VCS.

  On a locking VCS, you will need to lock the old revision branch with
@kbd{C-x v v}.  You'll be asked to confirm, when you lock the old
revision, that you really mean to create a new branch---if you say no,
you'll be offered a chance to lock the latest revision instead.  On
a merging-based VCS you will skip this step.

1317
  Then make your changes and type @kbd{C-x v v} again to commit a new
1318
revision.  This automatically creates a new branch starting from the
1319 1320 1321
selected revision.  You need not specially request a new branch,
because that's the only way to add a new revision at a point that is
not the head of a branch.
1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368

  After the branch is created, you ``stay'' on it.  That means that
subsequent check-ins create new revisions on that branch.  To leave the
branch, you must explicitly select a different revision with @kbd{C-u C-x
v v}.  To transfer changes from one branch to another, use the merge
command, described in the next section.

@node Merging
@subsubsection Merging Branches

@cindex merging changes
  When you have finished the changes on a certain branch, you will
often want to incorporate them into the file's main line of development
(the trunk).  This is not a trivial operation, because development might
also have proceeded on the trunk, so that you must @dfn{merge} the
changes into a file that has already been changed otherwise.  VC allows
you to do this (and other things) with the @code{vc-merge} command.

@table @kbd
@item C-x v m (vc-merge)
Merge changes into the work file.
@end table

@kindex C-x v m
@findex vc-merge
  @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
into the current version of the work file.  It firsts asks you in the
minibuffer where the changes should come from.  If you just type
@key{RET}, Emacs merges any changes that were made on the same branch
since you checked the file out (we call this @dfn{merging the news}).
This is the common way to pick up recent changes from the repository,
regardless of whether you have already changed the file yourself.

  You can also enter a branch ID or a pair of revision IDs in
the minibuffer.  Then @kbd{C-x v m} finds the changes from that
branch, or the differences between the two revisions you specified, and
merges them into the current revision of the current file.

  As an example, suppose that you have finished a certain feature on
branch 1.3.1.  In the meantime, development on the trunk has proceeded
to revision 1.5.  To merge the changes from the branch to the trunk,
first go to the head revision of the trunk, by typing @kbd{C-u C-x v v
@key{RET}}.  Revision 1.5 is now current.  If locking is used for the file,
type @kbd{C-x v v} to lock revision 1.5 so that you can change it.  Next,
type @kbd{C-x v m 1.3.1 @key{RET}}.  This takes the entire set of changes on
branch 1.3.1 (relative to revision 1.3, where the branch started, up to
the last revision on the branch) and merges it into the current revision
1369
of the work file.  You can now commit the changed file, thus creating
1370 1371 1372
revision 1.6 containing the changes from the branch.

  It is possible to do further editing after merging the branch, before
1373
the next check-in.  But it is usually wiser to commit the merged
1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404
revision, then lock it and make the further changes.  This will keep
a better record of the history of changes.

@cindex conflicts
@cindex resolving conflicts
  When you merge changes into a file that has itself been modified, the
changes might overlap.  We call this situation a @dfn{conflict}, and
reconciling the conflicting changes is called @dfn{resolving a
conflict}.

  Whenever conflicts occur during merging, VC detects them, tells you
about them in the echo area, and asks whether you want help in merging.
If you say yes, it starts an Ediff session (@pxref{Top,
Ediff, Ediff, ediff, The Ediff Manual}).

  If you say no, the conflicting changes are both inserted into the
file, surrounded by @dfn{conflict markers}.  The example below shows how
a conflict region looks; the file is called @samp{name} and the current
master file revision with user B's changes in it is 1.11.

@c @w here is so CVS won't think this is a conflict.
@smallexample
@group
@w{<}<<<<<< name
  @var{User A's version}
=======
  @var{User B's version}
@w{>}>>>>>> 1.11
@end group
@end smallexample