PRISTINE-TAR(1)
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
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 alongside 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) and pristine-bz2(1) to produce the pristine gzip and
bzip2 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 pristinetar checkout command can later be used to recreate the original tarball based only on the information stored in version control.
- For pristine-tar checkout to work, you also need to store the
precise contents of the tarball in version control. To specify in
which tag (or branch or other treeish object) it's stored, use the upstream parameter. 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 pristinetar checkout. - 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.
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, and bzip2ed 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.