From 84e6c43e85cab83ee033bf13c1e58c0f30ca1de9 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <e.dolstra@tudelft.nl>
Date: Mon, 2 Oct 2006 22:11:44 +0000
Subject: [PATCH] * Documented nix-hash.

---
 doc/manual/Makefile.am             |   2 +-
 doc/manual/manual.xml              |   4 +
 doc/manual/nix-hash.xml            | 153 +++++++++++++++++++++++++++++
 doc/manual/nix-install-package.xml |   3 -
 doc/manual/nix-store.xml           |   3 +
 5 files changed, 161 insertions(+), 4 deletions(-)
 create mode 100644 doc/manual/nix-hash.xml

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index ea8cb3e9ad..1e490e8ffc 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -11,7 +11,7 @@ man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
  nix-collect-garbage.1 nix-push.1 nix-pull.1 \
  nix-prefetch-url.1 nix-channel.1 \
  nix-pack-closure.1 nix-unpack-closure.1 \
- nix-install-package.1
+ nix-install-package.1 nix-hash.1
 
 FIGURES = figures/user-environments.png
 
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index db9e77c6b5..d8fd5ddb21 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -69,6 +69,10 @@
         <title>nix-collect-garbage</title>
         <xi:include href="nix-collect-garbage.xml" />
       </section>
+      <section xml:id="sec-nix-hash">
+        <title>nix-hash</title>
+        <xi:include href="nix-hash.xml" />
+      </section>
       <section xml:id="sec-nix-install-package">
         <title>nix-install-package</title>
         <xi:include href="nix-install-package.xml" />
diff --git a/doc/manual/nix-hash.xml b/doc/manual/nix-hash.xml
new file mode 100644
index 0000000000..3a28fe4c6b
--- /dev/null
+++ b/doc/manual/nix-hash.xml
@@ -0,0 +1,153 @@
+<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
+<command>nix-store</command> <option>--dump</option>.  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>
diff --git a/doc/manual/nix-install-package.xml b/doc/manual/nix-install-package.xml
index b696fa03fc..5e4f03d734 100644
--- a/doc/manual/nix-install-package.xml
+++ b/doc/manual/nix-install-package.xml
@@ -86,11 +86,8 @@ to restart itself with <command>xterm</command>,
 </refsection>
 
 
-
 <refsection><title>Examples</title>
 
-<para></para>
-
 <para>To install <filename>subversion-1.4.0.nixpkg</filename> into the
 user’s current profile, without any prompting:
 
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index b8ee297242..41257e3ded 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -670,8 +670,11 @@ in Nix itself.</para>
 
 </refsection>
             
+
 </refsection>
 
 
+<!-- TODO: dump / restore -->
+
 
 </refentry>