guix.texi

versa.

The result of running @command{guix pull} is a @dfn{profile} available
under @file{~/.config/guix/current} containing the latest Guix.  Thus,
make sure to add it to the beginning of your search path so that you use
the latest version, and similarly for the Info manual
(@pxref{Documentation}):

@example
export PATH="$HOME/.config/guix/current/bin:$PATH"
export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
@end example

The @option{--list-generations} or @option{-l} option lists past generations
produced by @command{guix pull}, along with details about their provenance:

@example
$ guix pull -l
Generation 1	Jun 10 2018 00:18:18
  guix 65956ad
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: origin/master
    commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe

Generation 2	Jun 11 2018 11:02:49
  guix e0cc7f6
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: origin/master
    commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
  2 new packages: keepalived, libnfnetlink
  6 packages upgraded: emacs-nix-mode@@2.0.4,
    guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac,
    heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4

Generation 3	Jun 13 2018 23:31:07	(current)
  guix 844cc1c
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: origin/master
    commit: 844cc1c8f394f03b404c5bb3aee086922373490c
  28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{}
  69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
@end example

@xref{Invoking guix describe, @command{guix describe}}, for other ways to
describe the current status of Guix.

This @code{~/.config/guix/current} profile works exactly like the profiles
created by @command{guix package} (@pxref{Invoking guix package}). That
is, you can list generations, roll back to the previous
generation---i.e., the previous Guix---and so on:

@example
$ guix pull --roll-back
switched from generation 3 to 2
$ guix pull --delete-generations=1
deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
@end example

You can also use @command{guix package} (@pxref{Invoking guix package})
to manage the profile by naming it explicitly:
@example
$ guix package -p ~/.config/guix/current --roll-back
switched from generation 3 to 2
$ guix package -p ~/.config/guix/current --delete-generations=1
deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
@end example

The @command{guix pull} command is usually invoked with no arguments,
but it supports the following options:

@table @code
@item --url=@var{url}
@itemx --commit=@var{commit}
@itemx --branch=@var{branch}
Download code for the @code{guix} channel from the specified @var{url}, at the
given @var{commit} (a valid Git commit ID represented as a hexadecimal
string), or @var{branch}.

@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
These options are provided for convenience, but you can also specify your
configuration in the @file{~/.config/guix/channels.scm} file or using the
@option{--channels} option (see below).

@item --channels=@var{file}
@itemx -C @var{file}
Read the list of channels from @var{file} instead of
@file{~/.config/guix/channels.scm} or @file{/etc/guix/channels.scm}.
@var{file} must contain Scheme code that
evaluates to a list of channel objects.  @xref{Channels}, for more
information.

@cindex channel news
@item --news
@itemx -N
Display the list of packages added or upgraded since the previous
generation, as well as, occasionally, news written by channel authors
for their users (@pxref{Channels, Writing Channel News}).

The package information is the same as displayed upon @command{guix
pull} completion, but without ellipses; it is also similar to the output
of @command{guix pull -l} for the last generation (see below).

@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
is provided, the subset of generations that match @var{pattern}.
The syntax of @var{pattern} is the same as with @code{guix package
--list-generations} (@pxref{Invoking guix package}).

@item --roll-back
@cindex rolling back
@cindex undoing transactions
@cindex transactions, undoing
Roll back to the previous @dfn{generation} of @file{~/.config/guix/current}---i.e.,
undo the last transaction.

@item --switch-generation=@var{pattern}
@itemx -S @var{pattern}
@cindex generations
Switch to a particular generation defined by @var{pattern}.

@var{pattern} may be either a generation number or a number prefixed
with ``+'' or ``-''.  The latter means: move forward/backward by a
specified number of generations.  For example, if you want to return to
the latest generation after @option{--roll-back}, use
@option{--switch-generation=+1}.

@item --delete-generations[=@var{pattern}]
@itemx -d [@var{pattern}]
When @var{pattern} is omitted, delete all generations except the current
one.

This command accepts the same patterns as @option{--list-generations}.
When @var{pattern} is specified, delete the matching generations.  When
@var{pattern} specifies a duration, generations @emph{older} than the
specified duration match.  For instance, @option{--delete-generations=1m}
deletes generations that are more than one month old.

