=back
-Now go ahead and Debianise your package. Just make commits on the
-master branch, adding things in the I<debian/> directory, or patching
-the upstream source.
+Now go ahead and Debianise your package. Make commits on the master
+branch, adding things in the I<debian/> directory, or patching the
+upstream source. For technical reasons, B<it is essential that your
+first commit introduces 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.
Finally, you need an orig tarball:
This tarball is ephemeral and easily regenerated, so we don't commit
it anywhere (e.g. with tools like pristine-tar(1)).
-=head3 Verifying upstream's tarball releases
+=head3 Comparing upstream's tarball releases
=over 4
-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
+tarball.
+
+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.
=back
=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
+begin
=over 4
=back
You are now ready to proceed as above, making commits to the
-I<debian/> directory and to the upstream source.
+I<debian/> directory and to the upstream source. As above, for
+technical reasons, B<it is essential that your first commit introduces
+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
=back
-If your tree is patches-unapplied, you will need to make a commit
-corresponding to each of the quilt patches. You can use
+If your tree is patches-unapplied, some conversion work is needed.
+You can use
=over 4
=back
-or manually with gbp-pq(1):
-
-=over 4
-
- % gbp pq import
- % gbp pq switch
- % git merge --ff-only patch-queue/master
- % gbp pq drop
-
-=back
-
Then make new upstream tags available:
=over 4
=back
-=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
+package.
To achieve this, you might need to delete
I<debian/source/local-options>. One way to have dgit check your
=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:
=over 4
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).
=over 4
% git debrebase new-upstream-v0 1.2.3
- % dch -v1.2.3-1 New upstream release.
- % git add debian/changelog && git commit -m changelog
=back
-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
+release:
=over 4
=back
+=head1 EDITING THE DEBIAN PACKAGING
+
+Just make commits on master that change the contents of I<debian/>.
+
=head1 EDITING THE DELTA QUEUE
=head2 Adding new patches
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
=over 4
- % git debrebase
+ % git debrebase -i
=back
=over 4
- % git debrebase launder
+ % git debrebase
% dgit push-source
=back
=head2 Alternative ways to start a debrebase
Above we started an interactive debrebase by invoking git-debrebase(1)
-without any arguments, i.e.
+like this:
=over 4
- % git debrebase
+ % git debrebase -i
=back
=back
If you take this approach, you should be very careful not to start the
-rebase earlier than the beginning of the delta queue.
+rebase too early.
=head1 SEE ALSO
~ianmdlvl / dgit.git / blobdiff