From: Joey Hess <joey@gnu.kitenet.net>
Date: Mon, 14 Dec 2009 19:42:49 +0000 (-0500)
Subject: Added an example. Closes: #561016
X-Git-Tag: 1.01~5
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=27ef1692e9f97d33b8ed89cee98cd5005d00dbd8;p=tools%2Fpristine-tar.git

Added an example. Closes: #561016
---

diff --git a/debian/changelog b/debian/changelog
index 672c0b9..3826efd 100644
--- 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 2a97090..1b858f5 100755
--- 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