[Request] [+- ] D9562: diff: describe behavior by using --from/--to instead of varying revision count

[martinvonz (Martin von Zweigbergk)]

martinvonz created this revision.
Herald added a reviewer: hg-reviewers.
Herald added a subscriber: mercurial-patches.

REVISION SUMMARY
  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.

REPOSITORY
  rHG Mercurial

BRANCH
  default

REVISION DETAIL
  https://phab.mercurial-scm.org/D9562

AFFECTED FILES
  mercurial/commands.py
  tests/test-help.t

CHANGE DETAILS

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 @@
          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
diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -2483,14 +2483,17 @@
        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



To: martinvonz, #hg-reviewers
Cc: mercurial-patches, mercurial-devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mercurial-scm.org/pipermail/mercurial-patches/attachments/20201210/1e7e7d04/attachment.html>