summaryrefslogtreecommitdiff
path: root/dgit-maint-gbp.7.pod
diff options
context:
space:
mode:
authorSean Whitton <spwhitton@spwhitton.name>2016-10-29 08:32:37 -0700
committerIan Jackson <ijackson@chiark.greenend.org.uk>2016-10-30 17:27:52 +0000
commitd2b944ee3787199f1e3c74794877cc92a2309475 (patch)
tree2f8d3aad828ae7c5bddff3299a4e1092c702eed7 /dgit-maint-gbp.7.pod
parentdedbcd47ea209e4ba1988b1621b81491d214756d (diff)
dgit-maint-gbp(7): New manpage
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
Diffstat (limited to 'dgit-maint-gbp.7.pod')
-rw-r--r--dgit-maint-gbp.7.pod131
1 files changed, 131 insertions, 0 deletions
diff --git a/dgit-maint-gbp.7.pod b/dgit-maint-gbp.7.pod
new file mode 100644
index 0000000..09cca22
--- /dev/null
+++ b/dgit-maint-gbp.7.pod
@@ -0,0 +1,131 @@
+=head1 NAME
+
+dgit - tutorial for package maintainers already using git-buildpackage(1)
+
+=head1 INTRODUCTION
+
+This document explains how B<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 B<dgit> into your existing workflow:
+
+=over 4
+
+=item
+
+Benefit from dgit's safety catches. In particular, ensure that your
+upload always matches exactly your git HEAD.
+
+=item
+
+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)).
+
+=item
+
+Incorporate NMUs with a single command (see below).
+
+=back
+
+=head1 GIT CONFIGURATION
+
+If you run
+
+=over 4
+
+ % git config dgit.default.quilt-mode gbp
+
+=back
+
+in your repository, you can omit I<--gbp> wherever it occurs below.
+
+Note that this does require that you always work from your gbp master
+branch, never the dgit patches-applied branch.
+
+=head1 BUILDING
+
+If you use gbp-buildpackage(1) to generate your orig tarballs, you
+will need to perform the first build with gbp-buildpackage(1) directly
+(this is due to Debian bug #841084).
+
+Otherwise, you can perform builds like this:
+
+=over 4
+
+ % dgit [--allow-dirty] gbp-build [OPTIONS]
+
+=back
+
+where I<--allow-dirty> is needed for testing uncommitted changes, and
+I<OPTIONS> are any further options to be passed on to
+gbp-buildpackage(1).
+
+When you are ready to build for upload, you will probably want to use
+sbuild(1) or pbuilder(1), or do a source-only upload. Either
+
+=over 4
+
+ % dgit --rm-old-changes --gbp sbuild
+
+=back
+
+or
+
+=over 4
+
+ % dgit --rm-old-changes gbp-build --git-pbuilder
+
+=back
+
+or
+
+=over 4
+
+ % dgit --rm-old-changes --gbp build-source
+
+=back
+
+We use I<--rm-old-changes> to ensure that there is exactly one changes
+file corresponding to this package, so we can be confident we're
+uploading what we intend (though B<dgit push> will do some safety
+checks).
+
+Note that all of the commands in this section are not required to
+upload with dgit. You can invoke gbp-buildpackage(1), pbuilder(1) and
+sbuild(1) directly. However, the defaults for these tools may leave
+you with something that dgit will refuse to upload because it doesn't
+match your git HEAD. As a general rule, leave all signing and tagging
+to dgit.
+
+=head1 UPLOADING
+
+Don't use I<--git-tag>: B<dgit push> will do this for you. To upload:
+
+=over 4
+
+ % dgit --gbp push
+
+=back
+
+This will push your git history to the dgit-repos, but you probably
+want to follow it up with a push to alioth.
+
+=head1 INCORPORATING NMUS
+
+=over 4
+
+ % dgit --gbp pull
+
+=back
+
+Alternatively, you can apply the NMU diff to your repository. The
+next push will then require I<--overwrite>.
+
+=head1 SEE ALSO
+
+dgit(1), dgit(7)
+
+=head1 AUTHOR
+
+This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.