forked from lix-project/lix
155 lines
4.6 KiB
XML
155 lines
4.6 KiB
XML
<refentry xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink">
|
||
|
||
<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.
|
||
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
|
||
<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>Specify a cryptographic hash, which can be one of
|
||
<literal>md5</literal>, <literal>sha1</literal>, and
|
||
<literal>sha256</literal>.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--to-base16</option></term>
|
||
|
||
<listitem><para>Don’t 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>Don’t 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>
|