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

8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
  This chapter describes Emacs features for maintaining medium- to
large-size programs and packages.  These features include:

@itemize @minus
@item
Unified interface to Support for Version Control Systems
(@acronym{VCS}) that record the history of changes to source files.

@item
A specialized mode for maintaining @file{ChangeLog} files that provide
a chronological log of program changes.

@item
@acronym{Xref}, a set of commands for displaying definitions of
symbols (a.k.a.@: ``identifiers'') and their references.

@item
@acronym{EDE}, the Emacs's own IDE.

@ifnottex
@item
A mode for merging changes to program sources made on separate
branches of development.
@end ifnottex
@end itemize

If you are maintaining a large Lisp program, then in addition to the
features described here, you may find the Emacs Lisp Regression
Testing (@acronym{ERT}) library useful (@pxref{Top,,ERT,ert, Emacs
Lisp Regression Testing}).
Glenn Morris's avatar
Glenn Morris committed
38 39

@menu
40
* Version Control::     Using version control systems.
41
* Change Log::          Maintaining a change history for your program.
42 43
* Xref::                Find definitions and references of any function,
                          method, struct, macro, @dots{} in your program.
44
* EDE::                 An integrated development environment for Emacs.
Glenn Morris's avatar
Glenn Morris committed
45 46 47 48 49
@ifnottex
* Emerge::              A convenient way of merging two versions of a program.
@end ifnottex
@end menu

50 51 52 53
@node Version Control
@section Version Control
@cindex version control

54
  A @dfn{version control system} is a program that can record multiple
55
versions of a source file, storing information such as the creation
56 57 58
time of each version, who made it, and a description of what was
changed.

59
@cindex VC
60 61 62
  The Emacs version control interface is called @dfn{VC}@.  VC
commands work with several different version control systems;
currently, it supports Bazaar, CVS, Git, Mercurial, Monotone, RCS,
63 64
SRC, SCCS/CSSC, and Subversion.  Of these, the GNU project distributes
CVS, RCS, and Bazaar.
65 66 67 68

  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}
69 70 71 72 73 74 75
@iftex
(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Customizing VC}).
@end ifnottex

Eli Zaretskii's avatar
Eli Zaretskii committed
76 77 78 79 80 81 82
@findex vc-refresh-state
@findex vc-state-refresh
  To update the VC state information for the file visited in the
current buffer, use the command @code{vc-refresh-state}.  This command
is useful when you perform version control commands outside Emacs
(e.g., from the shell prompt), or if you put the buffer's file under a
different version control system, or remove it from version control
83
entirely.
Eli Zaretskii's avatar
Eli Zaretskii committed
84

85 86 87 88
@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.
89
* Log Buffer::          Features available in log entry buffers.
90
* Registering::         Putting a file under version control.
91
* Old Revisions::       Examining and comparing old versions.
92 93
* VC Change Log::       Viewing the VC Change Log.
* VC Undo::             Canceling changes before or after committing.
94
* VC Ignore::           Ignore files under version control system.
95 96 97 98 99 100 101 102 103 104 105 106
* VC Directory Mode::   Listing files managed by version control.
* Branches::            Multiple lines of development.
@ifnottex
* 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,
107 108 109 110 111
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
112
altering repository settings, are not supported in VC@.  You should
113
perform such tasks outside VC, e.g., via the command line.
114 115 116 117 118 119 120

  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
121
* Why Version Control?::    Understanding the problems it addresses.
122 123
* Version Control Systems:: Supported version control back-end systems.
* VCS Concepts::            Words and concepts related to version control.
124 125 126
* VCS Merging::             How file conflicts are handled.
* VCS Changesets::          How changes are grouped.
* VCS Repositories::        Where version control repositories are stored.
127 128 129 130
* Types of Log File::       The VCS log in contrast to the ChangeLog.
@end menu

@node Why Version Control?
131
@subsubsection Understanding the Problems it Addresses
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147

  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,
148 149 150 151
such as explanatory comments about the intention behind each change.
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.
152 153 154 155 156 157
@end itemize

@node Version Control Systems
@subsubsection Supported Version Control Systems

@cindex back end (version control)
158 159
  VC currently works with many different version control systems,
which it refers to as @dfn{back ends}:
160 161 162 163 164 165 166

@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
167
missing in SCCS (e.g., tag names for releases) by implementing them
168 169 170 171 172
itself.  Other VC features, such as multiple branches, are simply
unavailable.  Since SCCS is non-free, we recommend avoiding it.

@cindex CSSC
@item
173
CSSC is a free replacement for SCCS@.  You should use CSSC only if, for
174 175 176 177 178 179
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
180 181 182
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.
183 184 185

