From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id WFjsEg0o12J6AwAAbAwnHQ (envelope-from ) for ; Tue, 19 Jul 2022 23:54:21 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id GJL4EQ0o12LZ5QAAG6o9tA (envelope-from ) for ; Tue, 19 Jul 2022 23:54:21 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id E20C31B3C3 for ; Tue, 19 Jul 2022 23:54:20 +0200 (CEST) Received: from localhost ([::1]:57538 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oDvAZ-0000fY-Bu for larch@yhetil.org; Tue, 19 Jul 2022 17:54:19 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34160) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oDvAI-0000fF-Gn for guix-patches@gnu.org; Tue, 19 Jul 2022 17:54:02 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:57605) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oDvAI-0005HS-7Z for guix-patches@gnu.org; Tue, 19 Jul 2022 17:54:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oDvAH-0005aZ-VE for guix-patches@gnu.org; Tue, 19 Jul 2022 17:54:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#56649] [PATCH] doc: Clarify "Replicating Guix" section. Resent-From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Tue, 19 Jul 2022 21:54:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 56649 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 56649@debbugs.gnu.org Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= X-Debbugs-Original-To: guix-patches@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.165826758921421 (code B ref -1); Tue, 19 Jul 2022 21:54:01 +0000 Received: (at submit) by debbugs.gnu.org; 19 Jul 2022 21:53:09 +0000 Received: from localhost ([127.0.0.1]:55364 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oDv9Q-0005ZQ-PP for submit@debbugs.gnu.org; Tue, 19 Jul 2022 17:53:09 -0400 Received: from lists.gnu.org ([209.51.188.17]:44798) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oDv9N-0005ZH-Iy for submit@debbugs.gnu.org; Tue, 19 Jul 2022 17:53:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34048) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oDv9N-0000bX-Du for guix-patches@gnu.org; Tue, 19 Jul 2022 17:53:05 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:44326) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oDv9M-0005Ej-5v; Tue, 19 Jul 2022 17:53:04 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:Subject:To:From:in-reply-to: references; bh=vDAYTCCbpI0Wh/VzfvIJguqSXVs6rlWahgdm/z9xBwM=; b=b6BeJevmQM0gXi X7ME2BBH9HhAz/6UTRxtakVUpP9CYPgHM7m6E7qnlG/XOUQ258nvOgDk09HA3r4b8XfGe44lxLSM8 iXNOj/HRpIOSzCrEcJvngJkS1DvHTREoeTm9cFvihsiZuHjrgBpDflhrosgybjHq6dUyHBWddSn+2 WNy13flnFJx/fGauOY1D25R2O3kQM+KBRXW4TXe+qzuVAzYbiibjveJ0twOE/M6PjeLYfaIA1MwSp VR5Tl8xi5xIYVLZtKQTD61nqQoaK7jWiqJtxgcVjnHtLYcKz+9hXr5gudqhyq9XvjQfOr4P+CUON0 z3F0ABCvXPjPOJMXKl6A==; Received: from 91-160-117-201.subs.proxad.net ([91.160.117.201]:53614 helo=gnu.org) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oDv9L-0001a5-J7; Tue, 19 Jul 2022 17:53:03 -0400 From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Date: Tue, 19 Jul 2022 23:52:50 +0200 Message-Id: <20220719215250.25467-1-ludo@gnu.org> X-Mailer: git-send-email 2.37.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1658267661; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=vDAYTCCbpI0Wh/VzfvIJguqSXVs6rlWahgdm/z9xBwM=; b=F4okWu2Kl0qLwo6Corjb35V9gkxquooRv60Syspjpbx7tYRsVoW/W+EEs5CMCfLHZKlUj9 nhkRk9TtUZMZzW4rbKuogy/T1yl4C7ZZjDWI2hdqwwLuIz7Ikcz3mtJLFYXW+l2kKnPELA gWNNdLVDBfZGL7Z/zmf1h1vFtabJurmAM8X09CYVhqx8hB2/6cOyxjKByIBbc6yT/iIoVc SzCtOqttCNaJjomNd7f/6++YinW+CKPhIp9fRPzqfCf+4zkte01OJthA26dWk0iQ0few6/ KdW8k2GA6dOxNuN9w/uat9A7bybpUwaB3AGHVPZ/UeH2fRX66hwfze+eELkEBA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1658267661; a=rsa-sha256; cv=none; b=eOtes0nM02BjGHV481ZkaM1VeRUY4IOij7Cs0Wzy9NRbk3BOiHuS0fvoYZ5oehW+/7t9ZE VZOEWPPM4C2Nc7vhLLmvqsXz5w62pOAkJV/o/wBEJjXgRZ8BxCTuR8XoX41x4A9LACzJgw o95Ka2AI/icNqwo7cOHwt52fH9JemZ+8qL05RWRirlAozlEY82W92aE6fKZSMmjbF/mdaS pZFSI2D+tuSLH52s/zG4dy2hZOOgC2DmHKxAGB5UGu68If6zWXb9+rKZxtjbV/zX9o6gLQ PlON+4aeZX6bwsS2pqCFqDpnOBP6vipaGW4kPuvQ7OIm8cKr7QvXwS1DImnWQw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=b6BeJevm; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -4.23 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=b6BeJevm; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: E20C31B3C3 X-Spam-Score: -4.23 X-Migadu-Scanner: scn0.migadu.com X-TUID: taFGgrnmxMPc From: Ludovic Courtès * doc/guix.texi (Specifying Additional Channels): Replace 'guix pull --list-generations' example with 'guix describe'. (Replicating Guix): Rewrite to insist on 'guix describe', to include an example capturing channels and another one restoring them, and mention "lock files". --- doc/guix.texi | 65 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 25 deletions(-) Hi! I felt the “Replicating Guix” as it existed was unhelpful because it didn’t clearly show how to capture and restore channels, because it was biased towards ‘guix pull’ rather than ‘guix time-machine’, and because it was a bit too abstract. Thoughts? Ludo’. diff --git a/doc/guix.texi b/doc/guix.texi index d8a3d2e90c..85dfc55306 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -5276,8 +5276,7 @@ but also the package modules from your own repository. The result in modules: @example -$ guix pull --list-generations -@dots{} +$ guix describe Generation 19 Aug 27 2018 16:20:48 guix d894ab8 repository URL: https://git.savannah.gnu.org/git/guix.git @@ -5287,16 +5286,13 @@ Generation 19 Aug 27 2018 16:20:48 repository URL: https://example.org/variant-packages.git branch: master commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb - 11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{} - 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{} @end example @noindent -The output of @command{guix pull} above shows that Generation@tie{}19 includes -both Guix and packages from the @code{variant-personal-packages} channel. Among -the new and upgraded packages that are listed, some like @code{variant-gimp} and -@code{variant-emacs-with-cool-features} might come from -@code{variant-packages}, while others come from the Guix default channel. +The output of @command{guix describe} above shows that we're now running +Generation@tie{}19 and that it includes +both Guix and packages from the @code{variant-personal-packages} channel +(@pxref{Invoking guix describe}). @node Using a Custom Guix Channel @section Using a Custom Guix Channel @@ -5326,10 +5322,11 @@ addressed below (@pxref{Channel Authentication}). @cindex pinning, channels @cindex replicating Guix @cindex reproducibility, of Guix -The @command{guix pull --list-generations} output above shows precisely which -commits were used to build this instance of Guix. We can thus replicate it, -say, on another machine, by providing a channel specification in -@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits: +The @command{guix describe} command shows precisely which commits were +used to build the instance of Guix we're using (@pxref{Invoking guix +describe}). We can replicate this instance on another machine or at a +different point in time by providing a channel specification ``pinned'' +to these commits that looks like this: @lisp ;; Deploy specific commits of my channels of interest. @@ -5343,18 +5340,36 @@ say, on another machine, by providing a channel specification in (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) @end lisp -The @command{guix describe --format=channels} command can even generate this -list of channels directly (@pxref{Invoking guix describe}). The resulting -file can be used with the @option{-C} option of @command{guix pull} -(@pxref{Invoking guix pull}) or @command{guix time-machine} -(@pxref{Invoking guix time-machine}). - -At this point the two machines run the @emph{exact same Guix}, with access to -the @emph{exact same packages}. The output of @command{guix build gimp} on -one machine will be exactly the same, bit for bit, as the output of the same -command on the other machine. It also means both machines have access to all -the source code of Guix and, transitively, to all the source code of every -package it defines. +To obtain this pinned channel specification, the easiest way is to run +@command{guix describe} and to save its output in the @code{channels} +format in a file, like so: + +@example +guix describe -f channels > channels.scm +@end example + +The resulting @file{channels.scm} file can be passed to the @option{-C} +option of @command{guix pull} (@pxref{Invoking guix pull}) or +@command{guix time-machine} (@pxref{Invoking guix time-machine}), as in +this example: + +@example +guix time-machine -C channels.scm -- shell python -- python3 +@end example + +Given the @file{channels.scm} file, the command above will always fetch +the @emph{exact same Guix instance}, then use that instance to run the +exact same Python (@pxref{Invoking guix shell}). On any machine, at any +time, it ends up running the exact same binaries, bit for bit. + +@cindex lock files +Pinned channels address a problem similar to ``lock files'' as +implemented by some deployment tools---they let you pin and reproduce a +set of packages. In the case of Guix though, you are effectively +pinning the entire package set as defined at the given channel commits; +in fact, you are pinning all of Guix, including its core modules and +command-line tools. You're also getting strong guarantees that you are, +indeed, obtaining the exact same software. This gives you super powers, allowing you to track the provenance of binary artifacts with very fine grain, and to reproduce software environments at base-commit: 22530b2645d64658e4b7dea8801f5604dfd395a0 -- 2.37.0