.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PRISTINE-TAR 1"
.TH PRISTINE-TAR 1 "2019-01-23" "perl v5.28.1" "pristine-tar"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
pristine\-tar \- regenerate pristine tarballs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBpristine-tar\fR [\s-1OPTIONS\s0] gendelta \fItarball\fR \fIdelta\fR
.PP
\&\fBpristine-tar\fR [\s-1OPTIONS\s0] gentar \fIdelta\fR \fItarball\fR
.PP
\&\fBpristine-tar\fR [\s-1OPTIONS\s0] commit \fItarball\fR [\fIupstream\fR]
.PP
\&\fBpristine-tar\fR [\s-1OPTIONS\s0] checkout \fItarball\fR
.PP
\&\fBpristine-tar\fR [\s-1OPTIONS\s0] list
.PP
\&\fBpristine-tar\fR [\s-1OPTIONS\s0] verify \fItarball\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
pristine-tar can regenerate an exact copy of a pristine upstream tarball
using only a small binary \fIdelta\fR file and the contents of the tarball,
which are typically kept in an \fIupstream\fR branch in version control.
.PP
The \fIdelta\fR file is designed to be checked into version control along-side
the \fIupstream\fR branch, thus allowing Debian packages to be built entirely
using sources in version control, without the need to keep copies of
upstream tarballs.
.PP
pristine-tar supports compressed tarballs, calling out to \fBpristine\-gz\fR\|(1),
\&\fBpristine\-bz2\fR\|(1), and \fBpristine\-xz\fR\|(1) to produce the pristine gzip, bzip2,
and xz files.
.SH "COMMANDS"
.IX Header "COMMANDS"
.SS "pristine-tar gendelta \fItarball\fP \fIdelta\fP"
.IX Subsection "pristine-tar gendelta tarball delta"
This takes the specified upstream \fItarball\fR, and generates a small binary
delta file that can later be used by pristine-tar gentar to recreate the
tarball.
.PP
If the delta filename is \*(L"\-\*(R", it is written to standard output.
.SS "pristine-tar gentar \fIdelta\fP \fItarball\fP"
.IX Subsection "pristine-tar gentar delta tarball"
This takes the specified \fIdelta\fR 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 \fItarball\fR.
.PP
If the delta filename is \*(L"\-\*(R", it is read from standard input.
.SS "pristine-tar commit \fItarball\fP [\fIupstream\fP]"
.IX Subsection "pristine-tar commit tarball [upstream]"
\&\fBpristine-tar commit\fR generates a pristine-tar delta file for the specified
\&\fItarball\fR, and commits it to version control. The \fBpristine-tar checkout\fR
command can later be used to recreate the original tarball based only
on the information stored in version control.
.PP
The \fIupstream\fR parameter specifies the tag or branch that contains the
same content that is present in the tarball. This defaults to
\&\*(L"refs/heads/upstream\*(R", or if there's no such branch, any
branch matching \*(L"upstream\*(R". The name of the tree it points to will be
recorded for later use by \fBpristine-tar checkout\fR. 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.
.PP
The delta files are stored in a branch named \*(L"pristine-tar\*(R", with filenames
corresponding to the input tarball, with \*(L".delta\*(R" appended. This
branch is created or updated as needed to add each new delta.
.PP
If \fItarball\fR already exists previously, it will only be overwritten if it does
not match a hash of the tarball that has been committed to version control.
.SS "pristine-tar checkout \fItarball\fP"
.IX Subsection "pristine-tar checkout tarball"
This regenerates a copy of the specified \fItarball\fR using information
previously saved in version control by \fBpristine-tar commit\fR.
.SS "pristine-tar list"
.IX Subsection "pristine-tar list"
This lists tarballs that pristine-tar is able to checkout from version
control.
.SS "pristine-tar verify \fItarball\fP"
.IX Subsection "pristine-tar verify tarball"
Verifies whether an existing \fItarball\fR matches the one that has been committed
to version control.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\-v" 4
.IX Item "-v"
.PD 0
.IP "\-\-verbose" 4
.IX Item "--verbose"
.PD
Verbose mode, show each command that is run.
.IP "\-d" 4
.IX Item "-d"
.PD 0
.IP "\-\-debug" 4
.IX Item "--debug"
.PD
Debug mode.
.IP "\-k" 4
.IX Item "-k"
.PD 0
.IP "\-\-keep" 4
.IX Item "--keep"
.PD
Don't clean up the temporary directory on exit.
.IP "\-m message" 4
.IX Item "-m message"
.PD 0
.IP "\-\-message=message" 4
.IX Item "--message=message"
.PD
Use this option to specify a custom commit message to pristine-tar commit.
.Sp
Applies to the \fBcommit\fR command.
.IP "\-s signaturefile" 4
.IX Item "-s signaturefile"
.PD 0
.IP "\-\-signature\-file=signaturefile" 4
.IX Item "--signature-file=signaturefile"
.PD
Use this option to optionally commit or checkout an upstream signature
file for the tarball. Note that extraction of signatures is not
performed by default.
.Sp
Applies to the \fBcommit\fR and \fBcheckout\fR commands.
.IP "\-r" 4
.IX Item "-r"
.PD 0
.IP "\-\-recompress" 4
.IX Item "--recompress"
.PD
Use this option to tell pristine-tar that it is \s-1OK\s0 to recompress the tarball if
1) the tarball can't be regenerated or 2) the delta file produced from the
original tarball is larger than a given threshold (see also
\&\fI\-B\fR/\fI\-\-recompress\-threshold\-bytes\fR and
\&\fI\-T\fR/\fI\-\-recompress\-threshold\-percent\fR).
.Sp
\&\fBNote that this modifies the original tarball on disk\fR, and you probably
shouldn't use it if you are also storing a upstream \s-1GPG\s0 signature of the
original tarball (see \fI\-\-signature\-file\fR).
.Sp
On the other hand, the actual contents of the tarball stored by pristine-tar
\&\fBwill\fR be identical to the content of the upstream original tarbal even if
the compressed tarball itself won't be bit-by-bit identical to the one released
by upstream.
.Sp
A copy of the original tarball will be saved with \*(L".backup\*(R" added to its
filename.
.Sp
Applies to the \fBcommit\fR and \fBgendelta\fR commands.
.IP "\-B N" 4
.IX Item "-B N"
.PD 0
.IP "\-\-recompress\-threshold\-bytes=N" 4
.IX Item "--recompress-threshold-bytes=N"
.PD
Recompress original tarball if the generated delta is larger then \fIN\fR bytes.
Default: 524288000 (500 kB).
.Sp
If this option is passed explicitly in the command line, it implies
\&\fI\-\-recompress\fR.
.Sp
Applies to the \fBcommit\fR and \fBgendelta\fR commands.
.IP "\-P N" 4
.IX Item "-P N"
.PD 0
.IP "\-\-recompress\-threshold\-percent=N" 4
.IX Item "--recompress-threshold-percent=N"
.PD
Recompress original tarball if the generated delta is larger than \fIN\fR% of the
size of the original tarball. Default: 30.
.Sp
If this option is passed explicitly in the command line, it implies
\&\fI\-\-recompress\fR.
.Sp
Applies to the \fBcommit\fR and \fBgendelta\fR commands.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Suppose you maintain the hello package, in a git repository. You have
just created a tarball of the release, \fIhello\-1.0.tar.gz\fR, which you
will upload to a \*(L"forge\*(R" site.
.PP
You want to ensure that, if the \*(L"forge\*(R" 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.
.PP
The solution is to use pristine-tar to commit a delta file that efficiently
stores enough information to reproduce the tarball later.
.PP
.Vb 3
\&    cd hello
\&    git tag \-s 1.0
\&    pristine\-tar commit ../hello\-1.0.tar.gz 1.0
.Ve
.PP
Remember to tell git to push both the pristine-tar branch, and your tag:
.PP
.Vb 1
\&    git push \-\-all \-\-tags
.Ve
.PP
Now it is a year later. The worst has come to pass; the \*(L"forge\*(R" 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.
.PP
.Vb 3
\&    git clone git://github.com/joeyh/hello.git
\&    cd hello
\&    pristine\-tar checkout ../hello\-1.0.tar.gz
.Ve
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
Only tarballs, gzipped tarballs, bzip2ed tarballs, and xzed tarballs
are currently supported.
.PP
Currently only the git revision control system is supported by the
\&\*(L"checkout\*(R" and \*(L"commit\*(R" 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 \*(L"checkout\*(R" or \*(L"commit\*(R".
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\fB\s-1TMPDIR\s0\fR" 4
.IX Item "TMPDIR"
Specifies a location to place temporary files, other than the default.
.IP "\fB\s-1PRISTINE_TAR\s0\fR" 4
.IX Item "PRISTINE_TAR"
Defines command line options to be assumed by pristine-tar. Any options passed
explicitly on the command line will override those.
.Sp
Options will be split on whitespaces, so if you want to pass an option that
needs an argument, use the \fI\-\-opt=arg\fR syntax instead of \fI\-\-opt arg\fR.
.IP "\fB\s-1PRISTINE_ALL_XDELTA\s0\fR" 4
.IX Item "PRISTINE_ALL_XDELTA"
Defines the underlying binary delta tool to be used for new deltas. Supported
values are \*(L"xdelta3\*(R" (default) and \*(L"xdelta\*(R".
.Sp
Existing deltas will be handled with the original tool that was used to
create them, regardless of the value of \fB\f(CB$PRISTINE_ALL_XDELTA\fB\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Joey Hess <joeyh@debian.org>
.PP
Licensed under the \s-1GPL,\s0 version 2 or above.