If the current generation matches, it is @emph{not} deleted.

Note that deleting generations prevents rolling back to them.
Consequently, this command must be used with care.

@xref{Invoking guix describe}, for a way to display information about the
current generation only.

@item --profile=@var{profile}
@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 --allow-downgrades
Allow pulling older or unrelated revisions of channels than those
currently in use.

@cindex downgrade attacks, protection against
By default, @command{guix pull} protects against so-called ``downgrade
attacks'' whereby the Git repository of a channel would be reset to an
earlier or unrelated revision of itself, potentially leading you to
install older, known-vulnerable versions of software packages.

@quotation Note
Make sure you understand its security implications before using
@option{--allow-downgrades}.
@end quotation

@item --disable-authentication
Allow pulling channel code without authenticating it.

@cindex authentication, of channel code
By default, @command{guix pull} authenticates code downloaded from
channels by verifying that its commits are signed by authorized
developers, and raises an error if this is not the case.  This option
instructs it to not perform any such verification.

@quotation Note
Make sure you understand its security implications before using
@option{--disable-authentication}.
@end quotation

@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
the system type of the build host.

@item --bootstrap
Use the bootstrap Guile to build the latest Guix.  This option is only
useful to Guix developers.
@end table

The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
repository and branch to pull from, as well as @emph{additional} repositories
containing package modules that should be deployed.  @xref{Channels}, for more
information.

In addition, @command{guix pull} supports all the common build options
(@pxref{Common Build Options}).

@node Invoking guix time-machine
@section Invoking @command{guix time-machine}

@cindex @command{guix time-machine}
@cindex pinning, channels
@cindex replicating Guix
@cindex reproducibility, of Guix

The @command{guix time-machine} command provides access to other
revisions of Guix, for example to install older versions of packages,
or to reproduce a computation in an identical environment.  The revision
of Guix to be used is defined by a commit or by a channel
description file created by @command{guix describe}
(@pxref{Invoking guix describe}).

The general syntax is:

@example
guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
@end example

where @var{command} and @var{arg}@dots{} are passed unmodified to the
@command{guix} command of the specified revision.  The @var{options} that define
this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):

@table @code
@item --url=@var{url}
@itemx --commit=@var{commit}
@itemx --branch=@var{branch}
Use the @code{guix} channel from the specified @var{url}, at the
given @var{commit} (a valid Git commit ID represented as a hexadecimal
string), or @var{branch}.

@item --channels=@var{file}
@itemx -C @var{file}
Read the list of channels from @var{file}.  @var{file} must contain
Scheme code that evaluates to a list of channel objects.
@xref{Channels} for more information.
@end table

As for @command{guix pull}, the absence of any options means that the
the latest commit on the master branch will be used. The command

@example
guix time-machine -- build hello
@end example

will thus build the package @code{hello} as defined in the master branch,
which is in general a newer revision of Guix than you have installed.
Time travel works in both directions!

Note that @command{guix time-machine} can trigger builds of channels and
their dependencies, and these are controlled by the standard build
options (@pxref{Common Build Options}).

@node Inferiors
@section Inferiors

@c TODO: Remove this once we're more confident about API stability.
@quotation Note
The functionality described here is a ``technology preview'' as of version
@value{VERSION}.  As such, the interface is subject to change.
@end quotation

@cindex inferiors
@cindex composition of Guix revisions
Sometimes you might need to mix packages from the revision of Guix you're
currently running with packages available in a different revision of Guix.
Guix @dfn{inferiors} allow you to achieve that by composing different Guix
revisions in arbitrary ways.

@cindex inferior packages
Technically, an ``inferior'' is essentially a separate Guix process connected
to your main Guix process through a REPL (@pxref{Invoking guix repl}).  The
@code{(guix inferior)} module allows you to create inferiors and to
communicate with them.  It also provides a high-level interface to browse and
manipulate the packages that an inferior provides---@dfn{inferior packages}.

