git-debrebase: new-upstream: Drop `sleep 2' (!)

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

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 1c3e68128f0e4967e90d1bb9e219b43b075e57a9..1156825c8a92831c55507a115b92413ace15fe16 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,


@@ -89,16 +95,29 @@ If the branch is already laundered and stitched, does nothing.
 
 =item git-debrebase prepush [--prose=<for commit message>]
 
 
 =item git-debrebase prepush [--prose=<for commit message>]
 

+If the branch is unstitched,
+stitches it,
+consuming ffq-prev.
+
+This is a good command to run before pushing to a git server.
+You should consider using B<conclude> instead,
+because that launders the branch too.
+

 =item git-debrebase stitch [--prose=<for commit message>]
 
 Stitches the branch,
 consuming ffq-prev.
 =item git-debrebase stitch [--prose=<for commit message>]
 
 Stitches the branch,
 consuming ffq-prev.

-This is a good command to run before pushing to a git server.

 
 If there is no ffq-prev, it is an error, unless --noop-ok.
 
 
 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<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.
+
+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>...]
 


@@ -135,6 +154,12 @@ If you git-rebase --abort,
 the whole new upstream operation is aborted,
 except for the laundering.
 
 the whole new upstream operation is aborted,
 except for the laundering.
 

+<new-version>
+may be whole new Debian version, including revision,
+or just the upstream part,
+in which case -1 will be appended
+to make the new Debian version.
+

 The <upstream-details> are, optionally, in order:
 
 =over
 The <upstream-details> are, optionally, in order:
 
 =over


@@ -244,6 +269,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.


@@ -251,11 +278,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


@@ -320,6 +356,86 @@ 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
+
+=item git-debrebase forget-was-ever-debrebase
+
+Deletes the ffq-prev and debrebase-last refs
+associated with this branch,
+that git-debrebase and dgit use to determine
+whether this branch is managed by git-debrebase,
+and what previous head may need to be stitched back in.
+
+This can be useful if you were just playing with git-debrebase,
+and have used git-reset --hard to go back to a commit
+before your experiments.
+
+Do not use this if you expect to run git-debrebase on the branch again.
+

 =back
 
 =head1 OPTIONS
 =back
 
 =head1 OPTIONS


@@ -384,10 +500,30 @@ 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.
 

+=item --experimntal-merge-resolution
+
+Enable experimental code for handling general merges
+(see L<git-debrebase(5)/General merges>).
+
+This option may generate branch structures that
+require the use of this same option by other people.
+Also you may experience lossage of various kinds,
+including false error messages,
+references to nonexistent documentation,
+being handed an incomprehensible pile of
+multidimensional merge wreckage,
+and/or possible mangling of your package's source code.
+

 =back
 
 =head1 UNSTITCHING AND LAUNDERING
 =back
 
 =head1 UNSTITCHING AND LAUNDERING