diff-mode documentation

diff-mode documentation

[Aaron S. Hawley]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 3030 bytes --]

The commands and features of Diff mode aren't entirely documumented in the
Emacs manual.  The following is a patch to files.texi that would add some.
There may exist a more appropriate location in the manual (or Emacs) for
this all to go. Stefan Monnier, the author of Diff mode, has provided
helpful feedback to me on this patch.  However, any mistakes are my own.

I've tried adopting the style for command tables found elsewhere in the
manual.  The patch also adds discussion of Diff mode's brilliant feature
to interactively correct the patch after any manual edits by the user.

Hope this helps,
/a

----

  Differences between versions of files are often distributed as
patches, which are the output from the @command{diff} program.  You
can use the same Diff mode to operate on a patch by typing @kbd{M-x
diff-mode}.  Any manual edits you make to a patch with Diff mode will
automatically correct the hunk header including insert, delete and
file line numbers.  Also, the following commands help to navigate,
manipulate and apply patches in Diff mode:

@table @kbd
@item M-n
@findex diff-hunk-next
Move to the next hunk in the patch.

@item M-p
@findex diff-hunk-prev
Move to the previous hunk in the patch.

@item M-@}
@findex diff-file-next
Move to the next file hunk in a multiple file patch.

@item M-@{
@findex diff-file-prev
Move to the previous file hunk in a multiple file patch.

@item M-k
@findex diff-hunk-kill
Kill the current hunk at point.

@item M-K
@findex diff-file-kill
In a patch with multiple files, kill the current patch to a file.

@item C-c C-s
@findex diff-split-hunk
Split the hunk at point. This is useful when manually editing a patch
and only works with the unified diff format.

@item C-c C-r
@findex diff-refine-hunk
Recomputes the current hunk by ignoring changes in whitespace.

@item M-R
@findex diff-reverse-direction
Convert the patch to a patch that reverts.
@xref{Reversed Patches, Applying Reversed Patches, Patch, diff,
Comparing and Merging Files}.

@item M-U
@findex diff-context->unified
Convert the patch to the unified diff format.
@xref{Unified Format, Unified Format, Diff, diff,
Comparing and Merging Files}.

@item M-C
@findex diff-unified->context
Convert the patch back to context diff format.
@xref{Context Format, Context Format, Diff, diff,
Comparing and Merging Files}.

@item M-r
@findex diff-restrict-view
@findex widen
Restrict the view to the current hunk. @xref{Narrowing}.  With a
prefix argument of @kbd{C-u} restrict the view to the current patch of
a multiple file patch.  The view can be widened again with @kbd{M-W}.

@item C-c C-a
@findex diff-apply-hunk
Apply hunk to target file.  With a prefix argument of @kbd{C-u}, apply
the reverse of the hunk.

@item M-A
@findex diff-ediff-patch
Start an Ediff session with the patch.
@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.

@item C-x 4 a
Add a new entry to the change log for the current file.  @xref{Change
Log}.  This is useful for log entries for functions that are deleted
by the patch.

@end table

[-- Attachment #2: Patch to files.texi --]
[-- Type: TEXT/PLAIN, Size: 2890 bytes --]

--- files.texi	06 Mar 2006 22:56:44 -0500	1.133
+++ files.texi	07 Mar 2006 18:27:41 -0500	
@@ -2999,7 +2999,87 @@
 @cindex patches
   Differences between versions of files are often distributed as
 patches, which are the output from the @command{diff} program.  You
-can use Diff mode to operate on a patch by typing @kbd{M-x diff-mode}.
+can use the same Diff mode to operate on a patch by typing @kbd{M-x
+diff-mode}.  Any manual edits you make to a patch with Diff mode will
+automatically correct the hunk header including insert, delete and
+file line numbers.  Also, the following commands help to navigate,
+manipulate and apply patches in Diff mode:
+
+@table @kbd
+@item M-n
+@findex diff-hunk-next
+Move to the next hunk in the patch.
+
+@item M-p
+@findex diff-hunk-prev
+Move to the previous hunk in the patch.
+
+@item M-@}
+@findex diff-file-next
+Move to the next file hunk in a multiple file patch.
+
+@item M-@{
+@findex diff-file-prev
+Move to the previous file hunk in a multiple file patch.
+
+@item M-k
+@findex diff-hunk-kill
+Kill the current hunk at point.
+
+@item M-K
+@findex diff-file-kill
+In a patch with multiple files, kill the current patch to a file.
+
+@item C-c C-s
+@findex diff-split-hunk
+Split the hunk at point. This is useful when manually editing a patch
+and only works with the unified diff format.
+
+@item C-c C-r
+@findex diff-refine-hunk
+Recomputes the current hunk by ignoring changes in whitespace.
+
+@item M-R
+@findex diff-reverse-direction
+Convert the patch to a patch that reverts.
+@xref{Reversed Patches, Applying Reversed Patches, Patch, diff,
+Comparing and Merging Files}.
+
+@item M-U
+@findex diff-context->unified
+Convert the patch to the unified diff format.
+@xref{Unified Format, Unified Format, Diff, diff,
+Comparing and Merging Files}.
+
+@item M-C
+@findex diff-unified->context
+Convert the patch back to context diff format.
+@xref{Context Format, Context Format, Diff, diff,
+Comparing and Merging Files}.
+
+@item M-r
+@findex diff-restrict-view
+@findex widen
+Restrict the view to the current hunk. @xref{Narrowing}.  With a
+prefix argument of @kbd{C-u} restrict the view to the current patch of
+a multiple file patch.  The view can be widened again with @kbd{M-W}.
+
+@item C-c C-a
+@findex diff-apply-hunk
+Apply hunk to target file.  With a prefix argument of @kbd{C-u}, apply
+the reverse of the hunk.
+
+@item M-A
+@findex diff-ediff-patch
+Start an Ediff session with the patch.
+@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
+
+@item C-x 4 a
+Add a new entry to the change log for the current file.  @xref{Change
+Log}.  This is useful for log entries for functions that are deleted
+by the patch.
+
+@end table
 
 @findex compare-windows
   The command @kbd{M-x compare-windows} compares the text in the

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: diff-mode documentation

[Richard Stallman]

    @item M-@}
    @findex diff-file-next
    Move to the next file hunk in a multiple file patch.

I think I can guess what a "file hunk" is.  Is it the part of the
patch that is the diff for one file?

    @findex diff-file-kill
    In a patch with multiple files, kill the current patch to a file.

What does the "current patch to a file"?  Is it different from the
current file hunk?


    @item M-R
    @findex diff-reverse-direction
    Convert the patch to a patch that reverts.
    @xref{Reversed Patches, Applying Reversed Patches, Patch, diff,
    Comparing and Merging Files}.

    @item M-U
    @findex diff-context->unified
    Convert the patch to the unified diff format.
    @xref{Unified Format, Unified Format, Diff, diff,
    Comparing and Merging Files}.

    @item M-C
    @findex diff-unified->context
    Convert the patch back to context diff format.
    @xref{Context Format, Context Format, Diff, diff,
    Comparing and Merging Files}.

I would rather these be C-c commands.  They are not the sort of commands
one would repeat over and over in a short period, so there's no harm
in using C-c, and that would make it possible for the M- commands
to be case-independent.

    @item M-A
    @findex diff-ediff-patch
    Start an Ediff session with the patch.
    @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.

Same story there.

    @item M-K
    @findex diff-file-kill
    In a patch with multiple files, kill the current patch to a file.

This would have to be moved.

Re: diff-mode documentation

[Aaron S. Hawley]

On Thu, 9 Mar 2006, Richard Stallman wrote:

>     @item M-@}
>     @findex diff-file-next
>     Move to the next file hunk in a multiple file patch.
>
> I think I can guess what a "file hunk" is.  Is it the part of the
> patch that is the diff for one file?

