chiark / gitweb /
git-debrebase: Provide convert-from-unapplied aa alias for -gbp
[dgit.git] / dgit-maint-gbp.7.pod
index 53d147a..b8abd66 100644 (file)
@@ -22,10 +22,6 @@ 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)).
 
 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
 
 Note that we assume a patches-unapplied repository: the upstream
 =back
 
 Note that we assume a patches-unapplied repository: the upstream
@@ -35,6 +31,15 @@ normally used with patches-unapplied.
 
 =head1 GIT CONFIGURATION
 
 
 =head1 GIT CONFIGURATION
 
+If you have configured an I<export-dir> in your gbp.conf, you should
+tell dgit about it:
+
+=over 4
+
+    % git config --global dgit.default.build-products-dir /home/spwhitton/build-area
+
+=back
+
 If you run
 
 =over 4
 If you run
 
 =over 4
@@ -50,24 +55,24 @@ branch, never the dgit patches-applied branch.
 
 =head1 BUILDING
 
 
 =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:
+You can perform test builds like this:
 
 =over 4
 
 
 =over 4
 
-    % dgit [--allow-dirty] gbp-build [OPTIONS]
+    % dgit [--include-dirty] gbp-build [OPTIONS]
 
 =back
 
 
 =back
 
-where I<--allow-dirty> is needed for testing uncommitted changes, and
+where I<--include-dirty> is needed for testing uncommitted changes, and
 I<OPTIONS> are any further options to be passed on to
 gbp-buildpackage(1).
 
 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
+If you are doing a source-only upload, you do not need to prepare a
+I<_source.changes>, as B<dgit push-source> will take of that on your
+behalf.
+
+If you need to include binaries with your upload, you will probably
+want to use sbuild(1), pbuilder(1) or cowbuilder(1):
 
 =over 4
 
 
 =over 4
 
@@ -75,37 +80,33 @@ sbuild(1) or pbuilder(1), or do a source-only upload.  Either
 
 =back
 
 
 =back
 
-or
+replacing 'sbuild' with 'pbuilder' or 'cowbuilder' if appropriate.
 
 
-=over 4
+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).
 
 
-    % dgit --rm-old-changes gbp-build --git-pbuilder
+Note that none of the commands in this section are required to upload
+with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1),
+cowbuilder(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.
 
 
-=back
+As a general rule, leave all signing and tagging to dgit.
 
 
-or
+=head1 UPLOADING
+
+Don't use I<--git-tag>: B<dgit push> will do this for you.  To do a
+source-only upload:
 
 =over 4
 
 
 =over 4
 
-    % dgit --rm-old-changes --gbp build-source
+    % dgit --gbp push-source
 
 =back
 
 
 =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:
+or if you need to include binaries,
 
 =over 4
 
 
 =over 4
 
@@ -114,21 +115,23 @@ Don't use I<--git-tag>: B<dgit push> will do this for you.  To upload:
 =back
 
 This will push your git history to the dgit-repos, but you probably
 =back
 
 This will push your git history to the dgit-repos, but you probably
-want to follow it up with a push to alioth.
+want to follow it up with a push to salsa.
 
 You will need to pass I<--overwrite> if the previous upload was not
 performed with dgit.
 
 
 You will need to pass I<--overwrite> if the previous upload was not
 performed with dgit.
 
-=head1 INCORPORATING NMUS
-
-=over 4
-
-    % dgit --gbp pull
+If this is first ever dgit push of the package, consider passing
+I<--deliberately-not-fast-forward> instead of I<--overwrite>.  This
+avoids introducing a new origin commit into the dgit view of your git
+history.  (This origin commit would represent the most recent non-dgit
+upload of the package, but this should already be represented in your
+git history.)
 
 
-=back
+=head1 INCORPORATING NMUS
 
 
-Alternatively, you can apply the NMU diff to your repository.  The
-next push will then require I<--overwrite>.
+B<dgit pull> can't yet incorporate NMUs into patches-unapplied gbp
+branches.  You can just apply the NMU diff the traditional way.  The
+next upload will require I<--overwrite>.
 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO