guix/doc/manual/nix-hash.xml

165 lines
5 KiB
XML
Raw Normal View History

2006-10-02 22:11:44 +00:00
<refentry xmlns="http://docbook.org/ns/docbook"
2007-09-19 14:01:41 +00:00
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-nix-hash">
2006-10-02 22:11:44 +00:00
2007-09-19 14:01:41 +00:00
<refmeta>
<refentrytitle>nix-hash</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">Nix</refmiscinfo>
<refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
</refmeta>
2006-10-02 22:11:44 +00:00
<refnamediv>
<refname>nix-hash</refname>
<refpurpose>compute the cryptographic hash of a path</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix-hash</command>
<arg><option>--flat</option></arg>
<arg><option>--base32</option></arg>
<arg><option>--truncate</option></arg>
<arg><option>--type</option> <replaceable>hashAlgo</replaceable></arg>
<arg choice='plain' rep='repeat'><replaceable>path</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>nix-hash</command>
<arg choice='plain'><option>--to-base16</option></arg>
<arg choice='plain' rep='repeat'><replaceable>hash</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>nix-hash</command>
<arg choice='plain'><option>--to-base32</option></arg>
<arg choice='plain' rep='repeat'><replaceable>hash</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsection><title>Description</title>
<para>The command <command>nix-hash</command> computes the
cryptographic hash of the contents of each
<replaceable>path</replaceable> and prints it on standard output. By
default, it computes an MD5 hash, but other hash algorithms are
available as well. The hash is printed in hexadecimal.</para>
<para>The hash is computed over a <emphasis>serialisation</emphasis>
of each path: a dump of the file system tree rooted at the path. This
allows directories and symlinks to be hashed as well as regular files.
2006-10-05 23:13:15 +00:00
The dump is in the <emphasis>NAR format</emphasis> produced by <link
linkend="refsec-nix-store-dump"><command>nix-store</command>
<option>--dump</option></link>. Thus, <literal>nix-hash
<replaceable>path</replaceable></literal> yields the same
cryptographic hash as <literal>nix-store --dump
2006-10-02 22:11:44 +00:00
<replaceable>path</replaceable> | md5sum</literal>.</para>
</refsection>
<refsection><title>Options</title>
<variablelist>
<varlistentry><term><option>--flat</option></term>
<listitem><para>Print the cryptographic hash of the contents of
each regular file <replaceable>path</replaceable>. That is, do
not compute the hash over the dump of
<replaceable>path</replaceable>. The result is identical to that
produced by the GNU commands <command>md5sum</command> and
<command>sha1sum</command>.</para></listitem>
</varlistentry>
<varlistentry><term><option>--base32</option></term>
<listitem><para>Print the hash in a base-32 representation rather
than hexadecimal. This base-32 representation is more compact and
can be used in Nix expressions (such as in calls to
<function>fetchurl</function>).</para></listitem>
</varlistentry>
<varlistentry><term><option>--truncate</option></term>
<listitem><para>Truncate hashes longer than 160 bits (such as
SHA-256) to 160 bits.</para></listitem>
</varlistentry>
<varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term>
<listitem><para>Use the specified cryptographic hash algorithm,
which can be one of <literal>md5</literal>,
<literal>sha1</literal>, and
2006-10-02 22:11:44 +00:00
<literal>sha256</literal>.</para></listitem>
</varlistentry>
<varlistentry><term><option>--to-base16</option></term>
<listitem><para>Dont hash anything, but convert the base-32 hash
representation <replaceable>hash</replaceable> to
hexadecimal.</para></listitem>
</varlistentry>
<varlistentry><term><option>--to-base32</option></term>
<listitem><para>Dont hash anything, but convert the hexadecimal
hash representation <replaceable>hash</replaceable> to
base-32.</para></listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection><title>Examples</title>
<para>Computing hashes:
<screen>
$ mkdir test
$ echo "hello" > test/world
$ nix-hash test/ <lineannotation>(MD5 hash; default)</lineannotation>
8179d3caeff1869b5ba1744e5a245c04
$ nix-store --dump test/ | md5sum <lineannotation>(for comparison)</lineannotation>
8179d3caeff1869b5ba1744e5a245c04 -
$ nix-hash --type sha1 test/
e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
$ nix-hash --type sha1 --base32 test/
nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
$ nix-hash --type sha256 --flat test/
error: reading file `test/': Is a directory
$ nix-hash --type sha256 --flat test/world
5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03</screen>
</para>
<para>Converting between hexadecimal and base-32:
<screen>
$ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
$ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6</screen>
</para>
</refsection>
</refentry>