<refentry>
<refnamediv>
<refname>nix</refname>
<refpurpose>manipulate or query the Nix store</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix</command>
<group choice='opt'>
<arg><option>--path</option></arg>
<arg><option>-p</option></arg>
</group>
<group choice='opt' rep='repeat'>
<arg><option>--verbose</option></arg>
<arg><option>-v</option></arg>
</group>
<group choice='opt' rep='repeat'>
<arg><option>--keep-failed</option></arg>
<arg><option>-K</option></arg>
</group>
<arg choice='plain'><replaceable>operation</replaceable></arg>
<arg rep='repeat'><replaceable>options</replaceable></arg>
<arg rep='repeat'><replaceable>arguments</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The command <command>nix</command> provides access to the Nix store. This
is the (set of) path(s) where Nix expressions and the file system objects
built by them are stored.
</para>
<para>
<command>nix</command> has many subcommands called
<emphasis>operations</emphasis>. These are individually documented
below. Exactly one operation must always be provided.
</para>
</refsect1>
<refsect1>
<title>Common Options</title>
<para>
In this section the options that are common to all Nix operations are
listed. These options are allowed for every subcommand (although they
may not always have an effect).
</para>
<variablelist>
<varlistentry>
<term><option>--path</option></term>
<listitem>
<para>
Indicates that any identifier arguments to the operation are paths
in the store rather than identifiers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose</option></term>
<listitem>
<para>
Increases the level of verbosity of diagnostic messages printed on
standard error. For each Nix operation, the information printed on
standard output is well-defined and specified below in the
respective sections. Any diagnostic information is printed on
standard error, never on standard output.
</para>
<para>
This option may be specified repeatedly. Currently, the following
verbosity levels exist:
</para>
<variablelist>
<varlistentry>
<term>0</term>
<listitem>
<para>
Print error messages only.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>1</term>
<listitem>
<para>
Print informational messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>2</term>
<listitem>
<para>
Print even more informational messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>3</term>
<listitem>
<para>
Print messages that should only be useful for debugging.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>4</term>
<listitem>
<para>
<quote>Vomit mode</quote>: print vast amounts of debug
information.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--keep-failed</option></term>
<listitem>
<para>
Specifies that in case of a build failure, the temporary directory
(usually in <filename>/tmp</filename>) in which the build takes
place should not be deleted. The path of the build directory is
printed as an informational message.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<!--######################################################################-->
<refsect1>
<title>Operation <option>--install</option></title>
<refsect2>
<title>Synopsis</title>
<cmdsynopsis>
<command>nix</command>
<group>
<arg><option>--install</option></arg>
<arg><option>-i</option></arg>
</group>
<arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg>
</cmdsynopsis>
</refsect2>
<refsect2>
<title>Description</title>
<para>
The operation <option>--install</option> realises the Nix expressions
identified by <replaceable>ids</replaceable> in the file system. If
these expressions are derivation expressions, they are first
normalised. That is, their target paths are are built, unless a normal
form is already known.
</para>
<para>
The identifiers of the normal forms of the given Nix expressions are
printed on standard output.
</para>
</refsect2>
</refsect1>
<!--######################################################################-->
<refsect1>
<title>Operation <option>--delete</option></title>
<refsect2>
<title>Synopsis</title>
<cmdsynopsis>
<command>nix</command>
<group>
<arg><option>--delete</option></arg>
<arg><option>-d</option></arg>
</group>
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
</cmdsynopsis>
</refsect2>
<refsect2>
<title>Description</title>
<para>
The operation <option>--delete</option> unconditionally deletes the
paths <replaceable>paths</replaceable> from the Nix store. It is an
error to attempt to delete paths outside of the store.
</para>
<warning>
<para>
This operation should almost never be called directly, since no
attempt is made to verify that no references exist to the paths to
be deleted. Therefore, careless deletion can result in an
inconsistent system. Deletion of paths in the store is done by the
garbage collector (which uses <option>--delete</option> to delete
unreferenced paths).
</para>
</warning>
</refsect2>
</refsect1>
<!--######################################################################-->
<refsect1>
<title>Operation <option>--query</option></title>
<refsect2>
<title>Synopsis</title>
<cmdsynopsis>
<command>nix</command>
<group>
<arg><option>--query</option></arg>
<arg><option>-q</option></arg>
</group>
<group>
<group>
<arg><option>--list</option></arg>
<arg><option>-l</option></arg>
</group>
<group>
<arg><option>--requisites</option></arg>
<arg><option>-r</option></arg>
</group>
<group>
<arg><option>--expansion</option></arg>
<arg><option>-e</option></arg>
</group>
<group>
<arg><option>--graph</option></arg>
<arg><option>-g</option></arg>
</group>
</group>
<arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
</cmdsynopsis>
</refsect2>
<refsect2>
<title>Description</title>
<para>
The operation <option>--query</option> displays various bits of
information about Nix expressions or paths in the store. The queries
are described in <xref linkend='nixref-queries' />. At most one query
can be specified; the default query is <option>--list</option>.
</para>
</refsect2>
<refsect2 id='nixref-queries'>
<title>Queries</title>
<variablelist>
<varlistentry>
<term><option>--list</option></term>
<listitem>
<para>
Prints out the target paths of the Nix expressions indicated by
the identifiers <replaceable>args</replaceable>. In the case of
a derivation expression, these are the paths that will be
produced by the builder of the expression. In the case of a
slice expression, these are the root paths (which are generally
the paths that were produced by the builder of the derivation
expression of which the slice is a normal form).
</para>
<para>
This query has one option:
</para>
<variablelist>
<varlistentry>
<term><option>--normalise</option></term>
<listitem>
<para>
Causes the target paths of the <emphasis>normal
forms</emphasis> of the expressions to be printed, rather
than the target paths of the expressions themselves.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--requisites</option></term>
<listitem>
<para>
Prints out the requisite paths of the Nix expressions indicated
by the identifiers <replaceable>args</replaceable>. The
requisite paths of a Nix expression are the paths that need to be
present in the system to be able to realise the expression. That
is, they form the <emphasis>closure</emphasis> of the expression
in the file system (i.e., no path in the set of requisite paths
points to anything outside the set of requisite paths).
</para>
<para>
The notion of requisite paths is very useful when one wants to
distribute Nix expressions. Since they form a closure, they are
the only paths one needs to distribute to another system to be
able to realise the expression on the other system.
</para>
<para>
This query is generally used to implement various kinds of
distribution. A <emphasis>source distribution</emphasis> is
obtained by distributing the requisite paths of a derivation
expression. A <emphasis>binary distribution</emphasis> is
obtained by distributing the requisite paths of a slice
expression (i.e., the normal form of a derivation expression; you
can directly specify the identifier of the slice expression, or
use <option>--normalise</option> and specify the identifier of a
derivation expression). A <emphasis>cache
distribution</emphasis> is obtained by distributing the
requisite paths of a derivation expression and specifying the
option <option>--include-successors</option>. This will include
not just the paths of a source and binary distribution, but also
all expressions and paths of subterms of the source. This is
useful if one wants to realise on the target system a Nix
expression that is similar but not quite the same as the one
being distributed, since any common subterms will be reused.
</para>
<para>
This query has a number of options:
</para>
<variablelist>
<varlistentry>
<term><option>--normalise</option></term>
<listitem>
<para>
Causes the requisite paths of the <emphasis>normal
forms</emphasis> of the expressions to be printed, rather
than the requisite paths of the expressions themselves.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--exclude-exprs</option></term>
<listitem>
<para>
Excludes the paths of Nix expressions. This causes the
closure property to be lost, that is, the resulting set of
paths is not enough to ensure realisibility.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--include-successors</option></term>
<listitem>
<para>
Also include the requisites of successors (normal forms).
Only the requisites of <emphasis>known</emphasis>
successors are included, i.e., the normal forms of
derivation expressions that have never been normalised will
not be included.
</para>
<para>
Note that not just the successor of a derivation expression
will be included, but also the successors of all input
expressions of that derivation expression. I.e., all
normal forms of subterms involved in the normalisation of
the top-level term are included.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--expansion</option></term>
<listitem>
<para>
For each identifier in <replaceable>args</replaceable>, prints
all expansions of that identifier, that is, all paths whose
current content matches the identifier.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--graph</option></term>
<listitem>
<para>
Prints a graph of the closure of the expressions identified by
<replaceable>args</replaceable> in the format of the
<command>dot</command> tool of AT&T's GraphViz package.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
</refentry>
<!--
local variables:
sgml-parent-document: ("book.xml" "refentry")
end:
-->