@cindex CVS
@item
186 187 188 189 190 191
CVS is the free version control system that was, until circa 2008,
used by the majority of free software projects.  Since then, it has
been superseded by newer systems.  CVS allows concurrent 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.
192 193 194 195

@cindex SVN
@cindex Subversion
@item
196
Subversion (svn) is a free version control system designed to be
197 198 199
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).
200 201 202

@cindex git
@item
203
Git is a decentralized version control system originally invented by
204
Linus Torvalds to support development of Linux (his kernel).  VC
205
supports many common Git operations, but others, such as repository
206
syncing, must be done from the command line.
207 208 209 210

@cindex hg
@cindex Mercurial
@item
211
Mercurial (hg) is a decentralized version control system broadly
212
resembling Git.  VC supports most Mercurial commands, with the
213
exception of repository sync operations.
214 215 216 217

@cindex bzr
@cindex Bazaar
@item
218 219
Bazaar (bzr) is a decentralized version control system that supports
both repository-based and decentralized versioning.  VC supports most
220
basic editing operations under Bazaar.
221

Eric S. Raymond's avatar
Eric S. Raymond committed
222 223 224
@cindex SRC
@cindex src
@item
225
SRC (src) is RCS, reloaded---a specialized version-control system
226
designed for single-file projects worked on by only one person.  It
Eric S. Raymond's avatar
Eric S. Raymond committed
227
allows multiple files with independent version-control histories to
228
exist in one directory, and is thus particularly well suited for
Eric S. Raymond's avatar
Eric S. Raymond committed
229 230 231 232
maintaining small documents, scripts, and dotfiles.  While it uses RCS
for revision storage, it presents a modern user interface featuring
lockless operation and integer sequential version numbers.  VC
supports almost all SRC operations.
233
@end itemize
Eric S. Raymond's avatar
Eric S. Raymond committed
234

235 236 237 238 239 240 241 242 243 244 245 246 247 248
@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
249 250 251
  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
252 253
may @dfn{commit} (or @dfn{check in}) the changes; this records the
changes in the repository, along with a descriptive log entry.
254

255 256 257
@cindex working tree
  A directory tree of work files is called a @dfn{working tree}.

258 259
@cindex revision
@cindex revision ID
260 261 262 263 264
  Each commit creates a new @dfn{revision} in the repository.  The
version control system keeps track of all past revisions and the
changes that were made in each revision.  Each revision is named by a
@dfn{revision ID}, whose format depends on the version control system;
in the simplest case, it is just an integer.
265 266

  To go beyond these basic concepts, you will need to understand three
267 268 269 270
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.
271

272
@node VCS Merging
273
@subsubsection Merge-based vs Lock-based Version Control
274

275 276 277 278
  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.

279
@cindex merging-based version
280 281 282 283
  In a version control system that uses merging, each user may modify
a work file at any time.  The system lets you @dfn{merge} your work
file, which may contain changes that have not been committed, with the
latest changes that others have committed.
284

285
@cindex locking-based version
286 287 288 289 290 291
  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
292
(@pxref{Interlocking}).  When you commit your changes, that unlocks
293 294 295 296 297 298 299
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
300 301
conflicts} happen when you commit a change to a file that conflicts
with a change committed by someone else after your checkout.  Both
302
kinds of conflict have to be resolved by human judgment and
303 304 305
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.
306 307 308 309

  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.
310 311
Decentralized version control systems, such as Git and Mercurial, are
exclusively merging-based.
312

313
  VC mode supports both locking and merging version control.  The
314 315 316 317 318 319 320
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
321

322
@cindex file-based version control
323 324 325 326 327 328 329 330
  On SCCS, RCS, CVS, and other early version control systems (and also
in SRC), version control operations are @dfn{file-based}: each file
has its own comment and revision history separate from that of all
other files.  Newer systems, beginning with Subversion, are
@dfn{changeset-based}: a commit 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.
331

332
@cindex changeset-based version control
333 334 335
  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
336
all of it.
337

338 339 340 341 342
@node VCS Repositories
@subsubsection Decentralized vs Centralized Repositories

@cindex centralized version control
@cindex decentralized version control
343
@cindex distributed version control
344 345
  Early version control systems were designed around a
@dfn{centralized} model in which each project has only one repository
346
used by all developers.  SCCS, RCS, CVS, Subversion, and SRC share this
347 348
kind of model.  One of its drawbacks is that the repository is a choke
point for reliability and efficiency.
349

350 351 352 353 354 355 356
  GNU Arch pioneered the concept of @dfn{distributed} or
