PRISTINE-TAR(1)

💖 PRISTINE-TAR 💖

okay bestie, welcome to pristine-tar, part of the pristine-tar manual (section 1, for the record). sit down, grab a strawberry 🍓, because this little icon is about to save your entire git repo's life.

---

✨ NAME ✨

pristine-tar — regenerate pristine tarballs. no cap. that's literally the whole job and it does it flawlessly.

---

🌸 SYNOPSIS 🌸

pristine-tar [OPTIONS] gendelta tarball delta

pristine-tar [OPTIONS] gentar delta tarball

pristine-tar [OPTIONS] commit tarball [upstream]

pristine-tar [OPTIONS] checkout tarball

pristine-tar [OPTIONS] list

pristine-tar [OPTIONS] verify tarball

---

🦋 DESCRIPTION 🦋

so here's the vibe: pristine-tar can regenerate an exact copy of a pristine upstream tarball using only a small binary delta file plus the contents of the tarball — and those contents are typically chillin' in an upstream branch in version control. 🫶

The delta file is designed to be checked into version control along-side the upstream branch, which means Debian packages can be built entirely using sources in version control, with zero need to hoard copies of upstream tarballs. it's giving minimalism. it's giving disk space freed. ✨

pristine-tar supports compressed tarballs, and it calls out to pristine-gz(1), pristine-bz2(1), and pristine-xz(1) to produce the pristine gzip, bzip2, and xz files. team work makes the dream work 💅

---

👑 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. (yes, stdout, go off ⭐)

🎀 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. it's basically a time capsule bestie 🕰️

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.

If tarball 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. safety first, always 💜

🎀 pristine-tar checkout tarball

This regenerates a copy of the specified tarball using information previously saved in version control by pristine-tar commit. the resurrection arc we deserve 🌈

🎀 pristine-tar list

This lists tarballs that pristine-tar is able to checkout from version control. window shopping, but make it tarballs 🛍️

🎀 pristine-tar verify tarball

Verifies whether an existing tarball matches the one that has been committed to version control. vibe check, but for your tarball ⭐

---

💅 OPTIONS 💅

• -v, --verbose — Verbose mode, show each command that is run. she tells you everything, main character energy.
• -d, --debug — Debug mode. for when you need to know the why 😭
• -k, --keep — Don't clean up the temporary directory on exit. leaving the mess behind on purpose, honestly relatable.
• -m message, --message=message — Use this option to specify a custom commit message to pristine-tar commit.
  • Applies to the commit command.
• -s signaturefile, --signature-file=signaturefile — 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.
  • Applies to the commit and checkout commands.
• -r, --recompress — Use this option to tell pristine-tar that it is OK 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 -B/--recompress-threshold-bytes and -T/--recompress-threshold-percent).

bestie, be careful: this modifies the original tarball on disk, and you probably shouldn't use it if you are also storing a upstream GPG signature of the original tarball (see --signature-file). 😭

On the other hand, the actual contents of the tarball stored by pristine-tar will 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. (yes, the manpage says "tarbal". we're keeping it. character for character, that's the rule 💀)

A copy of the original tarball will be saved with ".backup" added to its filename. your safety net, slay 🫶

• Applies to the commit and gendelta commands.

• -B N, --recompress-threshold-bytes=N — Recompress original tarball if the generated delta is larger then N bytes. Default: 524288000 (500 kB).

If this option is passed explicitly in the command line, it implies --recompress.

• Applies to the commit and gendelta commands.

• -P N, --recompress-threshold-percent=N — Recompress original tarball if the generated delta is larger than N% of the size of the original tarball. Default: 30.

If this option is passed explicitly in the command line, it implies --recompress.

• Applies to the commit and gendelta commands.

---

🧚 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. (yes, background mp3s. we're all very excited for 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

and that's the redemption arc, bestie. iconic. 🎀

---

🙈 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". she's polite, she doesn't touch your stuff 💜

---

🌱 ENVIRONMENT 🌱

• TMPDIR — Specifies a location to place temporary files, other than the default.
• PRISTINE_TAR — Defines command line options to be assumed by pristine-tar. Any options passed explicitly on the command line will override those.

Options will be split on whitespaces, so if you want to pass an option that needs an argument, use the --opt=arg syntax instead of --opt arg. (learn from my mistakes bestie 😭)

• PRISTINE_ALL_XDELTA — Defines the underlying binary delta tool to be used for new deltas. Supported values are "xdelta3" (default) and "xdelta".

Existing deltas will be handled with the original tool that was used to create them, regardless of the value of $PRISTINE_ALL_XDELTA. the past stays in the past ✨

---

⭐ AUTHOR ⭐

Joey Hess <joeyh@debian.org>

Licensed under the GPL, version 2 or above.

---

and that's a wrap! this page was brought to you by perl v5.38.2, dated 2024-04-01. go regenerate something pristine, queen 👑💖