about summary refs log tree commit diff
path: root/doc/manual/command-ref/nix-hash.xml
blob: 80263e18e339e488c57690eb4795ef3bc5f16ad4 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
<refentry xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      version="5.0"
      xml:id="sec-nix-hash">
  
<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>

<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.  To generate
the same hash as <command>nix-prefetch-url</command> you have to
specify multiple arguments, see below for an example.</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>Use the specified cryptographic hash algorithm,
    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 the same hash as <command>nix-prefetch-url</command>:
<screen>
$ nix-prefetch-url file://&lt;(echo test)
1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
$ nix-hash --type sha256 --flat --base32 &lt;(echo test)
1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
</screen>
</para>

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