/
maintaining.texi
2426 lines (2027 loc) · 97.5 KB
/
maintaining.texi
1
2
3
4
5
6
7
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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
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
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
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
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
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
757
758
759
760
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
843
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
899
900
901
902
903
904
905
906
907
908
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
947
948
949
950
951
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
@c This is part of the Emacs manual., Abbrevs, This is part of the Emacs manual., Top
@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2015 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Maintaining
@chapter Maintaining Large Programs
This chapter describes Emacs features for maintaining large
programs. If you are maintaining a large Lisp program, then in
addition to the features described here, you may find
the Emacs Lisp Regression Testing (ERT) library useful
(@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}).
@menu
* Version Control:: Using version control systems.
* 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.
* EDE:: An integrated development environment for Emacs.
@ifnottex
* Emerge:: A convenient way of merging two versions of a program.
@end ifnottex
@end menu
@node Version Control
@section Version Control
@cindex version control
A @dfn{version control system} is a program that can record multiple
versions of a source file, storing information such as the creation
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 Bazaar, CVS, Git, Mercurial, Monotone, RCS,
SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS,
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}
@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.
* Log Buffer:: Features available in log entry buffers.
* Registering:: Putting a file under version control.
* Old Revisions:: Examining and comparing old versions.
* VC Change Log:: Viewing the VC Change Log.
* VC Undo:: Canceling changes before or after committing.
* VC Ignore:: Ignore files under version control system.
* 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,
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.
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
* Why Version Control?:: Understanding the problems it addresses.
* Version Control Systems:: Supported version control back-end systems.
* VCS Concepts:: Words and concepts related to version control.
* VCS Merging:: How file conflicts are handled.
* VCS Changesets:: How changes are grouped.
* VCS Repositories:: Where version control repositories are stored.
* 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)
VC currently works with many different version control systems,
which it refers to as @dfn{back ends}:
@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
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.
@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
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.
@cindex SVN
@cindex Subversion
@item
Subversion (svn) is a free version control system designed to be
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).
@cindex git
@item
Git is a decentralized version control system originally invented by
Linus Torvalds to support development of Linux (his kernel). VC
supports many common Git operations, but others, such as repository
syncing, must be done from the command line.
@cindex hg
@cindex Mercurial
@item
Mercurial (hg) is a decentralized version control system broadly
resembling Git. VC supports most Mercurial commands, with the
exception of repository sync operations.
@cindex bzr
@cindex Bazaar
@item
Bazaar (bzr) is a decentralized version control system that supports
both repository-based and decentralized versioning. VC supports most
basic editing operations under Bazaar.
@cindex SRC
@cindex src
@item
SRC (src) is RCS, reloaded - a specialized version-control system
designed for single-file projects worked on by only one person. It
allows multiple files with independent version-control histories to
exist in one directory, and is thus particularly well suited for
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.
@end itemize
@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
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
may @dfn{commit} (or @dfn{check in}) the changes; this records the
changes in the repository, along with a descriptive log entry.
@cindex working tree
A directory tree of work files is called a @dfn{working tree}.
@cindex revision
@cindex revision ID
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.
To go beyond these basic concepts, you will need to understand three
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.
@node VCS Merging
@subsubsection Merge-based vs lock-based Version Control
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.
@cindex merging-based version
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.
@cindex locking-based version
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
(@pxref{Interlocking}). When you commit your changes, that unlocks
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
conflicts} happen when you commit a change to a file that conflicts
with a change committed by someone else after your checkout. Both
kinds of conflict have to be resolved by human judgment and
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.
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.
Decentralized version control systems, such as Git and Mercurial, are
exclusively merging-based.
VC mode supports both locking and merging version control. The
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
@cindex file-based version control
On SCCS, RCS, CVS, and other early version control systems, 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.
@cindex changeset-based version control
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
all of it.
@node VCS Repositories
@subsubsection Decentralized vs Centralized Repositories
@cindex centralized version control
@cindex decentralized version control
@cindex distributed version control
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
kind of model. One of its drawbacks is that the repository is a choke
point for reliability and efficiency.
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.
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.
@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:
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}.
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.
@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. Another
advantage is that commit logs can't be fixed in many version control
systems.
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 committing the change (@pxref{Log Buffer}). Or you
can write the entry in the log buffer while committing 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
@cindex VC mode line indicator
When you visit a file that is under version control, Emacs indicates
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.
@cindex version control status
The character between the back-end name and the revision ID
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
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
instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
@samp{@@} means that the file was locally added, but not yet committed
to the master repository.
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}
over the indicator pops up a menu of VC commands, identical to
@samp{Tools / Version Control} on the menu bar.
@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
@cindex filesets, VC
@cindex VC filesets
Most VC commands operate on @dfn{VC filesets}. A VC fileset is a
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
consists of the marked files (@pxref{VC Directory Mode}).
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.
@table @kbd
@item C-x v v
Perform the next appropriate version control operation on the current
VC fileset.
@end table
@findex vc-next-action
@kindex C-x v v
The principal VC command is a multi-purpose command, @kbd{C-x v v}
(@code{vc-next-action}), which performs the most appropriate
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.
Note that 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
On a merging-based version control system (i.e., most modern ones;
@pxref{VCS Merging}), @kbd{C-x v v} does the following:
@itemize @bullet
@item
If there is more than one file in the VC fileset and the files have
inconsistent version control statuses, signal an error. (Note,
however, that a fileset is allowed to include both newly-added
files and modified files; @pxref{Registering}.)
@item
If none of the files in the VC fileset are registered with a version
control system, register the VC fileset, i.e., place it under version
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.
@item
If every work file in the VC fileset is unchanged, do nothing.
@item
If every work file in the VC fileset has been modified, commit the
changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit. @xref{Log Buffer}.
If committing to a shared repository, the commit may fail if the
repository that has been changed since your last update. In that
case, you must perform an update before trying again. On a
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.
@item
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.
@end itemize
These rules also apply when you use RCS in its non-locking mode,
except that changes are not automatically merged from the repository.
Nothing informs you if another user has committed changes in the same
file since you began editing it; when you commit your revision, his
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}).
@node VC With A Locking VCS
@subsubsection Basic Version Control with Locking
On a locking-based version control system (such as SCCS, and RCS in
its default mode), @kbd{C-x v v} does the following:
@itemize @bullet
@item
If there is more than one file in the VC fileset and the files have
inconsistent version control statuses, signal an error.
@item
If each file in the VC fileset is not registered with a version
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.
@item
If each file is registered and unlocked, lock it and make it writable,
so that you can begin to edit it.
@item
If each file is locked by you and contains changes, commit the
changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit (@pxref{Log Buffer}).
@item
If each file is locked by you, but you have not changed it, release
the lock and make the file read-only again.
@item
If each file is locked by another user, ask whether you want to
steal the lock. If you say yes, the file becomes locked by you,
and a warning message is sent to the user who had formerly locked the
file.
@end itemize
These rules also apply when you use CVS in locking mode, except
that CVS does not support stealing locks.
@node Advanced C-x v v
@subsubsection Advanced Control in @kbd{C-x v v}
@cindex revision ID in version control
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
@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.
@item
Otherwise, if using CVS or RCS, you can specify a revision ID.
If the fileset is modified (or locked), this makes Emacs commit with
that revision ID@. You can create a new branch by supplying an
appropriate revision ID (@pxref{Branches}).
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
Branches}). An empty argument (i.e., @kbd{C-u C-x v v @key{RET}})
checks out the latest (head) revision on the current branch.
This is silently ignored on a decentralized version control system.
Those systems do not let you specify your own revision IDs, nor do
they use the concept of checking out individual files.
@end itemize
@node Log Buffer
@subsection Features of the Log Entry Buffer
@cindex C-c C-c @r{(Log Edit mode)}
@findex log-edit-done
When you tell VC to commit a change, it pops up a buffer named
@file{*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} (@code{log-edit-done}) to exit
the buffer and commit the change, together with your log entry.
@cindex Log Edit mode
@cindex mode, Log Edit
@vindex vc-log-mode-hook
@c FIXME: Mention log-edit-mode-hook here? --xfq
The major mode for the @file{*vc-log*} buffer is Log Edit mode, a
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}).
In the @file{*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:
@smallexample
Author: J. R. Hacker <jrh@@example.com>
@end smallexample
@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 recognize only @samp{Author} and
@samp{Date}. If you specify a header for a system that does not
support it, the header is treated as part of the log entry.
@kindex C-c C-f @r{(Log Edit mode)}
@findex log-edit-show-files
@kindex C-c C-d @r{(Log Edit mode)}
@findex log-edit-show-diff
While in the @file{*vc-log*} buffer, the current VC fileset is
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}).
@kindex C-c C-a @r{(Log Edit mode)}
@findex log-edit-insert-changelog
If the 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 @file{*vc-log*} buffer. If the topmost item in each
@file{ChangeLog} was made under your user name on the current date,
this command searches that item for entries matching the file(s) to be
committed, and inserts them.
@ifnottex
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.
@end ifnottex
To abort a commit, just @emph{don't} type @kbd{C-c C-c} in that
buffer. You can switch buffers and do other editing. As long as you
don't try to make another commit, the entry you were editing remains
in the @file{*vc-log*} buffer, and you can go back to that buffer at
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)}
You can also browse the history of previous log entries to duplicate
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.
@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
i} or @kbd{C-x v v} adds it to the working tree but not to the
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
must perform a commit (@pxref{Basic VC Editing}). Note that a single
commit can include both file additions and edits to existing files.
On a locking-based version control system (@pxref{VCS Merging}),
registering a file leaves it unlocked and read-only. Type @kbd{C-x v
v} to start editing it.
@node Old Revisions
@subsection Examining And Comparing Old Revisions
@table @kbd
@item C-x v =
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
Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The
Ediff Manual}.
@end ifnottex
@item C-x v D
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.
@item C-x v ~
Prompt for a revision of the current file, and visit it in a separate
buffer (@code{vc-revision-other-window}).
@item C-x v g
Display an annotated version of the current file: for each line, show
the latest revision in which it was modified (@code{vc-annotate}).
@end table
@findex vc-diff
@kindex C-x v =
@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.
@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 (@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
file-based rather than changeset-based (e.g., CVS), since then
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.
@ifnottex
@findex vc-ediff
@kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
Ediff session. @xref{Top,, Ediff, ediff, The Ediff Manual}.
@end ifnottex
@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
it displays the changes in the entire current working tree (i.e., the
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.
@vindex vc-diff-switches
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,
@var{backend} stands for the relevant version control system,
e.g., @code{bzr} for Bazaar. 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. Most of the
@code{vc-@var{backend}-diff-switches} variables default to @code{nil},
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.
@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.
@findex vc-annotate
@kindex C-x v g
Many version control systems allow you to view files @dfn{annotated}
with per-line revision information, by typing @kbd{C-x v g}
(@code{vc-annotate}). This creates a new ``annotate'' buffer
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.
When you give a prefix argument to this command, Emacs reads two
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.
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, i.e., 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, i.e., the revision after the one
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 VC Change Log
@subsection VC Change Log
@table @kbd
@item C-x v l
Display the change history for the current fileset
(@code{vc-print-log}).
@item C-x v L
Display the change history for the current repository
(@code{vc-print-root-log}).
@item C-x v I
Display the changes that a ``pull'' operation will retrieve
(@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}).
@end table
@kindex C-x v l
@findex vc-print-log
@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
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.
@findex vc-print-root-log
@findex log-view-toggle-entry-display
@kbd{C-x v L} (@code{vc-print-root-log}) displays a
@file{*vc-change-log*} buffer showing the history of the entire
version-controlled directory tree (RCS, SCCS, and CVS do not support
this feature). With a prefix argument, the command prompts for the
maximum number of revisions to display.
The @kbd{C-x v L} history is shown in a compact form, usually
showing only the first line of each log entry. However, you can type
@key{RET} (@code{log-view-toggle-entry-display}) in the
@file{*vc-change-log*} buffer to reveal the entire log entry for the
revision at point. A second @key{RET} hides it again.
On a decentralized 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 (@pxref{Pulling / Pushing}). 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. 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 destination repository.
In the @file{*vc-change-log*} buffer, you can use the following keys
to move between the logs of revisions and of files, and to examine and
compare past revisions (@pxref{Old Revisions}):
@table @kbd
@item p
Move to the previous revision entry. (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 entry. A numeric prefix argument is a
repeat count.
@item P
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.
@item N
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.
@item a
Annotate the revision on the current line (@pxref{Old Revisions}).
@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.
@item d
Display a diff between the revision at point and the next earlier
revision, for the specific file.
@item D
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}
In a compact-style log buffer (e.g., the one created by @kbd{C-x v
L}), toggle between showing and hiding the full log entry for the
revision at point.
@end table