When combined with channels (@pxref{Channels}), inferiors provide a simple way
to interact with a separate revision of Guix.  For example, let's assume you
want to install in your profile the current @code{guile} package, along with
the @code{guile-json} as it existed in an older revision of Guix---perhaps
because the newer @code{guile-json} has an incompatible API and you want to
run your code against the old API@.  To do that, you could write a manifest for
use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
manifest, you would create an inferior for that old Guix revision you care
about, and you would look up the @code{guile-json} package in the inferior:

@lisp
(use-modules (guix inferior) (guix channels)
             (srfi srfi-1))   ;for 'first'

(define channels
  ;; This is the old revision from which we want to
  ;; extract guile-json.
  (list (channel
         (name 'guix)
         (url "https://git.savannah.gnu.org/git/guix.git")
         (commit
          "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))

(define inferior
  ;; An inferior representing the above revision.
  (inferior-for-channels channels))

;; Now create a manifest with the current "guile" package
;; and the old "guile-json" package.
(packages->manifest
 (list (first (lookup-inferior-packages inferior "guile-json"))
       (specification->package "guile")))
@end lisp

On its first run, @command{guix package --manifest} might have to build the
channel you specified before it can create the inferior; subsequent runs will
be much faster because the Guix revision will be cached.

The @code{(guix inferior)} module provides the following procedures to open an
inferior:

@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
   [#:cache-directory] [#:ttl]
Return an inferior for @var{channels}, a list of channels.  Use the cache at
@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
This procedure opens a new connection to the build daemon.

As a side effect, this procedure may build or substitute binaries for
@var{channels}, which can take time.
@end deffn

@deffn {Scheme Procedure} open-inferior @var{directory} @
  [#:command "bin/guix"]
Open the inferior Guix in @var{directory}, running
@code{@var{directory}/@var{command} repl} or equivalent.  Return @code{#f} if
the inferior could not be launched.
@end deffn

@cindex inferior packages
The procedures listed below allow you to obtain and manipulate inferior
packages.

@deffn {Scheme Procedure} inferior-packages @var{inferior}
Return the list of packages known to @var{inferior}.
@end deffn

@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
   [@var{version}]
Return the sorted list of inferior packages matching @var{name} in
@var{inferior}, with highest version numbers first.  If @var{version} is true,
return only packages with a version number prefixed by @var{version}.
@end deffn

@deffn {Scheme Procedure} inferior-package? @var{obj}
Return true if @var{obj} is an inferior package.
@end deffn

@deffn {Scheme Procedure} inferior-package-name @var{package}
@deffnx {Scheme Procedure} inferior-package-version @var{package}
@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
@deffnx {Scheme Procedure} inferior-package-description @var{package}
@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
@deffnx {Scheme Procedure} inferior-package-location @var{package}
@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
These procedures are the counterpart of package record accessors
(@pxref{package Reference}).  Most of them work by querying the inferior
@var{package} comes from, so the inferior must still be live when you call
these procedures.
@end deffn

Inferior packages can be used transparently like any other package or
file-like object in G-expressions (@pxref{G-Expressions}).  They are also
transparently handled by the @code{packages->manifest} procedure, which is
commonly use in manifests (@pxref{Invoking guix package, the
@option{--manifest} option of @command{guix package}}).  Thus you can insert
an inferior package pretty much anywhere you would insert a regular package:
in manifests, in the @code{packages} field of your @code{operating-system}
declaration, and so on.

@node Invoking guix describe
@section Invoking @command{guix describe}

@cindex reproducibility
@cindex replicating Guix
Often you may want to answer questions like: ``Which revision of Guix am I
using?'' or ``Which channels am I using?''  This is useful information in many
situations: if you want to @emph{replicate} an environment on a different
machine or user account, if you want to report a bug or to determine what
change in the channels you are using caused it, or if you want to record your
system state for reproducibility purposes.  The @command{guix describe}
command answers these questions.

When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
displays the channel(s) that it was built from, including their repository URL
and commit IDs (@pxref{Channels}):

@example
$ guix describe
Generation 10	Sep 03 2018 17:32:44	(current)
  guix e0fa68c
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: e0fa68c7718fffd33d81af415279d6ddb518f727
@end example

If you're familiar with the Git version control system, this is similar in
spirit to @command{git describe}; the output is also similar to that of
@command{guix pull --list-generations}, but limited to the current generation
(@pxref{Invoking guix pull, the @option{--list-generations} option}).  Because
the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
information is all it takes to describe the revision of Guix you're using, and
also to replicate it.

To make it easier to replicate Guix, @command{guix describe} can also be asked
to return a list of channels instead of the human-readable description above:

@example
$ guix describe -f channels
(list (channel
        (name 'guix)
        (url "https://git.savannah.gnu.org/git/guix.git")
        (commit
          "e0fa68c7718fffd33d81af415279d6ddb518f727")
        (introduction
          (make-channel-introduction
            "9edb3f66fd807b096b48283debdcddccfea34bad"
            (openpgp-fingerprint
              "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA")))))
@end example

@noindent
You can save this to a file and feed it to @command{guix pull -C} on some
other machine or at a later point in time, which will instantiate @emph{this
exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
From there on, since you're able to deploy the same revision of Guix, you can
just as well @emph{replicate a complete software environment}.  We humbly
think that this is @emph{awesome}, and we hope you'll like it too!

The details of the options supported by @command{guix describe} are as
follows:

@table @code
@item --format=@var{format}
@itemx -f @var{format}
Produce output in the specified @var{format}, one of:

@table @code
@item human
produce human-readable output;
@item channels
produce a list of channel specifications that can be passed to @command{guix
pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
guix pull});
@item channels-sans-intro
like @code{channels}, but omit the @code{introduction} field; use it to
produce a channel specification suitable for Guix version 1.1.0 or
earlier---the @code{introduction} field has to do with channel
authentication (@pxref{Channels, Channel Authentication}) and is not
supported by these older versions;
@item json
@cindex JSON
produce a list of channel specifications in JSON format;
@item recutils
produce a list of channel specifications in Recutils format.
@end table

@item --list-formats
Display available formats for @option{--format} option.

@item --profile=@var{profile}
@itemx -p @var{profile}
Display information about @var{profile}.
@end table

@node Invoking guix archive
@section Invoking @command{guix archive}

@cindex @command{guix archive}
@cindex archive
The @command{guix archive} command allows users to @dfn{export} files
from the store into a single archive, and to later @dfn{import} them on
a machine that runs Guix.
In particular, it allows store files to be transferred from one machine
to the store on another machine.

@quotation Note
If you're looking for a way to produce archives in a format suitable for
tools other than Guix, @pxref{Invoking guix pack}.
@end quotation

@cindex exporting store items
To export store files as an archive to standard output, run:

@example
guix archive --export @var{options} @var{specifications}...
@end example

@var{specifications} may be either store file names or package
specifications, as for @command{guix package} (@pxref{Invoking guix
package}).  For instance, the following command creates an archive
containing the @code{gui} output of the @code{git} package and the main
output of @code{emacs}:

@example
guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
@end example

If the specified packages are not built yet, @command{guix archive}
automatically builds them.  The build process may be controlled with the
common build options (@pxref{Common Build Options}).

To transfer the @code{emacs} package to a machine connected over SSH,
one would run:

@example
guix archive --export -r emacs | ssh the-machine guix archive --import
@end example

@noindent
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
@option{-r}), regardless of what is already available in the store on
the target machine.  The @option{--missing} option can help figure out
which items are missing from the target store.  The @command{guix copy}
command simplifies and optimizes this whole process, so this is probably
what you should use in this case (@pxref{Invoking guix copy}).

@cindex nar, archive format
@cindex normalized archive (nar)
@cindex nar bundle, archive format
Each store item is written in the @dfn{normalized archive} or @dfn{nar}
format (described below), and the output of @command{guix archive
--export} (and input of @command{guix archive --import}) is a @dfn{nar
bundle}.

The nar format is
comparable in spirit to `tar', but with differences
that make it more appropriate for our purposes.  First, rather than
recording all Unix metadata for each file, the nar format only mentions
the file type (regular, directory, or symbolic link); Unix permissions
and owner/group are dismissed.  Second, the order in which directory
entries are stored always follows the order of file names according to
the C locale collation order.  This makes archive production fully
deterministic.

That nar bundle format is essentially the concatenation of zero or more
nars along with metadata for each store item it contains: its file name,
references, corresponding derivation, and a digital signature.

When exporting, the daemon digitally signs the contents of the archive,
and that digital signature is appended.  When importing, the daemon
verifies the signature and rejects the import in case of an invalid
signature or if the signing key is not authorized.
@c FIXME: Add xref to daemon doc about signatures.

The main options are:

@table @code
@item --export
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
@option{--recursive} is passed.

@item -r
@itemx --recursive
When combined with @option{--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
signature, or if it is signed by a public key not among the authorized
keys (see @option{--authorize} below).

@item --missing
Read a list of store file names from the standard input, one per line,
and write on the standard output the subset of these files missing from
the store.

@item --generate-key[=@var{parameters}]
@cindex signing, archives
Generate a new key pair for the daemon.  This is a prerequisite before
archives can be exported with @option{--export}.  Note that this
operation usually takes time, because it needs to gather enough entropy
to generate the key pair.

The generated key pair is typically stored under @file{/etc/guix}, in
@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
key, which must be kept secret).  When @var{parameters} is omitted,
an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
versions before 1.6.0, it is a 4096-bit RSA key.
Alternatively, @var{parameters} can specify
@code{genkey} parameters suitable for Libgcrypt (@pxref{General
public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
Libgcrypt Reference Manual}).

@item --authorize
@cindex authorizing, archives
Authorize imports signed by the public key passed on standard input.
The public key must be in ``s-expression advanced format''---i.e., the
same format as the @file{signing-key.pub} file.

The list of authorized keys is kept in the human-editable file
@file{/etc/guix/acl}.  The file contains
@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.

@item --extract=@var{directory}
@itemx -x @var{directory}
Read a single-item archive as served by substitute servers
(@pxref{Substitutes}) and extract it to @var{directory}.  This is a
low-level operation needed in only very narrow use cases; see below.

For example, the following command extracts the substitute for Emacs
served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:

@example
$ wget -O - \
  https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
  | gunzip | guix archive -x /tmp/emacs
@end example

Single-item archives are different from multiple-item archives produced
by @command{guix archive --export}; they contain a single store item,
and they do @emph{not} embed a signature.  Thus this operation does
@emph{no} signature verification and its output should be considered
unsafe.

The primary purpose of this operation is to facilitate inspection of
archive contents coming from possibly untrusted substitute servers
(@pxref{Invoking guix challenge}).

@item --list
@itemx -t
Read a single-item archive as served by substitute servers
(@pxref{Substitutes}) and print the list of files it contains, as in
this example:

@example
$ wget -O - \
  https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
  | lzip -d | guix archive -t
@end example

@end table

@c *********************************************************************
@node Channels
@chapter Channels

@cindex channels
@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
@cindex @command{guix pull}, configuration file
@cindex configuration of @command{guix pull}
Guix and its package collection are updated by running @command{guix pull}
(@pxref{Invoking guix pull}).  By default @command{guix pull} downloads and
deploys Guix itself from the official GNU@tie{}Guix repository.  This can be
customized by defining @dfn{channels} in the
@file{~/.config/guix/channels.scm} file.  A channel specifies a URL and branch
of a Git repository to be deployed, and @command{guix pull} can be instructed
to pull from one or more channels.  In other words, channels can be used
to @emph{customize} and to @emph{extend} Guix, as we will see below.
Guix is able to take into account security concerns and deal with authenticated
updates.

@menu
* Specifying Additional Channels::  Extending the package collection.
* Using a Custom Guix Channel::  Using a customized Guix.
* Replicating Guix::            Running the @emph{exact same} Guix.
* Channel Authentication::      How Guix verifies what it fetches.
* Primary URL::                 Distinguishing mirror to original.
* Creating a Channel::          How to write your custom channel.
* Package Modules in a Sub-directory::  Specifying the channel's package modules location.
* Declaring Channel Dependencies::  How to depend on other channels.
* Specifying Channel Authorizations::  Defining channel authors authorizations.
* Writing Channel News::        Communicating information to channel's users.
@end menu

@node Specifying Additional Channels
@section Specifying Additional Channels

@cindex extending the package collection (channels)
@cindex variant packages (channels)
You can specify @emph{additional channels} to pull from. To use a channel, write
@code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it
@emph{in addition} to the default Guix channel(s):

@vindex %default-channels
@lisp
;; Add variant packages to those Guix provides.
(cons (channel
        (name 'variant-packages)
        (url "https://example.org/variant-packages.git"))
      %default-channels)
@end lisp

@noindent
Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
add a channel the list of channels that the variable @code{%default-channels}
is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
Manual}).  With this file in place, @command{guix pull} builds not only Guix
but also the package modules from your own repository.  The result in
@file{~/.config/guix/current} is the union of Guix with your own package
modules:

@example
$ guix pull --list-generations
@dots{}
Generation 19	Aug 27 2018 16:20:48
  guix d894ab8
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
  variant-packages dd3df5e
    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.

@node Using a Custom Guix Channel
@section Using a Custom Guix Channel

The channel called @code{guix} specifies where Guix itself---its command-line
tools as well as its package collection---should be downloaded.  For instance,
suppose you want to update from another copy of the Guix repository at
@code{example.org}, and specifically the @code{super-hacks} branch, you can
write in @code{~/.config/guix/channels.scm} this specification:

@lisp
;; Tell 'guix pull' to use another repo.
(list (channel
        (name 'guix)
        (url "https://example.org/another-guix.git")
        (branch "super-hacks")))
@end lisp

@noindent
From there on, @command{guix pull} will fetch code from the @code{super-hacks}
branch of the repository at @code{example.org}.  The authentication concern is
addressed below ((@pxref{Channel  Authentication}).

@node Replicating Guix
@section Replicating Guix

@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:

@lisp
;; Deploy specific commits of my channels of interest.
(list (channel
       (name 'guix)
       (url "https://git.savannah.gnu.org/git/guix.git")
       (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
      (channel
       (name 'variant-packages)
       (url "https://example.org/variant-packages.git")
       (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 -C options 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.

This gives you super powers, allowing you to track the provenance of binary
artifacts with very fine grain, and to reproduce software environments at
will---some sort of ``meta reproducibility'' capabilities, if you will.
@xref{Inferiors}, for another way to take advantage of these super powers.

@node Channel Authentication
@section Channel Authentication

@anchor{channel-authentication}
@cindex authentication, of channel code
The @command{guix pull} and @command{guix time-machine} commands
@dfn{authenticate} the code retrieved from channels: they make sure each
commit that is fetched is signed by an authorized developer.  The goal
is to protect from unauthorized modifications to the channel that would
lead users to run malicious code.

As a user, you must provide a @dfn{channel introduction} in your
channels file so that Guix knows how to authenticate its first commit.
A channel specification, including its introduction, looks something
along these lines:

@lisp
(channel
  (name 'some-channel)
  (url "https://example.org/some-channel.git")
  (introduction
   (make-channel-introduction
    "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
    (openpgp-fingerprint
     "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
@end lisp

The specification above shows the name and URL of the channel.  The call
to @code{make-channel-introduction} above specifies that authentication
of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.

For the main channel, called @code{guix}, you automatically get that
information from your Guix installation.  For other channels, include
the channel introduction provided by the channel authors in your
@file{channels.scm} file.  Make sure you retrieve the channel
introduction from a trusted source since that is the root of your trust.

If you're curious about the authentication mechanics, read on!

@cindex primary URL, channels
@node Primary URL
@section Primary URL

Channel authors can indicate the primary URL of their channel's Git
repository in the @file{.guix-channel} file, like so:

@lisp
(channel
  (version 0)
  (url "https://example.org/guix.git"))
@end lisp

This allows @command{guix pull} to determine whether it is pulling code
from a mirror of the channel; when that is the case, it warns the user
that the mirror might be stale and displays the primary URL.  That way,
users cannot be tricked into fetching code from a stale mirror that does
not receive security updates.

This feature only makes sense for authenticated repositories, such as
the official @code{guix} channel, for which @command{guix pull} ensures
the code it fetches is authentic.

@cindex personal packages (channels)
@cindex channels, for personal packages
@node Creating a Channel
@section Creating a Channel

Let's say you have a bunch of custom package variants or personal packages
that you think would make little sense to contribute to the Guix project, but
would like to have these packages transparently available to you at the
command line.  You would first write modules containing those package
definitions (@pxref{Package Modules}), maintain them in a Git repository, and
then you and anyone else can use it as an additional channel to get packages
from.  Neat, no?

@c What follows stems from discussions at
@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
@c earlier discussions on guix-devel@gnu.org.
@quotation Warning
Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
publish your personal channel to the world, we would like to share a few words
of caution:

@itemize
@item
Before publishing a channel, please consider contributing your package
definitions to Guix proper (@pxref{Contributing}).  Guix as a project is open
to free software of all sorts, and packages in Guix proper are readily
available to all Guix users and benefit from the project's quality assurance
process.

@item
When you maintain package definitions outside Guix, we, Guix developers,
consider that @emph{the compatibility burden is on you}.  Remember that
package modules and package definitions are just Scheme code that uses various
programming interfaces (APIs).  We want to remain free to change these APIs to
keep improving Guix, possibly in ways that break your channel.  We never
change APIs gratuitously, but we will @emph{not} commit to freezing APIs
either.

@item
Corollary: if you're using an external channel and that channel breaks, please
@emph{report the issue to the channel authors}, not to the Guix project.
@end itemize

You've been warned!  Having said this, we believe external channels are a
practical way to exert your freedom to augment Guix' package collection and to
share your improvements, which are basic tenets of
@uref{https://www.gnu.org/philosophy/free-sw.html, free software}.  Please
email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
@end quotation

To create a channel, create a Git repository containing your own package
modules and make it available.  The repository can contain anything, but a
useful channel will contain Guile modules that export packages.  Once you
start using a channel, Guix will behave as if the root directory of that
channel's Git repository has been added to the Guile load path (@pxref{Load
Paths,,, guile, GNU Guile Reference Manual}).  For example, if your channel
contains a file at @file{my-packages/my-tools.scm} that defines a Guile
module, then the module will be available under the name @code{(my-packages
my-tools)}, and you will be able to use it like any other module
(@pxref{Modules,,, guile, GNU Guile Reference Manual}).

As a channel author, consider bundling authentication material with your
channel so that users can authenticate it.  @xref{Channel
Authentication}, and @ref{Specifying Channel Authorizations}, for info
on how to do it.


@cindex subdirectory, channels
@node Package Modules in a Sub-directory
@section Package Modules in a Sub-directory

As a channel author, you may want to keep your channel modules in a
sub-directory.  If your modules are in the sub-directory @file{guix}, you must
add a meta-data file @file{.guix-channel} that contains:

@lisp
(channel
  (version 0)
  (directory "guix"))
@end lisp

@cindex dependencies, channels
@cindex meta-data, channels
@node Declaring Channel Dependencies
@section Declaring Channel Dependencies

Channel authors may decide to augment a package collection provided by other
channels.  They can declare their channel to be dependent on other channels in
a meta-data file @file{.guix-channel}, which is to be placed in the root of
the channel repository.

The meta-data file should contain a simple S-expression like this:

@lisp
(channel
 (version 0)
 (dependencies
  (channel
   (name 'some-collection)
   (url "https://example.org/first-collection.git")

   ;; The 'introduction' bit below is optional: you would
   ;; provide it for dependencies that can be authenticated.
   (introduction
    (channel-introduction
      (version 0)
      (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
      (signer "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
  (channel
   (name 'some-other-collection)
   (url "https://example.org/second-collection.git")
   (branch "testing"))))
@end lisp

In the above example this channel is declared to depend on two other channels,
which will both be fetched automatically.  The modules provided by the channel
will be compiled in an environment where the modules of all these declared
channels are available.

For the sake of reliability and maintainability, you should avoid dependencies
on channels that you don't control, and you should aim to keep the number of
dependencies to a minimum.