dgit FAQ

Q: What is dgit?

A bidirectional gateway between source packages in the Debian archive and git.

Q: Why should I bother to learn how to use dgit?

If you incorporate dgit push-source into your workflow, then you will be providing your git history to Debian's users and downstreams in a way that is more useful to them than just adding a Vcs-Git header.

If you think that a package maintainer's git history should be provided to users because it is part of the preferred format for modification, then dgit is the easiest way to provide it.

Specifically, if you incorporate dgit push-source into your workflow, you provide your git history to your users in a form known as the dgit view. The dgit view of a package is designed to be what someone who knows git, but does not know Debian-specific practices, would expect.

You don't have to think about difference between the maintainer view and the dgit view (if any), because dgit will perform that conversion for you when you upload. It does this in a way which does not hide the maintainer's git history, i.e., the dgit view is constructed from the maintainer's git history, not from the .dsc. If the maintainer view and the dgit view are not identical, the latter will have some additional commits appended to convert your maintainer history into the dgit view.

There are also minor conveniences for maintainers in using dgit, which together mean that you have to think less about the idiosyncracies of uploading to the Debian archive and more about the contents of your package.

Q: Do I need to change my git workflow in order to use dgit?

In principle, no. It is a design goal of dgit that you don't have to do that.

However, dgit does have to be taught about each Debian git workflow in order that users of that workflow can start using dgit, and there are some git workflows out there for which support has not yet been added.

git-buildpackage and git-dpm users are fully supported and that support is stable and well-tested. See dgit-maint-gbp(7) and dgit-maint-dpm(7).

Q: Okay, how do I get started?

You can pretty much achieve the benefits to users and downstreams described above just by starting to use dgit push-source for your source-only uploads. You do not need to read a lot of documentation to do this -- there isn't really any need to "learn dgit" in the way you had to learn sbuild or pbuilder, for example.

All that's required is to determine whether you need dgit push-source, or dgit --gbp push-source, or one of the other maintainer view options described in dgit(1). (If you are using the patches-unapplied git-buildpackage workflow many packaging teams use, let me save you some time: you want dgit --gbp push-source.)

The only other option you are likely to require is --overwrite. dgit will suggest using this option when it detects that the most recent upload was not made with dgit. The primary purpose of this is to avoid accidentally overwriting someone's NMU. If dgit suggests using --overwrite and you know that your HEAD is indeed what you want to upload, just go ahead and pass --overwrite -- it's not a dangerous option, despite its name.

Uploading to NEW works well but is not quite so straightforward, and will likely require learning more about how dgit works. If you're interested in that, start with dgit(1), which will direct you to more specific manpages for your workflow.

Q: How can I try out dgit without making any mistakes I might make public ?

dgit --damp-run will avoid making any public changes, and avoid signing anything. --dry-run will avoid making any changes at all (but is less faithful).

dgit is quite careful and double checks many things. If you do not pass forcing options, dgit should detect most mistakes, and stop. If dgit is implicated in any embarrassment, please file a bug saying what you did, so we can think how to make dgit spot similar mistakes.

Q: Why is dgit so fussy / Why are dgit's error messages so difficult?

dgit tries very hard to avoid a number of different possible mistakes in your uploads. The result of this is that you have to think less hard about the idiosyncracies of uploading to the Debian archive, and focus more on the contents of your package.

However, while dgit is good at emitting error messages at the right times, the error messages that it emits are sometimes not as helpful and easy to understand as we want them to be. Bug reports are welcome. The dgit developers already know what's going on, so it is difficult for us to univocally improve the error output.

Q: Does everyone on my team have to be using dgit in order for me to use it to upload team-maintained packages?

No. dgit copes just fine with interspersed dgit and non-dgit uploads. Your use of dgit will not disrupt the work of other people on your team.

Q: I am a Debian Maintainer (DM) and I want to use dgit. I get a "dgit@push.dgit.debian.org: Permission denied (publickey)." error when trying to use dgit push/dgit push-source. What should I do?

Your ssh public key needs to be added to the access list. Hopefully you can do this yourself.

The update can be initiated by anyone in the debian group on Salsa. https://salsa.debian.org/dgit-team/extra-push-ssh-keys has instructions (non-public repo since it contains users' ssh keys). DMs should have access to that repo, but if you don't, contact any Debian Project Member (DPM) aka Debian Developer (DD) eg a sponsor or mentor and they should be able to help you. DPMs (aka DDs) do not need to do this because the Debian Project already has a list of DPM ssh public keys, and those are automatically authorised.