Provided by: pristine-tar_1.33_amd64 
NAME
pristine-tar - regenerate pristine tarballs
SYNOPSIS
pristine-tar [-vdk] gendelta tarball delta
pristine-tar [-vdk] gentar delta tarball
pristine-tar [-vdk] [-m message] commit tarball [upstream]
pristine-tar [-vdk] checkout tarball
pristine-tar [-vdk] list
DESCRIPTION
pristine-tar can regenerate an exact copy of a pristine upstream tarball using only a small binary delta
file and the contents of the tarball, which are typically kept in an upstream branch in version control.
The delta file is designed to be checked into version control along-side the upstream branch, thus
allowing Debian packages to be built entirely using sources in version control, without the need to keep
copies of upstream tarballs.
pristine-tar supports compressed tarballs, calling out to pristine-gz(1), pristine-bz2(1), and
pristine-xz(1) to produce the pristine gzip, bzip2, and xz files.
COMMANDS
pristine-tar gendelta tarball delta
This takes the specified upstream tarball, and generates a small binary delta file that can later be
used by pristine-tar gentar to recreate the tarball.
If the delta filename is "-", it is written to standard output.
pristine-tar gentar delta tarball
This takes the specified delta file, and the files in the current directory, which must have
identical content to those in the upstream tarball, and uses these to regenerate the pristine
upstream tarball.
If the delta filename is "-", it is read from standard input.
pristine-tar commit tarball [upstream]
pristine-tar commit generates a pristine-tar delta file for the specified tarball, and commits it to
version control. The pristine-tar checkout command can later be used to recreate the original tarball
based only on the information stored in version control.
The upstream parameter specifies the tag or branch that contains the same content that is present in
the tarball. This defaults to "refs/heads/upstream", or if there's no such branch, any branch
matching "upstream". The name of the tree it points to will be recorded for later use by pristine-tar
checkout. Note that the content does not need to be 100% identical to the content of the tarball, but
if it is not, additional space will be used in the delta file.
The delta files are stored in a branch named "pristine-tar", with filenames corresponding to the
input tarball, with ".delta" appended. This branch is created or updated as needed to add each new
delta.
pristine-tar checkout tarball
This regenerates a copy of the specified tarball using information previously saved in version
control by pristine-tar commit.
pristine-tar list
This lists tarballs that pristine-tar is able to checkout from version control.
OPTIONS
-v
--verbose
Verbose mode, show each command that is run.
-d
--debug
Debug mode.
-k
--keep
Don't clean up the temporary directory on exit.
-m message
--message=message
Use this option to specify a custom commit message to pristine-tar commit.
EXAMPLES
Suppose you maintain the hello package, in a git repository. You have just created a tarball of the
release, 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
LIMITATIONS
Only tarballs, gzipped tarballs, bzip2ed tarballs, and xzed tarballs are currently supported.
Currently only the git revision control system is supported by the "checkout" and "commit" commands. It's
ok if the working copy is not clean or has uncommitted changes, or has changes staged in the index; none
of that will be touched by "checkout" or "commit".
ENVIRONMENT
TMPDIR
Specifies a location to place temporary files, other than the default.
AUTHOR
Joey Hess <joeyh@debian.org> Licensed under the GPL, version 2 or above.