For further reading, visit the FAQs page


Hi Pirate ‍ Praveen . I'm curious, what is the meaning and function of the --pristine-tar flag in these commands: (1) gbp clone --pristine-tar (2) gbp import-orig --pristine-tar ../node-color-3.1.3.tar.gz

Pirate Praven
Good question. Debian packages are built from tarballs (tar.gz, tar.bz2 or tar.xz) files. But during development people need to collaborate and need to use a version control system like git. So we extract the tarballs and create a branch 'upstream' with files inside these tarballs.
Then we create master branch from upstream and add debian directory in it (which is extracted from debian.tar when a git repo is created).
So gbp import-orig or gbp import-dsc (for the very first time) helps in creating these branches.
Now we can collaborate on the package using git. So when we are ready to upload the package, we will recreate the orig.tar and debian.tar and .dsc from the git repo.
Suppose I uploaded these generated tar.gz to debian. Now someone else want to modify the package, they will clone the git repo, make changes and generate tar.gz files from the repo and upload.
Now we have a problem, the tar.gz generated from the repo is usually not bit by bit identical to the tarballs used during gbp import. So md5 or sha1 checksums will not match even though the contents inside these tarballs are same.
Debian's archive software (dak) will reject the new upload saying the file you uploaded is different from the file already in the archive. I think this is caused by how text files are stored internally in different architectures or something, I don't know the exact reason.

So to solve this problem we have two options and different teams use different options

pristine-tar is one option.

Downloading the tar file from debian archive instead of generating locally is another option.

js and ruby teams (most other teams too) uses pristine-tar option. golang team uses downloading from debian archive option. With pristine-tar option, a branch pristine-tar is created that has additional information required to generate bit by bit identical and checksum matching tarballs from the git repo.So people can use gbp export-orig --pristine-tar to regenerate the exact same tarballs used to import it.

Hope this is clear now ?

Git source format proposition

And as a proper fix, people are proposing a git based source format, but it is not accepted yet. Hopefully git and debian packaging together will become easier in the future. this still being developed and tested. In golang team they use upstream master branch directly as upstream branch in debian. So they don't use upstream tarballs. They generate a tarball from upstream tag and then use apt source command to download the tarball if it is already uplpaded. gnome team uses upstream git with pristine-tar branch. So each team has its own git workflow. Some teams just keep the debian folder in git. origtargz command will work with all these different workflows.

origtargz will try pristine-tar checkout if there is a pristine-tar branch, if no pristine-tar branch, it will try apt source, if that does not work then it will try uscan. And in case the repo has multiple orig tars imported by gbp then origtargz will fail but gbp export-orig --pristine-tar will work. Also if you forgot to give --pristine-tar option during import then you can use pristine-tar commit later. These are mostly subjective choices of people like what editor they use or what distro they use. So you will see all kinds of permutations and combinations.

There used to be other VCS too earlier but it seems git won the battle and almost all packages now use git.

You don't need to worry about all these options right now, just shared for information only.

And using a VCS itself is optional in Debian. So you will see some packages without a git repo as well.

Only mandatory thing is one or more source tars and a .dsc file.

So apt source is the basic command that will get you the source of any package, irrespective of the workflow they use for development.

For js-team, it is gbp clone --pristine-tar and gbp export-orig --pristine-tar. These two commands should be enough to build any package from git repo.

So if you don't want to learn any of these and still contribute, then apt source, modify, build and create a debdiff and send as patch to

Debian Packaging | Debian Javascript Packaging