git-debrebase: merge: Improve some xxx comments

[dgit.git] / git-debrebase.1.pod

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 4d1a67360d6a4ba9a4700cd08caac5cb840a57dd..fe65674735838fa3fe67566a5edf62e6550170bc 100644 (file)
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -55,6 +55,12 @@ The options for git-rebase must either start with C<-i>,
 or be prececded by C<-->,
 to distinguish them from options for git-debrebase.
 
 or be prececded by C<-->,
 to distinguish them from options for git-debrebase.
 

+It is hazardous to use plain git-rebase on a git-debrebase branch,
+because git-rebase has a tendency to start the rebase
+too far back in history,
+and then drop important commits.
+Soo L<git-debrebase(5)/ILLEGAL OPERATIONS>
+

 =item git-debrebase status
 
 Analyses the current branch,
 =item git-debrebase status
 
 Analyses the current branch,


@@ -100,6 +106,13 @@ If there is no ffq-prev, it is an error, unless --noop-ok.
 You should consider using B<conclude> instead,
 because that launders the branch too.
 
 You should consider using B<conclude> instead,
 because that launders the branch too.
 

+=item git-debrebase scrap
+
+Throws away all the work since the branch was last stitched.
+This is done by rewinding you to ffq-prev.
+
+If you are in the middle of a git-rebase, will abort that too.
+

 =item git-debrebase new-upstream <new-version> [<upstream-details>...]
 
 Rebases the delta queue
 =item git-debrebase new-upstream <new-version> [<upstream-details>...]
 
 Rebases the delta queue


@@ -250,6 +263,8 @@ the gbp upstream branch, if there is one.
 It is a snag if it is not an ancestor of HEAD,
 or if the history between the upstream and HEAD
 contains commits which make changes to upstream files.
 It is a snag if it is not an ancestor of HEAD,
 or if the history between the upstream and HEAD
 contains commits which make changes to upstream files.

+If it is not specified,
+the same algorithm is used as for git-debrebase new-upstream.

 
 It is also a snag if the specified upstream
 has a debian/ subdirectory.
 
 It is also a snag if the specified upstream
 has a debian/ subdirectory.


@@ -257,11 +272,20 @@ This check exists to detect certain likely user errors,
 but if this situation is true and expected,
 forcing it is fine.
 
 but if this situation is true and expected,
 forcing it is fine.
 

+git-debrebase will try to look for the dgit archive view
+of the most recent release,
+and if it finds it will make a pseduomerge so that
+your new git-debrebase view is appropriately fast forward.
+

 The result is a well-formed git-debrebase interchange branch.
 The result is also fast-forward from the gbp branch.
 
 The result is a well-formed git-debrebase interchange branch.
 The result is also fast-forward from the gbp branch.
 

+It is a snag if the new branch looks like it will have diverged,
+just as for a laundering/unstitching call to git-debrebase;
+See L</Establish the current branch's ffq-prev>, below.
+

 Note that it is dangerous not to know whether you are
 Note that it is dangerous not to know whether you are

-dealing with a gbp patches-unappled branch containing quilt patches,
+dealing with a gbp patches-unapplied branch containing quilt patches,

 or a git-debrebase interchange branch.
 At worst,
 using the wrong tool for the branch format might result in
 or a git-debrebase interchange branch.
 At worst,
 using the wrong tool for the branch format might result in


@@ -326,6 +350,72 @@ Be sure to not accidentally treat the result as
 a git-debrebase branch,
 or you will drop all the patches!
 
 a git-debrebase branch,
 or you will drop all the patches!
 

+=item git-debrebase convert-from-dgit-view [<convert-options>] [upstream]
+
+Converts any dgit-compatible git branch
+corresponding to a (possibly hypothetical) 3.0 quilt dsc source package
+into a git-debrebase-compatible branch.
+
+This operation should not be used
+if the branch is already in git-debrebase form.
+Normally git-debrebase will refuse to continue in this case
+(or silently do nothing if the global --noop-ok option is used).
+
+Some representation of the original upstream source code will be needed.
+If I<upstream> is supplied, that must be a suitable upstream commit.
+By default,
+git-debrebase will look first for git tags (as for new-upstream),
+and then for orig tarballs which it will ask dgit to process.
+
+The upstream source must be exactly right and
+all the patches in debian/patches must be up to date.
+Applying the patches from debian/patches to the upstream source
+must result in exactly your HEAD.
+
+The output is laundered and stitched.
+The resulting history is not particularly pretty,
+especially if orig tarball(s) were imported
+to produce a synthetic upstream commit.
+
+The available convert-options are as follows.
+(These must come after convert-from-dgit-view.)
+
+=over
+
+=item --[no-]diagnose
+
+Print additional error messages to help diagnose
+failure to find an appropriate upstream.
+--no-diagnose is the default.
+
+=item --build-products-dir
+
+Directory to look in for orig tarballs.
+The default is the git config option
+dgit.default.build-products-dir
+or failing that, C<..>.
+Passed on to dgit, if git-debrebase invokes dgit.
+
+=item --[no-]origs
+
+Whether to try to look for or use any orig tarballs.
+--origs is the default.
+
+=item --[no-]tags
+
+Whether to try to look for or use any upstream git tags.
+--tags is the default.
+
+=item --always-convert-anyway
+
+Perform the conversion operation,
+producing unpleasant extra history,
+even if the branch seems to be in git-debrebase form already.
+This should not be done unless necessary,
+and it should not be necessary.
+
+=back
+

 =back
 
 =head1 OPTIONS
 =back
 
 =head1 OPTIONS


@@ -390,6 +480,12 @@ it is a snag if <commit-ish> is the anchor
 for the previous upstream version in
 git-debrebase new-upstream operations.
 
 for the previous upstream version in
 git-debrebase new-upstream operations.
 

+=item --dgit=<program>
+
+Run <program>, instead of dgit from PATH,
+when invocation of dgit is necessary.
+This is provided mostly for the benefit of the test suite.
+

 =item -D
 
 Requests (more) debugging.  May be repeated.
 =item -D
 
 Requests (more) debugging.  May be repeated.