1 files changed, 32 insertions, 38 deletions
diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index f25fe57..9e22cd1 100644
@@ -116,23 +116,29 @@ it anywhere (e.g. with tools like pristine-tar(1)).
-It can be a good idea to compare upstream's released tarballs with the
-release tags, at least for the first upload of the package. If they
-are different, you might need to add some additional steps to your
-I<debian/rules>, such as running autotools.
+The above assumes that you know how to build the package from git and
+that doing so is straightforward.
-A convenient way to perform this check is to import the tarball as
-described in the following section, using a different value for
-'upstream-tag', and then use git-diff(1) to compare the imported
-tarball to the release tag. If they are the same, you can use
-upstream's tarball instead of running git-deborig(1).
+If, as a user of the upstream source, you usually build from upstream
+tarball releases, rather than upstream git tags, you will sometimes
+find that the git tree doesn't contain everything that is in the
+Additional build steps may be needed. For example, you may need your
+I<debian/rules> to run autotools.
+You can compare the upstream tarball release, and upstream git tag,
+within git, by importing the tarball into git as described in the
+next section, using a different value for 'upstream-tag', and then
+using git-diff(1) to compare the imported tarball to the release tag.
=head2 When upstream releases only tarballs
-We need a virtual upstream branch with virtual release tags.
-gbp-import-orig(1) can manage this for us. To begin
+Because we want to work in git, we need a virtual upstream branch with
+virtual release tags. gbp-import-orig(1) can manage this for us. To
@@ -198,7 +204,6 @@ the debian/ directory containing at least one file, and does nothing
else.> In other words, make a commit introducing I<debian/> before
patching the upstream source.
=head1 CONVERTING AN EXISTING PACKAGE
This section explains how to convert an existing Debian package to
@@ -236,17 +241,6 @@ corresponding to each of the quilt patches. You can use
-or manually with gbp-pq(1):
- % gbp pq import
- % gbp pq switch
- % git merge --ff-only patch-queue/master
- % gbp pq drop
Then make new upstream tags available:
@@ -255,14 +249,10 @@ Then make new upstream tags available:
-=for dgit-test dpkg-source-ignores begin
Now you simply need to ensure that your git HEAD is dgit-compatible,
-i.e., it is exactly what you would get if you ran
-B<dpkg-buildpackage -i'(?:^|/)\.git(?:/|$)' -I.git -S>
-and then unpacked the resultant source package.
-=for dgit-test dpkg-source-ignores end
+i.e., it is exactly what you would get if you deleted .git, invoked
+B<dpkg-buildpackage -S>, and then unpacked the resultant source
To achieve this, you might need to delete
I<debian/source/local-options>. One way to have dgit check your
@@ -272,9 +262,10 @@ The first dgit push will require I<--overwrite>.
=head1 GIT CONFIGURATION
-This workflow does not support using B<git merge> to merge divergent
-branches of development (see "OTHER MERGES" in git-debrebase(5)). You
-should configure git such that B<git pull> does not try to merge:
+git-debrebase does not yet support using B<git merge> to merge
+divergent branches of development (see "OTHER MERGES" in
+git-debrebase(5)). You should configure git such that B<git pull>
+does not try to merge:
@@ -285,7 +276,7 @@ should configure git such that B<git pull> does not try to merge:
Now when you pull work from other Debian contributors, git will rebase
your work on top of theirs.
-If you use this repository for upstream development in addition to
+If you use this clone for upstream development in addition to
Debian packaging work, you may not want to set this global setting.
Instead, see the B<branch.autoSetupRebase> and
B<branch.E<lt>nameE<gt>.rebase> settings in git-config(5).
@@ -333,12 +324,15 @@ or if you have a working watch file
% git debrebase new-upstream-v0 1.2.3
- % dch -v1.2.3-1 New upstream release.
- % git add debian/changelog && git commit -m changelog
-You can now review the merge of the new upstream release:
+This invocation of git-debrebase(1) involves a git rebase. You may
+need to resolve conflicts if the Debian delta queue does not apply
+cleanly to the new upstream source.
+If all went well, you can now review the merge of the new upstream
@@ -366,7 +360,7 @@ a tarball:
Adding new patches is straightforward: just make commits touching only
files outside of the I<debian/> directory. You can also use tools
-like git-revert(1), git-am(1) and git-cherrypick(1).
+like git-revert(1), git-am(1) and git-cherry-pick(1).
=head2 Editing patches: starting a debrebase