path: root/doc/manual/nix-reference.xml

<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>
      <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>
    </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>


</refentry>


<!--
local variables:
sgml-parent-document: ("book.xml" "refentry")
end:
-->