pull: Make '--dry-run' behave as expected.

* guix/scripts/pull.scm (show-help): Document '--dry-run'.
(build-and-install): Add #:dry-run? parameter and honor it.
(guix-pull): Remove (assoc-ref opts 'dry-run?) condition.  Instead, pass
it as #:dry-run? to 'build-and-install'.
* doc/guix.texi (Invoking guix pull): Document '--dry-run'.  Move
'--verbose' to the bottom.

doc/guix.texi

@@ -2844,9 +2844,6 @@ The @command{guix pull} command is usually invoked with no arguments,
 but it supports the following options:
 
 @table @code
-@item --verbose
-Produce verbose output, writing build logs to the standard error output.
-
 @item --url=@var{url}
 @itemx --commit=@var{commit}
 @itemx --branch=@var{branch}
@@ -2880,6 +2877,14 @@ current generation only.
 @itemx -p @var{profile}
 Use @var{profile} instead of @file{~/.config/guix/current}.
 
+@item --dry-run
+@itemx -n
+Show which channel commit(s) would be used and what would be built or
+substituted but do not actually do it.
+
+@item --verbose
+Produce verbose output, writing build logs to the standard error output.
+
 @item --bootstrap
 Use the bootstrap Guile to build the latest Guix.  This option is only
 useful to Guix developers.

guix/scripts/pull.scm

@@ -86,6 +86,8 @@ Download and deploy the latest version of Guix.\n"))
                          list generations matching PATTERN"))
   (display (G_ "
   -p, --profile=PROFILE  use PROFILE instead of ~/.config/guix/current"))
+  (display (G_ "
+  -n, --dry-run          show what would be pulled and built"))
   (display (G_ "
       --bootstrap        use the bootstrap Guile to build the new Guix"))
   (newline)
@@ -164,15 +166,18 @@ Download and deploy the latest version of Guix.\n"))
     (_ #t)))
 
 (define* (build-and-install instances profile
-                            #:key verbose?)
+                            #:key verbose? dry-run?)
-  "Build the tool from SOURCE, and install it in PROFILE."
+  "Build the tool from SOURCE, and install it in PROFILE.  When DRY-RUN? is
+true, display what would be built without actually building it."
   (define update-profile
     (store-lift build-and-use-profile))
 
   (mlet %store-monad ((manifest (channel-instances->manifest instances)))
     (mbegin %store-monad
-      (update-profile profile manifest)
+      (update-profile profile manifest
-      (return (display-profile-news profile)))))
+                      #:dry-run? dry-run?)
+      (munless dry-run?
+        (display-profile-news profile)))))
 
 (define (honor-lets-encrypt-certificates! store)
   "Tell Guile-Git to use the Let's Encrypt certificates."
@@ -497,8 +502,6 @@ Use '~/.config/guix/channels.scm' instead."))
        (ensure-default-profile)
        (cond ((assoc-ref opts 'query)
               (process-query opts profile))
-             ((assoc-ref opts 'dry-run?)
-              #t)                                 ;XXX: not very useful
              (else
               (with-store store
                 (with-status-report print-build-event
@@ -531,6 +534,8 @@ Use '~/.config/guix/channels.scm' instead."))
                                            (canonical-package guile-2.2)))))
                         (run-with-store store
                           (build-and-install instances profile
+                                             #:dry-run?
+                                             (assoc-ref opts 'dry-run?)
                                              #:verbose?
                                              (assoc-ref opts 'verbose?))))))))))))))