upstream branch and upstream tarball in git-dpm
Often the upstream branch in a git-dpm project will be an imported tar file, sometimes with upstream's history added as parent commit using import-tar's or import-dsc's -p.
But the commit recorded as upstream branch can differ, contrained by the following conditions:
- Every file not in the upstream branch but in the tarball must not be needed for building the package (and not result in a different build).
- Git-dpm checks that no files relative to the patched branch are introduced in the debian branch to avoid common errors. Thus the file would be there when building a directory unpacked with dpkg-source while not in the git repository, so the build would differ which it should not.
- Every file existing in the upstream branch and not in the tarball or different there must be deleted in the debian branch
- Otherwise when building a source package from the debian branch, dpkg-source will see modifications in the current directory relative to the upstream tarball with the patches applied (it ignores deletions, so files not being there or modified files missing in the debian branch are no problem).
- commits in the patched branch may not touch anything that differs between the the upstream tarball and the upstream branch
The patches are generated by git format-patch relative to the upstream branch by git-dpm, while dpkg-source will apply them on top of the upstream tarball.
advantages / disadvantages for non-verbatim upstream branch
Not importing the .orig.tar but using a upstream provided commit as upstream branch directly has the main advantage that you are nearer to upstream. If you want to use some commits made there directly after the release as patches, you do not need to cherry pick them but can just fast forward your branch. Also upstream does not need to cherry-pick your commits, but can just pull them.
But if you want only some of the following commits, you will need to cherry-pick anyway. And as the commits in the patched branch are used to make the patches in debian/patches, you will most likely want to have a different description anyway than what is in upstream's repository, so the advantage will usually be none.
The biggest disadvantages of having a upstream branch that is not exactly like the unpacked source but only similar enough is that it is hard to check everything is correct. Git-dpm has no checks to even check things and the most important things (exististance of files does not change build) are not even decideable by a computer.
Thus just importing the .orig.tar file is recommended unless you have strong reasons or feelings the other way.
examples
The easiest example is an upstream that misses some files in its VCS that are in the tarball but those files are not needed by the build. In this case you can just use that branch as upstream part (the only hard part is being sure those files are really not needed).
Second most easy is a tarball that misses files in the tarball that are in the upstream branch but are not needed for building the package. In this case just delete the files from your debian branch. You will not be able to reintroduce any of those files by a patch. And if your tarball later introduces and needs those files, don't forget to reintroduce the files in the debian branch (Unless you use import-dsc, git-dpm will keep deleted files deleted in the debian branch even when merging in a new patched branch on a new upstream branch).
If the files missing in the upstream tarball are needed for the build (usual examples are Makefile.in or configure), this only works if you regenerate them at build time (in above example by autoreconf). Don't forget to delete all the files generated by that in debian/rules clean, though.