dgit-user(7): Fix some typos.

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

diff --git a/dgit-user.7.pod b/dgit-user.7.pod
index 98234658f5b5ca96f4f10f6d93046d187590d936..08647c61bbd3e80f5c2a41ecfbe06cb7e37294a7 100644 (file)
--- a/dgit-user.7.pod
+++ b/dgit-user.7.pod
@@ -30,7 +30,7 @@ or L<dgit(1)> and L<dgit(7)>.
 
 =over 4
 
 
 =over 4
 

-    % dgit clone glibc jessie
+    % 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
     % git commit -a -m 'Fix libc lost output bug'
     % cd glibc
     % wget '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'


@@ -55,7 +55,7 @@ Later:
 =over 4
 
     % cd glibc
 =over 4
 
     % cd glibc

-    % dgit pull jessie
+    % dgit pull jessie,-security

     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
     % dpkg-buildpackage -uc -b
     % sudo dpkg -i ../libc6_*.deb
     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
     % dpkg-buildpackage -uc -b
     % sudo dpkg -i ../libc6_*.deb


@@ -66,7 +66,7 @@ Later:
 
 =over 4
 
 
 =over 4
 

-    % dgit clone glibc jessie
+    % dgit clone glibc jessie,-security

     % cd glibc
 
 =back
     % cd glibc
 
 =back


@@ -125,15 +125,23 @@ If you don't know what you're running, try this:
 
 =back
 
 
 =back
 

+For Debian, you should add C<,-security>
+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.)
+

 =head1 WHAT DGIT CLONE PRODUCES
 
 =head2 What branches are there
 
 dgit clone will give you a new working tree,
 =head1 WHAT DGIT CLONE PRODUCES
 
 =head2 What branches are there
 
 dgit clone will give you a new working tree,

-and arrange for you to be on a branch like
-C<dgit/jessie>.
+and arrange for you to be on a branch named like
+C<dgit/jessie,-security> (yes, with a comma in the branch name).

 
 

-There is a tracking branch for the contents of the archive, called
+For each release (like C<jessie>)
+there is a tracking branch for the contents of the archive, called

 C<remotes/dgit/dgit/jessie>
 (and similarly for other suites).  This can be updated with
 C<dgit fetch jessie>.
 C<remotes/dgit/dgit/jessie>
 (and similarly for other suites).  This can be updated with
 C<dgit fetch jessie>.


@@ -141,6 +149,12 @@ 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<*-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'll have to supply a C<-p>I<package> option to dgit fetch.)
 (You can also dgit fetch in a tree that wasn't made by dgit clone.
 If there's no C<debian/changelog>
 you'll have to supply a C<-p>I<package> option to dgit fetch.)


@@ -189,6 +203,9 @@ history invented by dgit.
 dgit histories often contain automatically-generated commits,
 including commits which make no changes but just serve
 to make a rebasing branch fast-forward.
 dgit histories often contain automatically-generated commits,
 including commits which make no changes but just serve
 to make a rebasing branch fast-forward.

+This is particularly true of
+combining branches like
+C<jessie,-security>.

 
 If the package maintainer is using git then
 after dgit clone
 
 If the package maintainer is using git then
 after dgit clone


@@ -217,7 +234,7 @@ 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>.
 
 they may modify files which are also committed to git,
 or leave outputs and teporary files not covered by C<.gitignore>.
 

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

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


@@ -288,6 +305,8 @@ but not to build a source package.
 
 =head1 INSTALLING
 
 
 =head1 INSTALLING
 

+=head2 Debian Jessie or older
+

 =over 4
 
     % sudo dpkg -i ../libc6_*.deb
 =over 4
 
     % sudo dpkg -i ../libc6_*.deb


@@ -301,6 +320,14 @@ If the dependencies aren't installed,
 you will get an error, which can usually be fixed with
 C<apt-get -f install>.
 
 you will get an error, which can usually be fixed with
 C<apt-get -f install>.
 

+=head2 Debian Stretch or newer
+
+=over 4
+
+    % sudo apt install ../libc6_*.deb
+
+=back
+

 =head1 Multiarch
 
 If you're working on a library package and your system has multiple
 =head1 Multiarch
 
 If you're working on a library package and your system has multiple


@@ -335,9 +362,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 verseion 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
 


@@ -352,7 +379,7 @@ but passing C<--force-overwrite> to dpkg will help
 
 =head1 SHARING YOUR WORK
 
 
 =head1 SHARING YOUR WORK
 

-The C<dgit/jessie> branch (or whatever) is a normal git branch.
+The C<dgit/jessie,-security> branch (or whatever) is a normal git branch.

 You can use C<git push> to publish it on any suitable git server.
 
 Anyone who gets that git branch from you
 You can use C<git push> to publish it on any suitable git server.
 
 Anyone who gets that git branch from you


@@ -381,15 +408,15 @@ you need to provide a source package
 but don't care about its format/layout
 (for example because some software you have consumes source packages,
 not git histories)
 but don't care about its format/layout
 (for example because some software you have consumes source packages,
 not git histories)

-you can use this recipe to generate a C<1.0> "native"
+you can use this recipe to generate a C<3.0 (native)>

 source package, which is just a tarball
 with accompanying .dsc metadata file:
 
 =over 4
 
 source package, which is just a tarball
 with accompanying .dsc metadata file:
 
 =over 4
 

-    % git rm debian/source/version
-    % git commit -m 'switch to 1.0 source format'
-    % dgit -wgf --dpkg-buildpackage:-sn build-source
+    % echo '3.0 (native)' >debian/source/format
+    % git commit -m 'switch to native source format' debian/source/format
+    % dgit -wgf build-source

 
 =back
 
 
 =back