Q: What is dgit?
A bidirectional gateway between the Debian archive (of source packages, in particular) 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 (with the exception of workflows which commit only debian/, and not the upstream source, into git). See dgit-maint-gbp(7) and dgit-maint-dpm(7).
Q: Okay, how do I get started?
Most of our documentation is in the form of manpages. Start with dgit(1), which will direct you to more specific manpages.
Q: How can I try out dgit without making my mistakes 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 "email@example.com: Permission denied (publickey)." error when trying to use dgit push/dgit push-source. What should I do?
Please e-mail Ian mailto:firstname.lastname@example.org requesting access with your SSH public key attached.