Mercurial > emacs
comparison man/maintaining.texi @ 83494:b901f4f12f33
Merged from emacs@sv.gnu.org
Patches applied:
* emacs@sv.gnu.org/emacs--devo--0--patch-160
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-161
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-162
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-163
Merge from gnus--rel--5.10
* emacs@sv.gnu.org/emacs--devo--0--patch-164
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-165
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-166
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-167
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-168
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-169
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-170
Merge from gnus--rel--5.10
* emacs@sv.gnu.org/emacs--devo--0--patch-171
Update from CVS: man/mh-e.texi (Folders): Various edits.
* emacs@sv.gnu.org/emacs--devo--0--patch-172
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-58
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-59
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-60
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-61
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-62
Merge from emacs--devo--0
* emacs@sv.gnu.org/gnus--rel--5.10--patch-63
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-64
Update from CVS
git-archimport-id: lorentey@elte.hu--2004/emacs--multi-tty--0--patch-534
author | Karoly Lorentey <lorentey@elte.hu> |
---|---|
date | Wed, 22 Mar 2006 15:16:06 +0000 |
parents | 91970b147f39 |
children | 4b75ae0fccd3 e3bacb89536a |
comparison
equal
deleted
inserted
replaced
83493:1bf2ca323037 | 83494:b901f4f12f33 |
---|---|
12 @menu | 12 @menu |
13 * Change Log:: Maintaining a change history for your program. | 13 * Change Log:: Maintaining a change history for your program. |
14 * Format of ChangeLog:: What the change log file looks like. | 14 * Format of ChangeLog:: What the change log file looks like. |
15 * Tags:: Go direct to any function in your program in one | 15 * Tags:: Go direct to any function in your program in one |
16 command. Tags remembers which file it is in. | 16 command. Tags remembers which file it is in. |
17 * Emerge:: A convenient way of merging two versions of a program. | |
18 @end menu | 17 @end menu |
19 | 18 |
20 @node Change Log | 19 @node Change Log |
21 @section Change Logs | 20 @section Change Logs |
22 | 21 |
844 details. | 843 details. |
845 | 844 |
846 You can also use the collection of tag names to complete a symbol | 845 You can also use the collection of tag names to complete a symbol |
847 name in the buffer. @xref{Symbol Completion}. | 846 name in the buffer. @xref{Symbol Completion}. |
848 | 847 |
849 @node Emerge | |
850 @section Merging Files with Emerge | |
851 @cindex Emerge | |
852 @cindex merging files | |
853 | |
854 It's not unusual for programmers to get their signals crossed and | |
855 modify the same program in two different directions. To recover from | |
856 this confusion, you need to merge the two versions. Emerge makes this | |
857 easier. See also @ref{Comparing Files}, for other ways to compare | |
858 files, and @ref{Top, Ediff,, ediff, The Ediff Manual}. | |
859 | |
860 @menu | |
861 * Overview of Emerge:: How to start Emerge. Basic concepts. | |
862 * Submodes of Emerge:: Fast mode vs. Edit mode. | |
863 Skip Prefers mode and Auto Advance mode. | |
864 * State of Difference:: You do the merge by specifying state A or B | |
865 for each difference. | |
866 * Merge Commands:: Commands for selecting a difference, | |
867 changing states of differences, etc. | |
868 * Exiting Emerge:: What to do when you've finished the merge. | |
869 * Combining in Emerge:: How to keep both alternatives for a difference. | |
870 * Fine Points of Emerge:: Misc. | |
871 @end menu | |
872 | |
873 @node Overview of Emerge | |
874 @subsection Overview of Emerge | |
875 | |
876 To start Emerge, run one of these four commands: | |
877 | |
878 @table @kbd | |
879 @item M-x emerge-files | |
880 @findex emerge-files | |
881 Merge two specified files. | |
882 | |
883 @item M-x emerge-files-with-ancestor | |
884 @findex emerge-files-with-ancestor | |
885 Merge two specified files, with reference to a common ancestor. | |
886 | |
887 @item M-x emerge-buffers | |
888 @findex emerge-buffers | |
889 Merge two buffers. | |
890 | |
891 @item M-x emerge-buffers-with-ancestor | |
892 @findex emerge-buffers-with-ancestor | |
893 Merge two buffers with reference to a common ancestor in a third | |
894 buffer. | |
895 @end table | |
896 | |
897 @cindex merge buffer (Emerge) | |
898 @cindex A and B buffers (Emerge) | |
899 The Emerge commands compare two files or buffers, and display the | |
900 comparison in three buffers: one for each input text (the @dfn{A buffer} | |
901 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging | |
902 takes place. The merge buffer shows the full merged text, not just the | |
903 differences. Wherever the two input texts differ, you can choose which | |
904 one of them to include in the merge buffer. | |
905 | |
906 The Emerge commands that take input from existing buffers use only the | |
907 accessible portions of those buffers, if they are narrowed | |
908 (@pxref{Narrowing}). | |
909 | |
910 If a common ancestor version is available, from which the two texts to | |
911 be merged were both derived, Emerge can use it to guess which | |
912 alternative is right. Wherever one current version agrees with the | |
913 ancestor, Emerge presumes that the other current version is a deliberate | |
914 change which should be kept in the merged version. Use the | |
915 @samp{with-ancestor} commands if you want to specify a common ancestor | |
916 text. These commands read three file or buffer names---variant A, | |
917 variant B, and the common ancestor. | |
918 | |
919 After the comparison is done and the buffers are prepared, the | |
920 interactive merging starts. You control the merging by typing special | |
921 @dfn{merge commands} in the merge buffer (@pxref{Merge Commands}). | |
922 For each run of differences between the input texts, you can choose | |
923 which one of them to keep, or edit them both together. | |
924 | |
925 The merge buffer uses a special major mode, Emerge mode, with commands | |
926 for making these choices. But you can also edit the buffer with | |
927 ordinary Emacs commands. | |
928 | |
929 At any given time, the attention of Emerge is focused on one | |
930 particular difference, called the @dfn{selected} difference. This | |
931 difference is marked off in the three buffers like this: | |
932 | |
933 @example | |
934 vvvvvvvvvvvvvvvvvvvv | |
935 @var{text that differs} | |
936 ^^^^^^^^^^^^^^^^^^^^ | |
937 @end example | |
938 | |
939 @noindent | |
940 Emerge numbers all the differences sequentially and the mode | |
941 line always shows the number of the selected difference. | |
942 | |
943 Normally, the merge buffer starts out with the A version of the text. | |
944 But when the A version of a difference agrees with the common ancestor, | |
945 then the B version is initially preferred for that difference. | |
946 | |
947 Emerge leaves the merged text in the merge buffer when you exit. At | |
948 that point, you can save it in a file with @kbd{C-x C-w}. If you give a | |
949 numeric argument to @code{emerge-files} or | |
950 @code{emerge-files-with-ancestor}, it reads the name of the output file | |
951 using the minibuffer. (This is the last file name those commands read.) | |
952 Then exiting from Emerge saves the merged text in the output file. | |
953 | |
954 Normally, Emerge commands save the output buffer in its file when you | |
955 exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not | |
956 save the output buffer, but you can save it yourself if you wish. | |
957 | |
958 @node Submodes of Emerge | |
959 @subsection Submodes of Emerge | |
960 | |
961 You can choose between two modes for giving merge commands: Fast mode | |
962 and Edit mode. In Fast mode, basic merge commands are single | |
963 characters, but ordinary Emacs commands are disabled. This is | |
964 convenient if you use only merge commands. In Edit mode, all merge | |
965 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs | |
966 commands are also available. This allows editing the merge buffer, but | |
967 slows down Emerge operations. | |
968 | |
969 Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to | |
970 Fast mode. The mode line indicates Edit and Fast modes with @samp{E} | |
971 and @samp{F}. | |
972 | |
973 Emerge has two additional submodes that affect how particular merge | |
974 commands work: Auto Advance mode and Skip Prefers mode. | |
975 | |
976 If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands | |
977 advance to the next difference. This lets you go through the merge | |
978 faster as long as you simply choose one of the alternatives from the | |
979 input. The mode line indicates Auto Advance mode with @samp{A}. | |
980 | |
981 If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands | |
982 skip over differences in states prefer-A and prefer-B (@pxref{State of | |
983 Difference}). Thus you see only differences for which neither version | |
984 is presumed ``correct.'' The mode line indicates Skip Prefers mode with | |
985 @samp{S}. | |
986 | |
987 @findex emerge-auto-advance-mode | |
988 @findex emerge-skip-prefers-mode | |
989 Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or | |
990 clear Auto Advance mode. Use @kbd{s s} | |
991 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. | |
992 These commands turn on the mode with a positive argument, turns it off | |
993 with a negative or zero argument, and toggle the mode with no argument. | |
994 | |
995 @node State of Difference | |
996 @subsection State of a Difference | |
997 | |
998 In the merge buffer, a difference is marked with lines of @samp{v} and | |
999 @samp{^} characters. Each difference has one of these seven states: | |
1000 | |
1001 @table @asis | |
1002 @item A | |
1003 The difference is showing the A version. The @kbd{a} command always | |
1004 produces this state; the mode line indicates it with @samp{A}. | |
1005 | |
1006 @item B | |
1007 The difference is showing the B version. The @kbd{b} command always | |
1008 produces this state; the mode line indicates it with @samp{B}. | |
1009 | |
1010 @item default-A | |
1011 @itemx default-B | |
1012 The difference is showing the A or the B state by default, because you | |
1013 haven't made a choice. All differences start in the default-A state | |
1014 (and thus the merge buffer is a copy of the A buffer), except those for | |
1015 which one alternative is ``preferred'' (see below). | |
1016 | |
1017 When you select a difference, its state changes from default-A or | |
1018 default-B to plain A or B. Thus, the selected difference never has | |
1019 state default-A or default-B, and these states are never displayed in | |
1020 the mode line. | |
1021 | |
1022 The command @kbd{d a} chooses default-A as the default state, and @kbd{d | |
1023 b} chooses default-B. This chosen default applies to all differences | |
1024 which you haven't ever selected and for which no alternative is preferred. | |
1025 If you are moving through the merge sequentially, the differences you | |
1026 haven't selected are those following the selected one. Thus, while | |
1027 moving sequentially, you can effectively make the A version the default | |
1028 for some sections of the merge buffer and the B version the default for | |
1029 others by using @kbd{d a} and @kbd{d b} between sections. | |
1030 | |
1031 @item prefer-A | |
1032 @itemx prefer-B | |
1033 The difference is showing the A or B state because it is | |
1034 @dfn{preferred}. This means that you haven't made an explicit choice, | |
1035 but one alternative seems likely to be right because the other | |
1036 alternative agrees with the common ancestor. Thus, where the A buffer | |
1037 agrees with the common ancestor, the B version is preferred, because | |
1038 chances are it is the one that was actually changed. | |
1039 | |
1040 These two states are displayed in the mode line as @samp{A*} and @samp{B*}. | |
1041 | |
1042 @item combined | |
1043 The difference is showing a combination of the A and B states, as a | |
1044 result of the @kbd{x c} or @kbd{x C} commands. | |
1045 | |
1046 Once a difference is in this state, the @kbd{a} and @kbd{b} commands | |
1047 don't do anything to it unless you give them a numeric argument. | |
1048 | |
1049 The mode line displays this state as @samp{comb}. | |
1050 @end table | |
1051 | |
1052 @node Merge Commands | |
1053 @subsection Merge Commands | |
1054 | |
1055 Here are the Merge commands for Fast mode; in Edit mode, precede them | |
1056 with @kbd{C-c C-c}: | |
1057 | |
1058 @table @kbd | |
1059 @item p | |
1060 Select the previous difference. | |
1061 | |
1062 @item n | |
1063 Select the next difference. | |
1064 | |
1065 @item a | |
1066 Choose the A version of this difference. | |
1067 | |
1068 @item b | |
1069 Choose the B version of this difference. | |
1070 | |
1071 @item C-u @var{n} j | |
1072 Select difference number @var{n}. | |
1073 | |
1074 @item . | |
1075 Select the difference containing point. You can use this command in the | |
1076 merge buffer or in the A or B buffer. | |
1077 | |
1078 @item q | |
1079 Quit---finish the merge. | |
1080 | |
1081 @item C-] | |
1082 Abort---exit merging and do not save the output. | |
1083 | |
1084 @item f | |
1085 Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) | |
1086 | |
1087 @item e | |
1088 Go into Edit mode. | |
1089 | |
1090 @item l | |
1091 Recenter (like @kbd{C-l}) all three windows. | |
1092 | |
1093 @item - | |
1094 Specify part of a prefix numeric argument. | |
1095 | |
1096 @item @var{digit} | |
1097 Also specify part of a prefix numeric argument. | |
1098 | |
1099 @item d a | |
1100 Choose the A version as the default from here down in | |
1101 the merge buffer. | |
1102 | |
1103 @item d b | |
1104 Choose the B version as the default from here down in | |
1105 the merge buffer. | |
1106 | |
1107 @item c a | |
1108 Copy the A version of this difference into the kill ring. | |
1109 | |
1110 @item c b | |
1111 Copy the B version of this difference into the kill ring. | |
1112 | |
1113 @item i a | |
1114 Insert the A version of this difference at point. | |
1115 | |
1116 @item i b | |
1117 Insert the B version of this difference at point. | |
1118 | |
1119 @item m | |
1120 Put point and mark around the difference. | |
1121 | |
1122 @item ^ | |
1123 Scroll all three windows down (like @kbd{M-v}). | |
1124 | |
1125 @item v | |
1126 Scroll all three windows up (like @kbd{C-v}). | |
1127 | |
1128 @item < | |
1129 Scroll all three windows left (like @kbd{C-x <}). | |
1130 | |
1131 @item > | |
1132 Scroll all three windows right (like @kbd{C-x >}). | |
1133 | |
1134 @item | | |
1135 Reset horizontal scroll on all three windows. | |
1136 | |
1137 @item x 1 | |
1138 Shrink the merge window to one line. (Use @kbd{C-u l} to restore it | |
1139 to full size.) | |
1140 | |
1141 @item x c | |
1142 Combine the two versions of this difference (@pxref{Combining in | |
1143 Emerge}). | |
1144 | |
1145 @item x f | |
1146 Show the names of the files/buffers Emerge is operating on, in a Help | |
1147 window. (Use @kbd{C-u l} to restore windows.) | |
1148 | |
1149 @item x j | |
1150 Join this difference with the following one. | |
1151 (@kbd{C-u x j} joins this difference with the previous one.) | |
1152 | |
1153 @item x s | |
1154 Split this difference into two differences. Before you use this | |
1155 command, position point in each of the three buffers at the place where | |
1156 you want to split the difference. | |
1157 | |
1158 @item x t | |
1159 Trim identical lines off the top and bottom of the difference. | |
1160 Such lines occur when the A and B versions are | |
1161 identical but differ from the ancestor version. | |
1162 @end table | |
1163 | |
1164 @node Exiting Emerge | |
1165 @subsection Exiting Emerge | |
1166 | |
1167 The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing | |
1168 the results into the output file if you specified one. It restores the | |
1169 A and B buffers to their proper contents, or kills them if they were | |
1170 created by Emerge and you haven't changed them. It also disables the | |
1171 Emerge commands in the merge buffer, since executing them later could | |
1172 damage the contents of the various buffers. | |
1173 | |
1174 @kbd{C-]} aborts the merge. This means exiting without writing the | |
1175 output file. If you didn't specify an output file, then there is no | |
1176 real difference between aborting and finishing the merge. | |
1177 | |
1178 If the Emerge command was called from another Lisp program, then its | |
1179 return value is @code{t} for successful completion, or @code{nil} if you | |
1180 abort. | |
1181 | |
1182 @node Combining in Emerge | |
1183 @subsection Combining the Two Versions | |
1184 | |
1185 Sometimes you want to keep @emph{both} alternatives for a particular | |
1186 difference. To do this, use @kbd{x c}, which edits the merge buffer | |
1187 like this: | |
1188 | |
1189 @example | |
1190 @group | |
1191 #ifdef NEW | |
1192 @var{version from A buffer} | |
1193 #else /* not NEW */ | |
1194 @var{version from B buffer} | |
1195 #endif /* not NEW */ | |
1196 @end group | |
1197 @end example | |
1198 | |
1199 @noindent | |
1200 @vindex emerge-combine-versions-template | |
1201 While this example shows C preprocessor conditionals delimiting the two | |
1202 alternative versions, you can specify the strings to use by setting | |
1203 the variable @code{emerge-combine-versions-template} to a string of your | |
1204 choice. In the string, @samp{%a} says where to put version A, and | |
1205 @samp{%b} says where to put version B. The default setting, which | |
1206 produces the results shown above, looks like this: | |
1207 | |
1208 @example | |
1209 @group | |
1210 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" | |
1211 @end group | |
1212 @end example | |
1213 | |
1214 @node Fine Points of Emerge | |
1215 @subsection Fine Points of Emerge | |
1216 | |
1217 During the merge, you mustn't try to edit the A and B buffers yourself. | |
1218 Emerge modifies them temporarily, but ultimately puts them back the way | |
1219 they were. | |
1220 | |
1221 You can have any number of merges going at once---just don't use any one | |
1222 buffer as input to more than one merge at once, since the temporary | |
1223 changes made in these buffers would get in each other's way. | |
1224 | |
1225 Starting Emerge can take a long time because it needs to compare the | |
1226 files fully. Emacs can't do anything else until @code{diff} finishes. | |
1227 Perhaps in the future someone will change Emerge to do the comparison in | |
1228 the background when the input files are large---then you could keep on | |
1229 doing other things with Emacs until Emerge is ready to accept | |
1230 commands. | |
1231 | |
1232 @vindex emerge-startup-hook | |
1233 After setting up the merge, Emerge runs the hook | |
1234 @code{emerge-startup-hook} (@pxref{Hooks}). | |
1235 | |
1236 @ignore | 848 @ignore |
1237 arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb | 849 arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb |
1238 @end ignore | 850 @end ignore |