[Emacs-diffs] Changes to emerge-xtra.texi

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       07/09/06 04:45:36

Index: emerge-xtra.texi
===================================================================
RCS file: emerge-xtra.texi
diff -N emerge-xtra.texi
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ emerge-xtra.texi    6 Sep 2007 04:45:36 -0000       1.1
@@ -0,0 +1,414 @@
address@hidden This is part of the Emacs manual.
address@hidden Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, 
Inc.
address@hidden See file emacs.texi for copying conditions.
address@hidden
address@hidden This file is included either in emacs-xtra.texi (when producing 
the
address@hidden printed version) or in the main Emacs manual (for the on-line 
version).
address@hidden Emerge
address@hidden Merging Files with Emerge
address@hidden Emerge
address@hidden merging files
+
+  It's not unusual for programmers to get their signals crossed and
+modify the same program in two different directions.  To recover from
+this confusion, you need to merge the two versions.  Emerge makes this
+easier.  For other ways to compare files, see
address@hidden
address@hidden Files,,, emacs, the Emacs Manual},
address@hidden iftex
address@hidden
address@hidden Files},
address@hidden ifnottex
+and @ref{Top, Ediff,, ediff, The Ediff Manual}.
+
address@hidden
+* Overview of Emerge:: How to start Emerge.  Basic concepts.
+* Submodes of Emerge:: Fast mode vs. Edit mode.
+                         Skip Prefers mode and Auto Advance mode.
+* State of Difference::        You do the merge by specifying state A or B
+                         for each difference.
+* Merge Commands::     Commands for selecting a difference,
+                         changing states of differences, etc.
+* Exiting Emerge::     What to do when you've finished the merge.
+* Combining in Emerge::            How to keep both alternatives for a 
difference.
+* Fine Points of Emerge::   Misc.
address@hidden menu
+
address@hidden Overview of Emerge
address@hidden Overview of Emerge
+
+  To start Emerge, run one of these four commands:
+
address@hidden @kbd
address@hidden M-x emerge-files
address@hidden emerge-files
+Merge two specified files.
+
address@hidden M-x emerge-files-with-ancestor
address@hidden emerge-files-with-ancestor
+Merge two specified files, with reference to a common ancestor.
+
address@hidden M-x emerge-buffers
address@hidden emerge-buffers
+Merge two buffers.
+
address@hidden M-x emerge-buffers-with-ancestor
address@hidden emerge-buffers-with-ancestor
+Merge two buffers with reference to a common ancestor in a third
+buffer.
address@hidden table
+
address@hidden merge buffer (Emerge)
address@hidden A and B buffers (Emerge)
+  The Emerge commands compare two files or buffers, and display the
+comparison in three buffers: one for each input text (the @dfn{A buffer}
+and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
+takes place.  The merge buffer shows the full merged text, not just the
+differences.  Wherever the two input texts differ, you can choose which
+one of them to include in the merge buffer.
+
+  The Emerge commands that take input from existing buffers use only
+the accessible portions of those buffers, if they are narrowed.
address@hidden
address@hidden,,, emacs, the Emacs Manual}.
address@hidden iftex
address@hidden
address@hidden
address@hidden ifnottex
+
+
+  If a common ancestor version is available, from which the two texts to
+be merged were both derived, Emerge can use it to guess which
+alternative is right.  Wherever one current version agrees with the
+ancestor, Emerge presumes that the other current version is a deliberate
+change which should be kept in the merged version.  Use the
address@hidden commands if you want to specify a common ancestor
+text.  These commands read three file or buffer names---variant A,
+variant B, and the common ancestor.
+
+  After the comparison is done and the buffers are prepared, the
+interactive merging starts.  You control the merging by typing special
address@hidden commands} in the merge buffer (@pxref{Merge Commands}).
+For each run of differences between the input texts, you can choose
+which one of them to keep, or edit them both together.
+
+  The merge buffer uses a special major mode, Emerge mode, with commands
+for making these choices.  But you can also edit the buffer with
+ordinary Emacs commands.
+
+  At any given time, the attention of Emerge is focused on one
+particular difference, called the @dfn{selected} difference.  This
+difference is marked off in the three buffers like this:
+
address@hidden
+vvvvvvvvvvvvvvvvvvvv
address@hidden that differs}
+^^^^^^^^^^^^^^^^^^^^
address@hidden example
+
address@hidden
+Emerge numbers all the differences sequentially and the mode
+line always shows the number of the selected difference.
+
+  Normally, the merge buffer starts out with the A version of the text.
+But when the A version of a difference agrees with the common ancestor,
+then the B version is initially preferred for that difference.
+
+  Emerge leaves the merged text in the merge buffer when you exit.  At
+that point, you can save it in a file with @kbd{C-x C-w}.  If you give a
+numeric argument to @code{emerge-files} or
address@hidden, it reads the name of the output file
+using the minibuffer.  (This is the last file name those commands read.)
+Then exiting from Emerge saves the merged text in the output file.
+
+  Normally, Emerge commands save the output buffer in its file when you
+exit.  If you abort Emerge with @kbd{C-]}, the Emerge command does not
+save the output buffer, but you can save it yourself if you wish.
+
address@hidden Submodes of Emerge
address@hidden Submodes of Emerge
+
+  You can choose between two modes for giving merge commands: Fast mode
+and Edit mode.  In Fast mode, basic merge commands are single
+characters, but ordinary Emacs commands are disabled.  This is
+convenient if you use only merge commands.  In Edit mode, all merge
+commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
+commands are also available.  This allows editing the merge buffer, but
+slows down Emerge operations.
+
+  Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
+Fast mode.  The mode line indicates Edit and Fast modes with @samp{E}
+and @samp{F}.
+
+  Emerge has two additional submodes that affect how particular merge
+commands work: Auto Advance mode and Skip Prefers mode.
+
+  If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
+advance to the next difference.  This lets you go through the merge
+faster as long as you simply choose one of the alternatives from the
+input.  The mode line indicates Auto Advance mode with @samp{A}.
+
+  If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
+skip over differences in states prefer-A and prefer-B (@pxref{State of
+Difference}).  Thus you see only differences for which neither version
+is presumed ``correct.''  The mode line indicates Skip Prefers mode with
address@hidden
+
address@hidden emerge-auto-advance-mode
address@hidden emerge-skip-prefers-mode
+  Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
+clear Auto Advance mode.  Use @kbd{s s}
+(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
+These commands turn on the mode with a positive argument, turns it off
+with a negative or zero argument, and toggle the mode with no argument.
+
address@hidden State of Difference
address@hidden State of a Difference
+
+  In the merge buffer, a difference is marked with lines of @samp{v} and
address@hidden characters.  Each difference has one of these seven states:
+
address@hidden @asis
address@hidden A
+The difference is showing the A version.  The @kbd{a} command always
+produces this state; the mode line indicates it with @samp{A}.
+
address@hidden B
+The difference is showing the B version.  The @kbd{b} command always
+produces this state; the mode line indicates it with @samp{B}.
+
address@hidden default-A
address@hidden default-B
+The difference is showing the A or the B state by default, because you
+haven't made a choice.  All differences start in the default-A state
+(and thus the merge buffer is a copy of the A buffer), except those for
+which one alternative is ``preferred'' (see below).
+
+When you select a difference, its state changes from default-A or
+default-B to plain A or B.  Thus, the selected difference never has
+state default-A or default-B, and these states are never displayed in
+the mode line.
+
+The command @kbd{d a} chooses default-A as the default state, and @kbd{d
+b} chooses default-B.  This chosen default applies to all differences
+which you haven't ever selected and for which no alternative is preferred.
+If you are moving through the merge sequentially, the differences you
+haven't selected are those following the selected one.  Thus, while
+moving sequentially, you can effectively make the A version the default
+for some sections of the merge buffer and the B version the default for
+others by using @kbd{d a} and @kbd{d b} between sections.
+
address@hidden prefer-A
address@hidden prefer-B
+The difference is showing the A or B state because it is
address@hidden  This means that you haven't made an explicit choice,
+but one alternative seems likely to be right because the other
+alternative agrees with the common ancestor.  Thus, where the A buffer
+agrees with the common ancestor, the B version is preferred, because
+chances are it is the one that was actually changed.
+
+These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
+
address@hidden combined
+The difference is showing a combination of the A and B states, as a
+result of the @kbd{x c} or @kbd{x C} commands.
+
+Once a difference is in this state, the @kbd{a} and @kbd{b} commands
+don't do anything to it unless you give them a numeric argument.
+
+The mode line displays this state as @samp{comb}.
address@hidden table
+
address@hidden Merge Commands
address@hidden Merge Commands
+
+  Here are the Merge commands for Fast mode; in Edit mode, precede them
+with @kbd{C-c C-c}:
+
address@hidden @kbd
address@hidden p
+Select the previous difference.
+
address@hidden n
+Select the next difference.
+
address@hidden a
+Choose the A version of this difference.
+
address@hidden b
+Choose the B version of this difference.
+
address@hidden C-u @var{n} j
+Select difference number @var{n}.
+
address@hidden .
+Select the difference containing point.  You can use this command in the
+merge buffer or in the A or B buffer.
+
address@hidden q
+Quit---finish the merge.
+
address@hidden C-]
+Abort---exit merging and do not save the output.
+
address@hidden f
+Go into Fast mode.  (In Edit mode, this is actually @kbd{C-c C-c f}.)
+
address@hidden e
+Go into Edit mode.
+
address@hidden l
+Recenter (like @kbd{C-l}) all three windows.
+
address@hidden -
+Specify part of a prefix numeric argument.
+
address@hidden @var{digit}
+Also specify part of a prefix numeric argument.
+
address@hidden d a
+Choose the A version as the default from here down in
+the merge buffer.
+
address@hidden d b
+Choose the B version as the default from here down in
+the merge buffer.
+
address@hidden c a
+Copy the A version of this difference into the kill ring.
+
address@hidden c b
+Copy the B version of this difference into the kill ring.
+
address@hidden i a
+Insert the A version of this difference at point.
+
address@hidden i b
+Insert the B version of this difference at point.
+
address@hidden m
+Put point and mark around the difference.
+
address@hidden ^
+Scroll all three windows down (like @kbd{M-v}).
+
address@hidden v
+Scroll all three windows up (like @kbd{C-v}).
+
address@hidden <
+Scroll all three windows left (like @kbd{C-x <}).
+
address@hidden >
+Scroll all three windows right (like @kbd{C-x >}).
+
address@hidden |
+Reset horizontal scroll on all three windows.
+
address@hidden x 1
+Shrink the merge window to one line.  (Use @kbd{C-u l} to restore it
+to full size.)
+
address@hidden x c
+Combine the two versions of this difference (@pxref{Combining in
+Emerge}).
+
address@hidden x f
+Show the names of the files/buffers Emerge is operating on, in a Help
+window.  (Use @kbd{C-u l} to restore windows.)
+
address@hidden x j
+Join this difference with the following one.
+(@kbd{C-u x j} joins this difference with the previous one.)
+
address@hidden x s
+Split this difference into two differences.  Before you use this
+command, position point in each of the three buffers at the place where
+you want to split the difference.
+
address@hidden x t
+Trim identical lines off the top and bottom of the difference.
+Such lines occur when the A and B versions are
+identical but differ from the ancestor version.
address@hidden table
+
address@hidden Exiting Emerge
address@hidden Exiting Emerge
+
+  The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
+the results into the output file if you specified one.  It restores the
+A and B buffers to their proper contents, or kills them if they were
+created by Emerge and you haven't changed them.  It also disables the
+Emerge commands in the merge buffer, since executing them later could
+damage the contents of the various buffers.
+
+  @kbd{C-]} aborts the merge.  This means exiting without writing the
+output file.  If you didn't specify an output file, then there is no
+real difference between aborting and finishing the merge.
+
+  If the Emerge command was called from another Lisp program, then its
+return value is @code{t} for successful completion, or @code{nil} if you
+abort.
+
address@hidden Combining in Emerge
address@hidden Combining the Two Versions
+
+  Sometimes you want to keep @emph{both} alternatives for a particular
+difference.  To do this, use @kbd{x c}, which edits the merge buffer
+like this:
+
address@hidden
address@hidden
+#ifdef NEW
address@hidden from A buffer}
+#else /* not NEW */
address@hidden from B buffer}
+#endif /* not NEW */
address@hidden group
address@hidden example
+
address@hidden
address@hidden emerge-combine-versions-template
+While this example shows C preprocessor conditionals delimiting the two
+alternative versions, you can specify the strings to use by setting
+the variable @code{emerge-combine-versions-template} to a string of your
+choice.  In the string, @samp{%a} says where to put version A, and
address@hidden says where to put version B.  The default setting, which
+produces the results shown above, looks like this:
+
address@hidden
address@hidden
+"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
address@hidden group
address@hidden example
+
address@hidden Fine Points of Emerge
address@hidden Fine Points of Emerge
+
+  During the merge, you mustn't try to edit the A and B buffers yourself.
+Emerge modifies them temporarily, but ultimately puts them back the way
+they were.
+
+  You can have any number of merges going at once---just don't use any one
+buffer as input to more than one merge at once, since the temporary
+changes made in these buffers would get in each other's way.
+
+  Starting Emerge can take a long time because it needs to compare the
+files fully.  Emacs can't do anything else until @code{diff} finishes.
+Perhaps in the future someone will change Emerge to do the comparison in
+the background when the input files are large---then you could keep on
+doing other things with Emacs until Emerge is ready to accept
+commands.
+
address@hidden emerge-startup-hook
+  After setting up the merge, Emerge runs the hook
address@hidden
address@hidden
address@hidden,,, emacs, the Emacs Manual}.
address@hidden iftex
address@hidden
address@hidden
address@hidden ifnottex
+
address@hidden
+   arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e
address@hidden ignore