# HG changeset patch
# User Martin von Zweigbergk <martinvonz@google.com>
# Date 2020-12-10 20:00:45
# Node ID ed5a0b5d21a6bcaeb1329fa373923a6d9155c70a
# Parent  6f8a94bbfba121452a8cfddfc83d60d14d92e2d0

diff: describe behavior by using --from/--to instead of varying revision count

I very recently updated the documentation to prefer `--from`/`--to`
over `-r`, but I missed the plain-text description of how the command
behaves when given different numbers of revisions (I guess I just
scanned the text for "-r"). This patch fixes that.

Differential Revision: https://phab.mercurial-scm.org/D9562

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -2483,14 +2483,17 @@ def diff(ui, repo, *pats, **opts):
        default to comparing against the working directory's first
        parent changeset if no revisions are specified.
 
-    When two revision arguments are given, then changes are shown
-    between those revisions. If only one revision is specified then
-    that revision is compared to the working directory, and, when no
-    revisions are specified, the working directory files are compared
-    to its first parent.
-
-    Alternatively you can specify -c/--change with a revision to see
-    the changes in that changeset relative to its first parent.
+    By default, the working directory files are compared to its first parent. To
+    see the differences from another revision, use --from. To see the difference
+    to another revision, use --to. For example, :hg:`diff --from .^` will show
+    the differences from the working copy's grandparent to the working copy,
+    :hg:`diff --to .` will show the diff from the working copy to its parent
+    (i.e. the reverse of the default), and :hg:`diff --from 1.0 --to 1.2` will
+    show the diff between those two revisions.
+
+    Alternatively you can specify -c/--change with a revision to see the changes
+    in that changeset relative to its first parent (i.e. :hg:`diff -c 42` is
+    equivalent to :hg:`diff --from 42^ --to 42`)
 
     Without the -a/--text option, diff will avoid generating diffs of
     files it detects as binary. With -a, diff will generate a diff
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -642,13 +642,17 @@ Test command without options
          default to comparing against the working directory's first parent
          changeset if no revisions are specified.
   
-      When two revision arguments are given, then changes are shown between
-      those revisions. If only one revision is specified then that revision is
-      compared to the working directory, and, when no revisions are specified,
-      the working directory files are compared to its first parent.
+      By default, the working directory files are compared to its first parent.
+      To see the differences from another revision, use --from. To see the
+      difference to another revision, use --to. For example, 'hg diff --from .^'
+      will show the differences from the working copy's grandparent to the
+      working copy, 'hg diff --to .' will show the diff from the working copy to
+      its parent (i.e. the reverse of the default), and 'hg diff --from 1.0 --to
+      1.2' will show the diff between those two revisions.
   
       Alternatively you can specify -c/--change with a revision to see the
-      changes in that changeset relative to its first parent.
+      changes in that changeset relative to its first parent (i.e. 'hg diff -c
+      42' is equivalent to 'hg diff --from 42^ --to 42')
   
       Without the -a/--text option, diff will avoid generating diffs of files it
       detects as binary. With -a, diff will generate a diff anyway, probably