X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit-user.7.pod;h=d7b610986b4ce15c4dc8d172432c09639035a21d;hp=e7300522098434daf7f3053d7745873f50a1e8de;hb=bc0c5d92e3f9fff9de05afbb7519bb29c25ac74f;hpb=dedbcd47ea209e4ba1988b1621b81491d214756d

diff --git a/dgit-user.7.pod b/dgit-user.7.pod
index e7300522..d7b61098 100644
--- a/dgit-user.7.pod
+++ b/dgit-user.7.pod
@@ -30,7 +30,7 @@ or L<dgit(1)> and L<dgit(7)>.
 
 =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'
@@ -55,7 +55,7 @@ Later:
 =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
@@ -66,7 +66,7 @@ Later:
 
 =over 4
 
-    % dgit clone glibc jessie
+    % dgit clone glibc jessie,-security
     % cd glibc
 
 =back
@@ -125,15 +125,23 @@ If you don't know what you're running, try this:
 
 =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,
-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>.
@@ -141,6 +149,12 @@ This, the I<remote suite branch>,
 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.)
@@ -183,12 +197,15 @@ 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.
-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,
 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
@@ -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>.
 
-Kf you always commit,
+If you always commit,
 you can use
 
 =over 4
@@ -332,7 +349,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.
-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.
@@ -345,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.
-(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,
-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
 
@@ -362,7 +379,7 @@ but passing C<--force-overwrite> to dpkg will help
 
 =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
@@ -391,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)
-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
 
-    % 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