From d2b944ee3787199f1e3c74794877cc92a2309475 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Sat, 29 Oct 2016 08:32:37 -0700
Subject: [PATCH] dgit-maint-gbp(7): New manpage

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
---
 Makefile             |   2 +-
 dgit-maint-gbp.7.pod | 131 +++++++++++++++++++++++++++++++++++++++++++
 dgit.1               |   1 +
 3 files changed, 133 insertions(+), 1 deletion(-)
 create mode 100644 dgit-maint-gbp.7.pod

diff --git a/Makefile b/Makefile
index 9491e4dc..4e51b5b0 100644
--- a/Makefile
+++ b/Makefile
@@ -34,7 +34,7 @@ absurddir=$(prefix)/share/dgit/absurd
 
 PROGRAMS=dgit
 MAN1PAGES=dgit.1
-MAN7PAGES=dgit.7 dgit-maint-merge.7
+MAN7PAGES=dgit.7 dgit-maint-merge.7 dgit-maint-gbp.7
 TXTDOCS=README.dsc-import
 PERLMODULES=Debian/Dgit.pm
 ABSURDITIES=git
diff --git a/dgit-maint-gbp.7.pod b/dgit-maint-gbp.7.pod
new file mode 100644
index 00000000..09cca22b
--- /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>.
diff --git a/dgit.1 b/dgit.1
index cc10695a..af23a5f3 100644
--- a/dgit.1
+++ b/dgit.1
@@ -999,6 +999,7 @@ non-dry-run dgit fetch first will help.
 .SH SEE ALSO
 \fBdgit\fP(7),
 \fBdgit-maint-merge\fP(7),
+\fBdgit-maint-gbp\fP(7),
 \fBcurl\fP(1),
 \fBdput\fP(1),
 \fBdebsign\fP(1),
-- 
2.30.2