dgit workflow

TOC

For Debian maintainer, there can be 4 approaches for maintaining git repository with dgit. Let me get all key points of manpages.

Here, the maintainer column indicates relationship of the maintainer to the upstream development.

Let’s copy key parts of manpages.

dgit-maint-native(7)

This document describes elements of a workflow for using dgit to maintain a Debian package that uses one of the native source formats (“1.0” & “3.0 (native)”).

• We expect that your git history is fast-forwarding.
• You should be prepared to tolerate a small amount of ugliness in your git history in the form of merges which stitch the dgit- generated archive view into your maintainer history.
  • This is to handle uploads that were not made with dgit, such as the uploads you made before switching to this workflow, or NMUs.

Benefits

• Benefit from dgit’s safety catches. In particular, ensure that your upload always matches exactly your git HEAD.
• Provide a better, more detailed history to downstream dgit users.
• Incorporate an NMU with one command.

dgit-maint-merge(7)

This document describes elements of a workflow for maintaining a non- native Debian package using dgit. The workflow makes the following opinionated assumptions:

• Git histories should be the non-linear histories produced by git-merge(1), preserving all information about divergent development that was later brought together.
• Maintaining convenient and powerful git workflows takes priority over the usefulness of the raw Debian source package. The Debian archive is thought of as an output format.
  • For example, we don’t spend time curating a series of quilt patches. However, in straightforward cases, the information such a series would contain is readily available from dgit-repos.
• It is more important to have the Debian package’s git history be a descendent of upstream’s git history than to use exactly the orig.tar that upstream makes available for download.

This workflow is less suitable for some packages. When the Debian delta contains multiple pieces which interact, or which you aren’t going to be able to upstream soon, it might be preferable to maintain the delta as a rebasing patch series. For such a workflow see for example dgit-maint-debrebase(7) and dgit-maint-gbp(7).

dgit-maint-debrebase(7)

This document describes elements of a workflow for maintaining a non- native Debian package using dgit. We maintain the Debian delta as a series of git commits on our master branch. We use git-debrebase(1) to shuffle our branch such that this series of git commits appears at the end of the branch. All the public git history is fast-forwarding, i.e., we do not rewrite and force-push.

Some advantages of this workflow:

• Manipulate the delta queue using the full power of git-rebase(1), instead of relying on quilt(1), and without having to switch back and forth between patches-applied and patches-unapplied branches when committing changes and trying to build, as with gbp-pq(1).
• If you are using 3.0 (quilt), provide your delta queue as a properly separated series of quilt patches in the source package that you upload to the archive (unlike with dgit-maint-merge(7)).
• Avoid the git tree being dirtied by the application or unapplication of patches, as they are always applied.
• Benefit from dgit’s safety catches. In particular, ensure that your upload always matches exactly your git HEAD.
• Provide your full git history in a standard format on dgit-repos, where it can benefit downstream dgit users, such as people using dgit to do an NMU (see dgit-nmu-simple(7) and dgit-user(7)).
• Minimise the amount you need to know about 3.0 (quilt) in order to maintain Debian source packages which use that format.

This workflow is appropriate for packages where the Debian delta contains multiple pieces which interact, or which you don’t expect to be able to upstream soon. For packages with simple and/or short-lived Debian deltas, use of git-debrebase(1) introduces unneeded complexity. For such packages, consider the workflow described in dgit-maint-merge(7).

dgit-maint-gbp(7)

This document explains how dgit can be incorporated into a git-buildpackage(1) package-maintenance workflow. This should be read jointly with git-buildpackage(1)’s documentation. Some reasons why you might want to incorporate dgit into your existing workflow:

• Benefit from dgit’s safety catches. In particular, ensure that your upload always matches exactly your git HEAD.
• Provide a better, more detailed git history to downstream dgit users, such as people using dgit to do an NMU (see dgit-nmu-simple(7) and dgit-user(7)).

Note that we assume a patches-unapplied repository: the upstream source committed to the git repository is unpatched. git-buildpackage(1) can work with patched-applied repositories, but is normally used with patches-unapplied.

gbp-import-orig usage with dgit

Let me compare gbp-import-orig usage for each dgit strategy.