git-debrebase: capture breakwater tip

[dgit.git] / dgit-user.7.pod

diff --git a/dgit-user.7.pod b/dgit-user.7.pod
index 95d08d8e6ee2010669775e8e6e1c27777616ec5b..c74396a56954d2ff176c2032cb022b1d71447921 100644 (file)
--- a/dgit-user.7.pod
+++ b/dgit-user.7.pod
@@ -32,10 +32,10 @@ or L<dgit(1)> and L<dgit(7)>.
 
     % dgit clone glibc jessie,-security
     % cd glibc
 
     % dgit clone glibc jessie,-security
     % cd glibc

-    % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
+    % curl 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u

     % git commit -a -m 'Fix libc lost output bug'
     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
     % git commit -a -m 'Fix libc lost output bug'
     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit

-    % sudo apt-get build-dep glibc
+    % mk-build-deps --root-cmd=sudo --install

     % dpkg-buildpackage -uc -b
     % sudo dpkg -i ../libc6_*.deb
 
     % dpkg-buildpackage -uc -b
     % sudo dpkg -i ../libc6_*.deb
 


@@ -126,7 +126,8 @@ If you don't know what you're running, try this:
 =back
 
 For Debian, you should add C<,-security>
 =back
 
 For Debian, you should add C<,-security>

-to the end of the suite name.
+to the end of the suite name,
+unless you're on unstable or testing.

 Hence, in our example
 C<jessie> becomes C<jessie,-security>.
 (Yes, with a comma.)
 Hence, in our example
 C<jessie> becomes C<jessie,-security>.
 (Yes, with a comma.)


@@ -148,9 +149,11 @@ This, the I<remote suite branch>,
 is synthesized by your local copy of dgit.
 It is fast forwarding.
 
 is synthesized by your local copy of dgit.
 It is fast forwarding.
 

-Debian separates out the security updates, into C<debian-security>.
-Telling dgit C<debian,-security> means that it should include 
-any updates available in C<debian-security>.
+Debian separates out the security updates, into C<*-security>.
+Telling dgit C<jessie,-security> means that it should include 
+any updates available in C<jessie-security>.
+The comma notation is a request to dgit to track jessie,
+or jessie-security if there is an update for the package there.

 
 (You can also dgit fetch in a tree that wasn't made by dgit clone.
 If there's no C<debian/changelog>
 
 (You can also dgit fetch in a tree that wasn't made by dgit clone.
 If there's no C<debian/changelog>


@@ -194,7 +197,7 @@ or upstream's git history.
 But for many packages the real git history
 does not exist,
 or has not been published in a dgitish form.
 But for many packages the real git history
 does not exist,
 or has not been published in a dgitish form.

-So yuu may find that the history is a rather short
+So you may find that the history is a rather short

 history invented by dgit.
 
 dgit histories often contain automatically-generated commits,
 history invented by dgit.
 
 dgit histories often contain automatically-generated commits,


@@ -229,9 +232,9 @@ that are in debian/patches before you do anything else!
 
 Debian package builds are often quite messy:
 they may modify files which are also committed to git,
 
 Debian package builds are often quite messy:
 they may modify files which are also committed to git,

-or leave outputs and teporary files not covered by C<.gitignore>.
+or leave outputs and temporary files not covered by C<.gitignore>.

 
 

-Kf you always commit,
+If you always commit,

 you can use
 
 =over 4
 you can use
 
 =over 4


@@ -285,21 +288,37 @@ a complete treatment is beyond the scope of this tutorial.
 
 =over 4
 
 
 =over 4
 

-    % sudo apt-get build-dep glibc
+    % mk-build-deps --root-cmd=sudo --install

     % dpkg-buildpackage -uc -b
 
 =back
 
     % dpkg-buildpackage -uc -b
 
 =back
 

-apt-get build-dep installs the build dependencies according to the
-official package, not your modified one.  So if you've changed the
-build dependencies you might have to install some of them by hand.
-

 dpkg-buildpackage is the primary tool for building a Debian source
 package.
 C<-uc> means not to pgp-sign the results.
 C<-b> means build all binary packages,
 but not to build a source package.
 
 dpkg-buildpackage is the primary tool for building a Debian source
 package.
 C<-uc> means not to pgp-sign the results.
 C<-b> means build all binary packages,
 but not to build a source package.
 

+=head2 Using sbuild
+
+You can build in an schroot chroot, with sbuild, instead of in your
+main environment.  (sbuild is used by the Debian build daemons.)
+
+=over 4
+
+    % git clean -xdf
+    % sbuild -c jessie -A --no-clean-source \
+             --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'
+
+=back
+
+Note that this will seem to leave a "source package"
+(.dsc and .tar.gz)
+in the parent directory,
+but that source package should not be used.
+It is likely to be broken.
+For more information see Debian bug #868527.
+

 =head1 INSTALLING
 
 =head2 Debian Jessie or older
 =head1 INSTALLING
 
 =head2 Debian Jessie or older


@@ -346,7 +365,7 @@ The proper solution
 is to build the package for all the architectures you
 have enabled.
 You'll need a chroot for each of the secondary architectures.
 is to build the package for all the architectures you
 have enabled.
 You'll need a chroot for each of the secondary architectures.

-This iw somewhat tiresome,
+This is somewhat tiresome,

 even though Debian has excellent tools for managing chroots.
 C<sbuild-createchroot> from the sbuild package is a
 good starting point.
 even though Debian has excellent tools for managing chroots.
 C<sbuild-createchroot> from the sbuild package is a
 good starting point.


@@ -359,9 +378,9 @@ If neither of those are an option,
 your desperate last resort is to try
 using the same version number
 as the official package for your own package.
 your desperate last resort is to try
 using the same version number
 as the official package for your own package.

-(The verseion is controlled by C<debian/changelog> - see above,)
+(The version is controlled by C<debian/changelog> - see above).

 This is not ideal because it makes it hard to tell what is installed,
 This is not ideal because it makes it hard to tell what is installed,

-because it will mislead and confuse apt.
+and because it will mislead and confuse apt.

 
 With the "same number" approach you may still get errors like
 
 
 With the "same number" approach you may still get errors like