X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=dgit-maint-gbp.7.pod;fp=dgit-maint-gbp.7.pod;h=09cca22b674ec769ec9da9189e570cc47ed8d828;hb=d2b944ee3787199f1e3c74794877cc92a2309475;hp=0000000000000000000000000000000000000000;hpb=dedbcd47ea209e4ba1988b1621b81491d214756d;p=dgit.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>.