@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 change histories.  In
effect, there is one repository for each developer, and repository
merges take the place of commit operations.
357

358 359 360
  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.
361 362 363 364 365 366 367 368 369

@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:
370 371 372
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}.
373 374 375 376 377 378

  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.
379 380 381 382 383 384 385
@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
Xue Fuqiao's avatar
Xue Fuqiao committed
386 387 388
single directory separately from those of other directories.  Another
advantage is that commit logs can't be fixed in many version control
systems.
389 390 391 392 393 394 395 396 397

  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
398
@kbd{C-c C-a} when committing the change (@pxref{Log Buffer}).  Or you
399 400 401
can write the entry in the log buffer while committing the change
(with the help of @kbd{C-c C-w}), and later use the @kbd{C-x v a}
command to copy it to @file{ChangeLog}
402 403 404 405 406 407 408 409 410
@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
411
@cindex VC mode line indicator
412 413

  When you visit a file that is under version control, Emacs indicates
414 415
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.
416

417
@cindex version control status
418
  The character between the back-end name and the revision ID
419 420 421 422 423
indicates the @dfn{version control status} of the work file.  In a
merge-based version control system, a @samp{-} character indicates
that the work file is 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
Xue Fuqiao's avatar
Xue Fuqiao committed
424
was removed from the version control.  Finally, @samp{?} means that
425 426
the file is under version control, but is missing from the working
tree.
427 428 429

  In a lock-based system, @samp{-} indicates an unlocked file, and
