How to use git-buildpackage
General information about how gbp works
git-buildpackage works around two main branches:
"upstream" is the branch where upstream files are tracked. Commits here are done only when the package get a new upstream version. Each new version is tagged by gbp as "upstream/<version>"
"master" is the branch where you work on debian/. At each new upstream version, gbp merges the correspondin tag into master. When a commit is ready for the upload and you dput it, gbp tags it as "debian/<version>"
In addition to this, gbp has support for pristine-tar (a nice feature to recreate tarballs identical to upstream ones). Using the --pristine-tar option, a new branch called "pristine-tar" is added, containing some delta files used to recreate the tarball. git-import-dsc or git-import-orig. You probably want to enable this option in your gbp.conf
In the team we want commits about one thing only. If you change several things, please put each of them in a separate commit, with its own descriptive message.
gbp configuration files
gbp has a system-wide configuration file in /etc/git-buildpackage/gbp.conf. Users can override it via ~/.gbp.conf.
Further, per-package configuration is available through debian/gbp.conf. Similarly, .git/gbp.conf is used as a per-repo configuration file.
Common tasks
For some common tasks, a list of procedures is given here. For the procedures, follow the links to the sections below.
- Create a new package from a source tarball
- Adopt an existing package into the team
- Work on a team maintained package
- Uploading a package to Debian (as DD, DM or sponsor)
- Having a package uploaded by an external sponsor
(Request a sponsor, for example at http://mentors.debian.net.)
- Update a package to a new upstream version
Basic procedures
Starting a Debian package from scratch
Create a working directory and initialize a git repo in it:
- mkdir foo-0.1
- cd foo-0.1
- git init
Then import the upstream tarball and launch dh-make to deploy the usual debian/ boilerplate:
- gbp import-orig --pristine-tar -u 0.1 ../foo-0.1.tar.gz
dh_make <options>
Now you have a gbp repository with two or three branches (master, upstream and pristine-tar if you enabled --pristine-tar), and you can start working as usual.
Importing an existing package
- git-import-dsc /path/to/foo_0.1-1.dsc
In details, this command will:
- Create foo/ and cd into it
- Import the upstream files into the upstream branch
- Tag the commit as upstream/0.1 where 0.1
- Import the debian/ directory into master
- Merge upstream into master
- Tag the commit as debian/0.1-1
Once done, you can start working as usual.
Creating a repository on Salsa
- Log in to Salsa and create a new project in the Debian 3D Printing Team.
git remote add origin git@salsa.debian.org:3dprinting-team/<packagename>.git
- git push origin master upstream pristine-tar --tags
Checking out a repository
git clone git@salsa.debian.org:3dprinting-team/<packagename>.git
Building a package
gbp <options>
Options are passed on to debuild, but you can easily configure it to use something else, or to integrate it with good stuff like pbuilder or cowbuilder. Please refer to the manual for more information
Creating patches
Create patches normally using quilt or dpkg-source. Make sure you add a good description to each patch.
Pushing into the repository
Both the master and upstream branch are stored on Salsa. However, the upstream branch doesn't change except when a new upstream version is imported, so at other times you don't need to worry about it.
Finalizing a package
- dch -r
If you need to be sponsored, build a source package and dput it to http:// mentors.debian.net, otherwise move on to the next section.
Uploading a package
dput <package>.changes
- gbp tag
- dch -i
Updating a package to a new upstream version
If you have a watch file, just tell gbp:
- git-import-orig --uscan
Otherwise, pass it the upstream tarball:
- git-import-orig /path/to/upstream.tar.gz -u 0.2