guix archive: Add -r/--recursive.

* guix/scripts/archive.scm (show-help, %options): Add -r/--recursive.
  (export-from-store): Pass #:recursive? to 'export-paths'.
* doc/guix.texi (Invoking guix archive): Add -r in Emacs example.  Add
  example with ~/.guix-profile.  Document -r/--recursive.

2 files changed, 32 insertions, 6 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index ab97c781ef..50388c5809 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1386,14 +1386,24 @@ to another machine's store.  For example, to transfer the @code{emacs}
 package to a machine connected over SSH, one would run:
 
 @example
-guix archive --export emacs | ssh the-machine guix archive --import
+guix archive --export -r emacs | ssh the-machine guix archive --import
 @end example
 
 @noindent
-However, note that, in this example, all of @code{emacs} and its
-dependencies are transferred, regardless of what is already available in
-the target machine's store.  The @code{--missing} option can help figure
-out which items are missing from the target's store.
+Similarly, a complete user profile may be transferred from one machine
+to another like this:
+
+@example
+guix archive --export -r $(readlink -f ~/.guix-profile) | \
+  ssh the-machine guix-archive --import
+@end example
+
+@noindent
+However, note that, in both examples, all of @code{emacs} and the
+profile as well as all of their dependencies are transferred (due to
+@code{-r}), regardless of what is already available in the target
+machine's store.  The @code{--missing} option can help figure out which
+items are missing from the target's store.
 
 Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
 comparable in spirit to `tar', but with a few noteworthy differences
@@ -1418,6 +1428,16 @@ The main options are:
 Export the specified store files or packages (see below.)  Write the
 resulting archive to the standard output.
 
+Dependencies are @emph{not} included in the output, unless
+@code{--recursive} is passed.
+
+@item -r
+@itemx --recursive
+When combined with @code{--export}, this instructs @command{guix
+archive} to include dependencies of the given items in the archive.
+Thus, the resulting archive is self-contained: it contains the closure
+of the exported store items.
+
 @item --import
 Read an archive from the standard input, and import the files listed
 therein into the store.  Abort if the archive has an invalid digital
diff --git a/guix/scripts/archive.scm b/guix/scripts/archive.scm
index 65bf5423dc..b85119a0ff 100644
--- a/guix/scripts/archive.scm
+++ b/guix/scripts/archive.scm
@@ -57,6 +57,8 @@ Export/import one or more packages from/to the store.\n"))
   (display (_ "
       --export           export the specified files/packages to stdout"))
   (display (_ "
+  -r, --recursive        combined with '--export', include dependencies"))
+  (display (_ "
       --import           import from the archive passed on stdin"))
   (display (_ "
       --missing          print the files from stdin that are missing"))
@@ -107,6 +109,9 @@ Export/import one or more packages from/to the store.\n"))
          (option '("export") #f #f
                  (lambda (opt name arg result)
                    (alist-cons 'export #t result)))
+         (option '(#\r "recursive") #f #f
+                 (lambda (opt name arg result)
+                   (alist-cons 'export-recursive? #t result)))
          (option '("import") #f #f
                  (lambda (opt name arg result)
                    (alist-cons 'import #t result)))
@@ -230,7 +235,8 @@ resulting archive to the standard output port."
 
     (if (or (assoc-ref opts 'dry-run?)
             (build-derivations store drv))
-        (export-paths store files (current-output-port))
+        (export-paths store files (current-output-port)
+                      #:recursive? (assoc-ref opts 'export-recursive?))
         (leave (_ "unable to export the given packages~%")))))
 
 (define (generate-key-pair parameters)