Added an example. Closes: #561016

diff --git a/debian/changelog b/debian/changelog
index 672c0b908ec526f0b0a74c9f811eee57c72b4f6e..3826efd3bbfa2821737e21ed6b75eef519a0df3c 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -2,6 +2,7 @@ pristine-tar (1.01) UNRELEASED; urgency=low
 
   * Use italics in man pages to highlight which parts of command
     lines are file names. Closes: #561015
+  * Added an example. Closes: #561016
 
  -- Joey Hess <joeyh@debian.org>  Mon, 14 Dec 2009 14:07:44 -0500
 

diff --git a/pristine-tar b/pristine-tar
index 2a970901c642ee35b895707e82fd9b51059f188c..1b858f50492d8c4821f1475f15c3429dfdf0c9d9 100755 (executable)
--- a/pristine-tar
+++ b/pristine-tar
@@ -103,6 +103,38 @@ Use this option to specify a custom commit message to pristine-tar commit.
 
 =back
 
+=head1 EXAMPLES
+
+Suppose you maintain the hello package, in a git repository. You have
+just created a tarball of the release, I<hello-1.0.tar.gz>, which you
+will upload to a "forge" site.
+
+You want to ensure that, if the "forge" loses the tarball, you can always
+recreate exactly that same tarball. And you'd prefer not to keep copies 
+of tarballs for every release, as that could use a lot of disk space
+when hello gets the background mp3s and user-contributed levels you
+are planning for version 2.0.
+
+The solution is to use pristine-tar to commit a delta file that efficiently
+stores enough information to reproduce the tarball later.
+
+       cd hello
+       git tag -s 1.0
+       pristine-tar commit ../hello-1.0.tar.gz 1.0
+
+Remember to tell git to push both the pristine-tar branch, and your tag:
+
+       git push --all --tags
+
+Now it is a year later. The worst has come to pass; the "forge" lost
+all its data, you deleted the tarballs to make room for bug report emails,
+and you want to regenerate them. Happily, the git repository is still
+available.
+
+       git clone git://github.com/joeyh/hello.git
+       cd hello
+       pristine-tar checkout ../hello-1.0.tar.gz
+
 =head1 LIMITATIONS
 
 Only tarballs, gzipped tarballs, and bzip2ed tarballs are currently