@samp{:} a locked file; if the file is locked by another user (for
430
instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
431
@samp{@@} means that the file was locally added, but not yet committed
432
to the master repository.
433 434

  On a graphical display, you can move the mouse over this mode line
Paul Eggert's avatar
Paul Eggert committed
435
indicator to pop up a tool-tip, which displays a more verbose
436
description of the version control status.  Pressing @kbd{mouse-1}
437 438
over the indicator pops up a menu of VC commands, identical to
@samp{Tools / Version Control} on the menu bar.
439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454

@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

455
@cindex filesets, VC
456
@cindex VC filesets
457
   Most VC commands operate on @dfn{VC filesets}.  A VC fileset is a
458 459 460 461
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
462 463
consists of the marked files (@pxref{VC Directory Mode}).

464 465 466 467 468 469 470
  On modern changeset-based version control systems (@pxref{VCS
Changesets}), VC commands handle multi-file VC filesets as a group.
For example, committing a multi-file VC fileset generates a single
revision, containing the changes to all those files.  On older
file-based version control systems like CVS, each file in a multi-file
VC fileset is handled individually; for example, a commit generates
one revision for each changed file.
471 472

@table @kbd
473
@item C-x v v
474 475
Perform the next appropriate version control operation on the current
VC fileset.
476 477 478 479
@end table

@findex vc-next-action
@kindex C-x v v
480
  The principal VC command is a multi-purpose command, @kbd{C-x v v}
Paul Eggert's avatar
Paul Eggert committed
481
(@code{vc-next-action}), which performs the most appropriate
482 483 484 485 486 487
action on the current VC fileset: either registering it with a version
control system, or committing it, or unlocking it, or merging changes
into it.  The precise actions are described in detail in the following
subsections.  You can use @kbd{C-x v v} either in a file-visiting
buffer or in a VC Directory buffer.

Paul Eggert's avatar
Paul Eggert committed
488
  Note that VC filesets are distinct from the named filesets used
489 490 491
for viewing and visiting files in functional groups
(@pxref{Filesets}).  Unlike named filesets, VC filesets are not named
and don't persist across sessions.
492 493 494 495 496 497 498 499 500 501

@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

502
  On a merging-based version control system (i.e., most modern ones;
503
@pxref{VCS Merging}), @kbd{C-x v v} does the following:
504 505 506

@itemize @bullet
@item
507
If there is more than one file in the VC fileset and the files have
508
inconsistent version control statuses, signal an error.  (Note,
Paul Eggert's avatar
Paul Eggert committed
509 510
however, that a fileset is allowed to include both newly-added
files and modified files; @pxref{Registering}.)
511 512

@item
513
If none of the files in the VC fileset are registered with a version
514
control system, register the VC fileset, i.e., place it under version
515 516 517
control.  @xref{Registering}.  If Emacs cannot find a system to
register under, it prompts for a repository type, creates a new
repository, and registers the VC fileset with it.
518 519

@item
520
If every work file in the VC fileset is unchanged, do nothing.
521 522

@item
523
If every work file in the VC fileset has been modified, commit the
524
changes.  To do this, Emacs pops up a @file{*vc-log*} buffer; type the
525
desired log entry for the new revision, followed by @kbd{C-c C-c} to
526
commit.  @xref{Log Buffer}.
527 528

If committing to a shared repository, the commit may fail if the
529
repository has been changed since your last update.  In that
530
case, you must perform an update before trying again.  On a
Glenn Morris's avatar
Glenn Morris committed
531 532 533 534
decentralized version control system, use @kbd{C-x v +}
(@pxref{Pulling / Pushing}) or @kbd{C-x v m} (@pxref{Merging}).
On a centralized version control system, type @kbd{C-x v v} again to
merge in the repository changes.
535 536

@item
537 538 539
Finally, if you are using a centralized version control system, check
if each work file in the VC fileset is up-to-date.  If any file has
been changed in the repository, offer to update it.
540 541
@end itemize

Paul Eggert's avatar
Paul Eggert committed
542
  These rules also apply when you use RCS in its non-locking mode,
543
except that changes are not automatically merged from the repository.
544
Nothing informs you if another user has committed changes in the same
545 546 547 548 549 550 551
file since you began editing it; when you commit your revision, that
other user's 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 committing 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}).
552 553 554 555

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

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

559
@itemize @bullet
560
@item
561
If there is more than one file in the VC fileset and the files have
562
inconsistent version control statuses, signal an error.
563 564 565

@item
If each file in the VC fileset is not registered with a version
566 567 568 569
control system, register the VC fileset.  @xref{Registering}.  If
Emacs cannot find a system to register under, it prompts for a
repository type, creates a new repository, and registers the VC
fileset with it.
570 571

@item
Paul Eggert's avatar
Paul Eggert committed
572
If each file is registered and unlocked, lock it and make it writable,
573
so that you can begin to edit it.
574 575

@item
576
If each file is locked by you and contains changes, commit the
577
changes.  To do this, Emacs pops up a @file{*vc-log*} buffer; type the
578 579
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit (@pxref{Log Buffer}).
580 581

@item
582 583
If each file is locked by you, but you have not changed it, release
the lock and make the file read-only again.
584 585

@item
586
If each file is locked by another user, ask whether you want to
Paul Eggert's avatar
Paul Eggert committed
587
steal the lock.  If you say yes, the file becomes locked by you,
588 589
and a warning message is sent to the user who had formerly locked the
file.
590 591 592
@end itemize

  These rules also apply when you use CVS in locking mode, except
593
that CVS does not support stealing locks.
594 595 596 597

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

598
@cindex revision ID in version control
599 600 601 602 603 604 605
  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
606 607 608 609
@cindex specific version control system
You can specify the name of a version control system.  This is useful
if the fileset can be managed by more than one version control system,
and Emacs fails to detect the correct one.
610 611

@item
612
Otherwise, if using CVS, RCS or SRC, you can specify a revision ID.
613

614
If the fileset is modified (or locked), this makes Emacs commit with
615
that revision ID@.  You can create a new branch by supplying an
616
appropriate revision ID (@pxref{Branches}).
617

618 619 620
If the fileset is unmodified (and unlocked), this checks the specified
revision into the working tree.  You can also specify a revision on
another branch by giving its revision or branch ID (@pxref{Switching
621
Branches}).  An empty argument (i.e., @kbd{C-u C-x v v @key{RET}})
Paul Eggert's avatar
Paul Eggert committed
622
checks out the latest (head) revision on the current branch.
623

624
This is silently ignored on a decentralized version control system.
625
Those systems do not let you specify your own revision IDs, nor do
Paul Eggert's avatar
Paul Eggert committed
626
they use the concept of checking out individual files.
627 628 629
@end itemize

@node Log Buffer
630 631
@subsection Features of the Log Entry Buffer

632
@kindex C-c C-c @r{(Log Edit mode)}
633 634
@findex log-edit-done
  When you tell VC to commit a change, it pops up a buffer named
635
@file{*vc-log*}.  In this buffer, you should write a @dfn{log entry}
636
describing the changes you have made (@pxref{Why Version Control?}).
637 638
After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
the buffer and commit the change, together with your log entry.
639

640 641 642
@cindex Log Edit mode
@cindex mode, Log Edit
@vindex vc-log-mode-hook
Xue Fuqiao's avatar
Xue Fuqiao committed
643
@c FIXME: Mention log-edit-mode-hook here?  --xfq
644
  The major mode for the @file{*vc-log*} buffer is Log Edit mode, a
645 646 647 648
variant of Text mode (@pxref{Text Mode}).  On entering Log Edit mode,
Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
(@pxref{Hooks}).

649
  In the @file{*vc-log*} buffer, you can write one or more @dfn{header
650 651 652 653 654 655
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:
656

657 658 659
@smallexample
Author: J. R. Hacker <jrh@@example.com>
@end smallexample
660

661 662
@noindent
Apart from the @samp{Author} header, Emacs recognizes the headers
663 664 665 666
@samp{Summary} (a one-line summary of the changeset), @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.  If you specify a header for a system that does not
667
support it, the header is treated as part of the log entry.
668

669
@kindex C-c C-f @r{(Log Edit mode)}
670
@findex log-edit-show-files
671
@kindex C-c C-d @r{(Log Edit mode)}
672
@findex log-edit-show-diff
Paul Eggert's avatar
Paul Eggert committed
673
  While in the @file{*vc-log*} buffer, the current VC fileset is
674 675 676 677 678 679
considered to be the fileset that will be committed if you type
@w{@kbd{C-c C-c}}.  To view a list of the files in the VC fileset,
type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}).  To view a diff
of changes between the VC fileset and the version from which you
started editing (@pxref{Old Revisions}), type @kbd{C-c C-d}
(@code{log-edit-show-diff}).
680