I'm glad you brought this up.  I'm not experienced with the common
terminology of patches, so I sort of "winged it".  A "file hunk" is indeed
the "diff" of a file.

>     @findex diff-file-kill
>     In a patch with multiple files, kill the current patch to a file.
>
> What does the "current patch to a file"?  Is it different from the
> current file hunk?

No, it's the same.

> I would rather these be C-c commands.
> [...]
>
>     @item M-A
>     @findex diff-ediff-patch
>     Start an Ediff session with the patch.
>     @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
>
> Same story there.
>
>     @item M-K
>     @findex diff-file-kill
>     In a patch with multiple files, kill the current patch to a file.
>
> This would have to be moved.

I'll let Stefan take this up.

Re: diff-mode documentation

[Richard Stallman]

    >     @findex diff-file-kill
    >     In a patch with multiple files, kill the current patch to a file.
    >
    > What does the "current patch to a file"?  Is it different from the
    > current file hunk?

    No, it's the same.

It is confusng to use two different names for the same thing,
especially if you don't say they mean the same thing.
Better to pick just one of them and use it consistently.

Re: diff-mode documentation

[Aaron S. Hawley]

On Thu, 9 Mar 2006, Richard Stallman wrote:

>     @item M-R
>     @findex diff-reverse-direction
>     Convert the patch to a patch that reverts.
>     @xref{Reversed Patches, Applying Reversed Patches, Patch, diff,
>     Comparing and Merging Files}.
>
>     @item M-U
>     @findex diff-context->unified
>     Convert the patch to the unified diff format.
>     @xref{Unified Format, Unified Format, Diff, diff,
>     Comparing and Merging Files}.
>
>     @item M-C
>     @findex diff-unified->context
>     Convert the patch back to context diff format.
>     @xref{Context Format, Context Format, Diff, diff,
>     Comparing and Merging Files}.
>
> I would rather these be C-c commands.  They are not the sort of commands
> one would repeat over and over in a short period, so there's no harm
> in using C-c, and that would make it possible for the M- commands
> to be case-independent.
>
>     @item M-A
>     @findex diff-ediff-patch
>     Start an Ediff session with the patch.
>     @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
>
> Same story there.
>
>     @item M-K
>     @findex diff-file-kill
>     In a patch with multiple files, kill the current patch to a file.
>
> This would have to be moved.

