X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=git-debrebase.1.pod;h=cbdf292b2812e616248c06cfb8908374680d8c06;hp=e5b84a0b140b9fc6067d8c3649716707d9f9078e;hb=HEAD;hpb=9e94228f893936a65dea1a05758e523dc7e7d22f

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index e5b84a0b..639b07d2 100644
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -1,21 +1,35 @@
 =head1 NAME
 
-git-debrebase - delta queue rebase tool for Debian packaging
+git-debrebase - tool to maintain series of Debian changes to upstream source
 
 =head1 SYNOPSYS
 
  git-debrebase [<options...>] [-- <git-rebase options...>]
  git-debrebase [<options...>] <operation> [<operation options...>
 
-=head1 INTRODUCTION
+=head1 QUICK REFERENCE
 
-git-debrebase is a tool for representing in git,
-and manpulating,
-Debian packages based on upstream source code.
+These are most of the commands you will regularly need:
+
+ git debrebase -i                           # edit the patch queue
+ git debrebase conclude && git push         # push to eg salsa
+ git debrebase conclude && dgit push-source # source-only upload
+ git debrebase new-upstream 1.2.3-1 [-i]    # uses tag, eg "v1.2.3"
+ dpkg-buildpackage -uc -b                   # get test debs, at any time
+
+To add patches, or edit the packaging, just make git commits.
+Ignore anything that may appear in debian/patches.
+Avoid using "git pull" and "git merge" without "--ff-only".
+
+git-debrebase has a special branch format, so see
+"CONVERTING AN EXISTING PACKAGE" in L<dgit-maint-debrebase(7)>.
+
+=head1 GUIDE TO DOCUMENTATION
 
 This is the command line reference.
-Please read the tutorial
-L<dgit-maint-debrebase(7)>.
+There is also a detailed workflow tutorial at
+L<dgit-maint-debrebase(7)>
+(on which the above "QUICK REFERENCE" is based).
 For background, theory of operation,
 and definitions see L<git-debrebase(5)>.
 
@@ -115,11 +129,12 @@ You should consider using B<prepush> or B<conclude> instead.
 =item git-debrebase scrap
 
 Throws away all the work since the branch was last stitched.
-This is done by rewinding you to ffq-prev.
+This is done by resetting you to ffq-prev
+and discarding all working tree changes.
 
 If you are in the middle of a git-rebase, will abort that too.
 
-=item git-debrebase new-upstream <new-version> [<upstream-details>...]
+=item git-debrebase new-upstream <new-version> [<upstream-details>...] [--|-i <git-rebase options...>]
 
 Rebases the delta queue
 onto a new upstream version.  In detail:
@@ -370,7 +385,7 @@ and any ffq-prev is deleted.
 
 This is provided mostly for the test suite
 and for unusual situations.
-It should be used only with care and 
+It should only be used with care and 
 with a proper understanding of the underlying theory.
 
 Be sure to not accidentally treat the result as
@@ -420,7 +435,7 @@ failure to find an appropriate upstream.
 Directory to look in for orig tarballs.
 The default is the git config option
 dgit.default.build-products-dir
-or failing that, "C<..>".
+or failing that, C<..>.
 Passed on to dgit, if git-debrebase invokes dgit.
 
 =item --[no-]origs
@@ -531,7 +546,7 @@ This is provided mostly for the benefit of the test suite.
 
 Requests (more) debugging.  May be repeated.
 
-=item --experimntal-merge-resolution
+=item --experimental-merge-resolution
 
 Enable experimental code for handling general merges
 (see L<git-debrebase(5)/General merges>).
@@ -619,6 +634,6 @@ The result is the laundered branch.
 =head1 SEE ALSO
 
 git-debrebase(1),
-dgit-maint-rebase(7),
+dgit-maint-debrebase(7),
 dgit(1),
 gitglossary(7)