681
@kindex C-c C-w @r{(Log Edit mode)}
682
@findex log-edit-generate-changelog-from-diff
683
  To help generate ChangeLog entries, type @kbd{C-c C-w}
684 685 686 687
(@code{log-edit-generate-changelog-from-diff}), to generate skeleton
ChangeLog entries, listing all changed file and function names based
on the diff of the VC fileset.  Consecutive entries left empty will be
combined by @kbd{C-q} (@code{fill-paragraph}).
688

689 690
@kindex C-c C-a @r{(Log Edit mode)}
@findex log-edit-insert-changelog
691 692
  If the VC fileset includes one or more @file{ChangeLog} files
(@pxref{Change Log}), type @kbd{C-c C-a}
693
(@code{log-edit-insert-changelog}) to pull the relevant entries into
694
the @file{*vc-log*} buffer.  If the topmost item in each
695
@file{ChangeLog} was made under your user name on the current date,
696 697
this command searches that item for entries matching the file(s) to be
committed, and inserts them.
698
@ifnottex
699 700 701
If you are using CVS or RCS, see @ref{Change Logs and VC}, for the
opposite way of working---generating ChangeLog entries from the Log
Edit buffer.
702 703
@end ifnottex

704
  To abort a commit, just @emph{don't} type @kbd{C-c C-c} in that
705
buffer.  You can switch buffers and do other editing.  As long as you
706
don't try to make another commit, the entry you were editing remains
707
in the @file{*vc-log*} buffer, and you can go back to that buffer at
708 709 710 711 712 713
any time to complete the commit.

@kindex M-n @r{(Log Edit mode)}
@kindex M-p @r{(Log Edit mode)}
@kindex M-s @r{(Log Edit mode)}
@kindex M-r @r{(Log Edit mode)}
714
  You can also browse the history of previous log entries to duplicate
715 716 717 718 719
a commit comment.  This can be useful when you want to make several
commits with similar comments.  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 (@pxref{Minibuffer History}), except that they are
used outside the minibuffer.
720

721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756
@node Registering
@subsection Registering a File for Version Control

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

@kindex C-x v i
@findex vc-register
  The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each
file in the current VC fileset, placing it under version control.
This is essentially equivalent to the action of @kbd{C-x v v} on an
unregistered VC fileset (@pxref{Basic VC Editing}), except that if the
VC fileset is already registered, @kbd{C-x v i} signals an error
whereas @kbd{C-x v v} performs some other action.

  To register a file, Emacs must choose a version control system.  For
a multi-file VC fileset, the VC Directory buffer specifies the system
to use (@pxref{VC Directory Mode}).  For a single-file VC fileset, if
the file's directory already contains files registered in a version
control system, or if the directory is part of a directory tree
controlled by a version control system, Emacs chooses that system.  In
the event that more than one version control system is applicable,
Emacs uses the one that appears first in the variable
@iftex
@code{vc-handled-backends}.
@end iftex
@ifnottex
@code{vc-handled-backends} (@pxref{Customizing VC}).
@end ifnottex
If Emacs cannot find a version control system to register the file
under, it prompts for a repository type, creates a new repository, and
registers the file into that repository.

  On most version control systems, registering a file with @kbd{C-x v
Paul Eggert's avatar
Paul Eggert committed
757
i} or @kbd{C-x v v} adds it to the working tree but not to the
758 759 760
repository.  Such files are labeled as @samp{added} in the VC
Directory buffer, and show a revision ID of @samp{@@@@} in the mode
line.  To make the registration take effect in the repository, you
761 762
must perform a commit (@pxref{Basic VC Editing}).  Note that a single
commit can include both file additions and edits to existing files.
763 764 765

  On a locking-based version control system (@pxref{VCS Merging}),
registering a file leaves it unlocked and read-only.  Type @kbd{C-x v
766
v} to start editing it.
767 768 769 770 771 772

@node Old Revisions
@subsection Examining And Comparing Old Revisions

@table @kbd
@item C-x v =
773 774 775 776 777 778 779
Compare the work files in the current VC fileset with the versions you
started from (@code{vc-diff}).  With a prefix argument, prompt for two
revisions of the current VC fileset and compare them.  You can also
call this command from a Dired buffer (@pxref{Dired}).

@ifnottex
@item M-x vc-ediff
780
Like @kbd{C-x v =}, but using Ediff.  @xref{Top,, Ediff, ediff, The
781
Ediff Manual}.
782
@end ifnottex
783 784

@item C-x v D
785 786 787
Compare the entire working tree to the revision you started from
(@code{vc-root-diff}).  With a prefix argument, prompt for two
revisions and compare their trees.
788 789 790 791

@item C-x v ~
Prompt for a revision of the current file, and visit it in a separate
buffer (@code{vc-revision-other-window}).
792 793

@item C-x v g
794 795
Display an annotated version of the current file: for each line, show
the latest revision in which it was modified (@code{vc-annotate}).
796 797 798 799
@end table

@findex vc-diff
@kindex C-x v =
800 801 802 803 804 805 806
  @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares
each work file in the current VC fileset to the version(s) from which
you started editing.  The diff is displayed in another window, in a
Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}.  The
usual Diff mode commands are available in this buffer.  In particular,
the @kbd{g} (@code{revert-buffer}) command performs the file
comparison again, generating a new diff.
807