I haven't heard anything from Stefan on this, but to get the "ball
rolling" I suppose we're talking about a patch like the one below.  I'm
not familiar with the keybinding standards of Emacs, but its some ideas I
had to fulfill the C-c requirement and maintain some semblance of command
mnemonics the M- commands had.  I also imagined the old bindings needed to
be preserved and didn't delete them.

--- diff-mode.el        19 Feb 2006 14:01:04 -0500      1.84
+++ diff-mode.el        10 Mar 2006 12:33:38 -0500
@@ -142,8 +142,13 @@
   `(("\e" . ,diff-mode-shared-map)
     ;; From compilation-minor-mode.
     ("\C-c\C-c" . diff-goto-source)
+    ("\C-ca" . diff-ediff-patch)
+    ("\C-cr" . diff-reverse-direction)
+    ("\C-cu" . diff-context->unified)
+    ("\C-cc" . diff-unified->context)
+    ("\C-c\C-k" . diff-file-kill)
     ;; Misc operations.
     ("\C-c\C-r" . diff-refine-hunk)
     ("\C-c\C-s" . diff-split-hunk)
     ("\C-c\C-a" . diff-apply-hunk)
     ("\C-c\C-t" . diff-test-hunk)

Re: diff-mode documentation

[Stefan Monnier]

> On Thu, 9 Mar 2006, Richard Stallman wrote:
>> @item M-R
>> @findex diff-reverse-direction
>> Convert the patch to a patch that reverts.
>> @xref{Reversed Patches, Applying Reversed Patches, Patch, diff,
>> Comparing and Merging Files}.
>> 
>> @item M-U
>> @findex diff-context->unified
>> Convert the patch to the unified diff format.
>> @xref{Unified Format, Unified Format, Diff, diff,
>> Comparing and Merging Files}.
>> 
>> @item M-C
>> @findex diff-unified->context
>> Convert the patch back to context diff format.
>> @xref{Context Format, Context Format, Diff, diff,
>> Comparing and Merging Files}.
>> 
>> I would rather these be C-c commands.  They are not the sort of commands
>> one would repeat over and over in a short period, so there's no harm
>> in using C-c, and that would make it possible for the M- commands
>> to be case-independent.

Good point.  These bindings date back to the beginning of diff-mode when
I wasn't following coding conventions as much and when all the other
bindings were under M-<something> so it seemed like a natural choice at
that point.

> I haven't heard anything from Stefan on this, but to get the "ball
> rolling" I suppose we're talking about a patch like the one below.  I'm

Sorry, I missed a couple days of this mailing list cause fsf's mailohost got
put on some random blacklist again.  At least this time I finally managed to
convince my sysadmin that add a whitelist that overrules the blacklist, so
hopefully the problem won't re-appear in the near future.

> --- diff-mode.el        19 Feb 2006 14:01:04 -0500      1.84
> +++ diff-mode.el        10 Mar 2006 12:33:38 -0500
> @@ -142,8 +142,13 @@
>    `(("\e" . ,diff-mode-shared-map)
>      ;; From compilation-minor-mode.
>      ("\C-c\C-c" . diff-goto-source)
> +    ("\C-ca" . diff-ediff-patch)
> +    ("\C-cr" . diff-reverse-direction)
> +    ("\C-cu" . diff-context->unified)
> +    ("\C-cc" . diff-unified->context)
> +    ("\C-c\C-k" . diff-file-kill)

Bindings of the form C-c <letter> are reserved for the user, so they're out.
Better use C-c C-<something>.


        Stefan

Re: diff-mode documentation

[Richard Stallman]

    +    ("\C-ca" . diff-ediff-patch)
    +    ("\C-cr" . diff-reverse-direction)
    +    ("\C-cu" . diff-context->unified)
    +    ("\C-cc" . diff-unified->context)

Those key sequences are reserved for users (see the Tips appendix
in the Lisp Manual).  You need to use key sequences in the space
reserved for major modes (since Diff mode is a major mode).

    +    ("\C-c\C-k" . diff-file-kill)

That is ok.