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.