808 809 810
@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
811 812 813
prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
diff between those versions of the fileset.  This will not work
reliably for multi-file VC filesets, if the version control system is
814
file-based rather than changeset-based (e.g., CVS), since then
815 816 817 818 819 820 821 822 823 824 825 826 827 828
revision IDs for different files would not be related in any
meaningful way.

  Instead of the revision ID, some version control systems let you
specify revisions in other formats.  For instance, under Bazaar you
can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =}
(and related commands) to specify the first revision committed after
yesterday.  See the documentation of the version control system for
details.

  If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
(@pxref{Dired}), the file listed on the current line is treated as the
current VC fileset.

829
@ifnottex
830 831
@findex vc-ediff
  @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
832
Ediff session.  @xref{Top,, Ediff, ediff, The Ediff Manual}.
833 834
@end ifnottex

835 836 837
@findex vc-root-diff
@kindex C-x v D
  @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
838
it displays the changes in the entire current working tree (i.e., the
839 840 841
working tree containing the current VC fileset).  If you invoke this
command from a Dired buffer, it applies to the working tree containing
the directory.
842

843 844 845 846 847 848 849 850
@findex vc-root-version-diff
@kindex C-u C-x v D
  To compare two arbitrary revisions of the whole trees, call
@code{vc-root-diff} with a prefix argument: @kbd{C-u C-x v D}.  This
prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
diff between those versions of the entire version-controlled directory
trees (RCS, SCCS, CVS, and SRC do not support this feature).

851
@vindex vc-diff-switches
852 853 854 855 856
  You can customize the @command{diff} options that @kbd{C-x v =} and
@kbd{C-x v D} use for generating diffs.  The options used are taken
from the first non-@code{nil} value amongst the variables
@code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
@code{diff-switches} (@pxref{Comparing Files}), in that order.  Here,
857
@var{backend} stands for the relevant version control system,
858
e.g., @code{bzr} for Bazaar.  Since @code{nil} means to check the
859 860 861
next variable in the sequence, either of the first two may use the
value @code{t} to mean no switches at all.  Most of the
@code{vc-@var{backend}-diff-switches} variables default to @code{nil},
862 863 864
but some default to @code{t}; these are for version control systems
whose @code{diff} implementations do not accept common diff options,
such as Subversion.
865 866 867 868 869 870 871 872 873

@findex vc-revision-other-window
@kindex C-x v ~
  To directly examine an older version of a file, visit the work file
and type @kbd{C-x v ~ @var{revision} @key{RET}}
(@code{vc-revision-other-window}).  This retrieves the file version
corresponding to @var{revision}, saves it to
@file{@var{filename}.~@var{revision}~}, and visits it in a separate
window.
874 875

