guix-package: Report `--search' matches in recutils format.

[jackhill/guix/guix.git] / doc / guix.texi

diff --git a/doc/guix.texi b/doc/guix.texi
index e1ca095..3fee24d 100644 (file)
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -23,6 +23,7 @@
 @title{GNU Guix Reference Manual}
 @subtitle{Using the GNU Guix Functional Package Manager}
 @author Ludovic Courtès
+@author Nikita Karetnikov
 
 @page
 @vskip 0pt plus 1filll
@@ -509,6 +510,15 @@ the last transaction.
 When combined with options such as @code{--install}, roll back occurs
 before any other actions.
 
+When rolling back from the first generation that actually contains
+installed packages, the profile is made to point to the @dfn{empty
+profile}, also known as @dfn{profile zero}---i.e., it contains no files
+apart from its own meta-data.
+
+Installing, removing, or upgrading packages from a generation that has
+been rolled back to overwrites previous future generations.  Thus, the
+history of a profile's generations is always linear.
+
 @item --profile=@var{profile}
 @itemx -p @var{profile}
 Use @var{profile} instead of the user's default profile.
@@ -533,6 +543,25 @@ availability of packages:
 
 @table @option
 
+@item --search=@var{regexp}
+@itemx -s @var{regexp}
+List the available packages whose synopsis or description matches
+@var{regexp}.  Print all the meta-data of matching packages in
+@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
+GNU recutils manual}).
+
+This allows specific fields to be extracted using the @command{recsel}
+command, for instance:
+
+@example
+$ guix-package -s malloc | recsel -p name,version
+name: glibc
+version: 2.17
+
+name: libgc
+version: 7.2alpha6
+@end example
+
 @item --list-installed[=@var{regexp}]
 @itemx -I [@var{regexp}]
 List currently installed packages in the specified profile.  When