@findex vc-annotate
876
@vindex vc-annotate-background-mode
877
@kindex C-x v g
878 879
  Many version control systems allow you to view files @dfn{annotated}
with per-line revision information, by typing @kbd{C-x v g}
880
(@code{vc-annotate}).  This creates a new ``annotate'' buffer
881 882 883 884 885 886 887 888
displaying the file's text, with each line colored to show how old it
is.  Red text is new, blue is 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.  If the variable @code{vc-annotate-background-mode}
is non-@code{nil}, the colors expressing the age of each line are
applied to the background color, leaving the foreground at its default
color.
889 890

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

895
  From the ``annotate'' buffer, these and other color scaling options are
896 897 898 899 900 901
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
902
Annotate the previous revision, i.e., the revision before the one
903 904
currently annotated.  A numeric prefix argument is a repeat count, so
@kbd{C-u 10 p} would take you back 10 revisions.
905 906

@item n
907
Annotate the next revision, i.e., the revision after the one
908
currently annotated.  A numeric prefix argument is a repeat count.
909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946

@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

947
@node VC Change Log
948
@subsection VC Change Log
949
@cindex VC change log
950 951 952

@table @kbd
@item C-x v l
953
Display the change history for the current fileset
954 955 956 957 958
(@code{vc-print-log}).

@item C-x v L
Display the change history for the current repository
(@code{vc-print-root-log}).
959 960

@item C-x v I
961
Display the changes that a ``pull'' operation will retrieve
962 963 964
(@code{vc-log-incoming}).

@item C-x v O
965
Display the changes that will be sent by the next ``push'' operation
966
(@code{vc-log-outgoing}).
967 968 969 970

@item C-x v h
Display the history of changes made in the region of file visited by
the current buffer (@code{vc-region-history}).
971 972 973 974
@end table

@kindex C-x v l
@findex vc-print-log
975 976 977 978 979
  @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named
@file{*vc-change-log*}, showing the history of changes made to the
current file, including who made the changes, the dates, and the log
entry for each change (these are the same log entries you would enter
via the @file{*vc-log*} buffer; @pxref{Log Buffer}).  Point is
980 981 982 983 984 985 986
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.

  If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
file listed on the current line.
987

988
@kindex C-x v L
989
@findex vc-print-root-log
990 991
@findex log-view-toggle-entry-display
  @kbd{C-x v L} (@code{vc-print-root-log}) displays a
992
@file{*vc-change-log*} buffer showing the history of the entire
993 994
version-controlled directory tree (RCS, SCCS, CVS, and SRC do not
support this feature).  With a prefix argument, the command prompts
995 996
for the maximum number of revisions to display.  A numeric prefix
argument specifies the maximum number of revisions without prompting.
997 998 999 1000 1001 1002 1003 1004
When the numeric prefix argument is 1, as in @w{@kbd{C-1 C-x v L}} or
@w{@kbd{C-u 1 C-x v L}}, the command prompts for the revision ID, and
displays the log entry of that revision together with the changes
(diffs) it introduced.  (Some less capable version control systems,
such as RCS and CVS, don't have commands to show a revision log with
its diffs; for them the command displays only the log entry, and you
can request to show the diffs by typing @kbd{d} or @kbd{D}, see
below.)
1005 1006

  The @kbd{C-x v L} history is shown in a compact form, usually
1007 1008
showing only the first line of each log entry.  However, you can type
@key{RET} (@code{log-view-toggle-entry-display}) in the
1009
@file{*vc-change-log*} buffer to reveal the entire log entry for the
1010
revision at point.  A second @key{RET} hides it again.
1011

1012 1013 1014 1015
@kindex C-x v I
@kindex C-x v O
@findex vc-log-incoming
@findex vc-log-outgoing
1016
  On a decentralized version control system, the @kbd{C-x v I}
1017 1018
(@code{vc-log-incoming}) command displays a log buffer showing the
changes that will be applied, the next time you run the version
Paul Eggert's avatar
Paul Eggert committed
1019
control system's pull command to get new revisions from another
Glenn Morris's avatar
Glenn Morris committed
1020
repository (@pxref{Pulling / Pushing}).  This other repository is the default
1021 1022 1023 1024
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.  Similarly, @kbd{C-x v O}
(@code{vc-log-outgoing}) shows the changes that will be sent to
Paul Eggert's avatar
Paul Eggert committed
1025
another repository, the next time you run the push command; with a
1026
prefix argument, it prompts for a specific destination repository.
1027

1028 1029
@cindex VC log buffer, commands in
@cindex vc-log buffer
1030
  In the @file{*vc-change-log*} buffer, you can use the following keys
1031 1032
to move between the logs of revisions and of files, and to examine and
compare past revisions (@pxref{Old Revisions}):
1033 1034 1035

@table @kbd
@item p
1036
Move to the previous revision entry.  (Revision entries in the log
1037 1038 1039 1040 1041
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
1042 1043
Move to the next revision entry.  A numeric prefix argument is a
repeat count.
1044 1045

@item P
1046 1047 1048
Move to the log of the previous file, if showing logs for a multi-file
VC fileset.  Otherwise, just move to the beginning of the log.  A
numeric prefix argument is a repeat count.
1049 1050

@item N
1051 1052
Move to the log of the next file, if showing logs for a multi-file VC
fileset.  A numeric prefix argument is a repeat count.
1053 1054

@item a
1055
Annotate the revision on the current line (@pxref{Old Revisions}).
1056 1057 1058 1059 1060 1061

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

@item f
1062
Visit the revision indicated at the current line.
1063 1064

@item d
1065 1066
Display a diff between the revision at point and the next earlier
revision, for the specific file.
1067 1068

@item D
1069 1070 1071 1072 1073
Display the changeset diff between the revision at point and the next
earlier revision.  This shows the changes to all files made in that
revision.

@item @key{RET}
1074
In a compact-style log buffer (e.g., the one created by @kbd{C-x v
1075 1076
L}), toggle between showing and hiding the full log entry for the
revision at point.
1077 1078
@end table

1079 1080
@vindex vc-log-show-limit
Because fetching many log entries can be slow, the
1081
@file{*vc-change-log*} buffer displays no more than 2000 revisions by
1082 1083 1084
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
1085
@file{*vc-change-log*} buffer by clicking on the @samp{Show 2X
1086
entries} or @samp{Show unlimited entries} buttons at the end of the
1087
buffer.  However, RCS, SCCS, CVS, and SRC do not support this feature.
1088

Kaushal Modi's avatar
Kaushal Modi committed
1089
@kindex C-x v h
Eli Zaretskii's avatar
Eli Zaretskii committed
1090
@findex vc-region-history
1091
A useful variant of examining history of changes is provided by the command
Kaushal Modi's avatar
Kaushal Modi committed
1092
@kbd{vc-region-history} (by default bound to @kbd{C-x v h}), which shows
1093 1094
a @file{*VC-history*} buffer with the history of changes made in the region
of the current buffer's file between point and the mark (@pxref{Mark}).  The
Kaushal Modi's avatar
Kaushal Modi committed
1095 1096
history of changes includes the commit log messages and also the
changes themselves in the Diff format.
Eli Zaretskii's avatar
Eli Zaretskii committed
1097

1098
Invoke this command after marking in the current buffer the region in
Eli Zaretskii's avatar
Eli Zaretskii committed
1099 1100 1101 1102 1103
whose changes you are interested.  In the @file{*VC-history*} buffer
it pops up, you can use all of the commands available in the
@file{*vc-change-log*} buffer described above, and also the commands
defined by Diff mode (@pxref{Diff Mode}).

1104
This command is currently available only with Git and Mercurial (hg).
Eli Zaretskii's avatar
Eli Zaretskii committed
1105

1106
@node VC Undo
1107
@subsection Undoing Version Control Actions
1108 1109 1110

@table @kbd
@item C-x v u
1111 1112
Revert the work file(s) in the current VC fileset to the last revision
(@code{vc-revert}).
1113 1114 1115
@end table

@kindex C-x v u
1116 1117 1118
@findex vc-revert
@vindex vc-revert-show-diff
  If you want to discard all the changes you have made to the current
Glenn Morris's avatar
Glenn Morris committed
1119
VC fileset, type @kbd{C-x v u} (@code{vc-revert}).  This shows
1120 1121 1122 1123 1124
you a diff between the work file(s) and the revision from which you
started editing, and asks for confirmation for discarding the changes.
If you agree, the fileset is reverted.  If you don't want @kbd{C-x v
u} to show a diff, set the variable @code{vc-revert-show-diff} to
@code{nil} (you can still view the diff directly with @kbd{C-x v =};
1125
@pxref{Old Revisions}).
1126 1127 1128 1129 1130

  On locking-based version control systems, @kbd{C-x v u} leaves files
unlocked; you must lock again to resume editing.  You can also use
@kbd{C-x v u} to unlock a file if you lock it and then decide not to
change it.
1131

Xue Fuqiao's avatar