This is the command line reference.
Please read the tutorial
-L<dgit-maint-debrebase(5)>.
+L<dgit-maint-debrebase(7)>.
For background, theory of operation,
and definitions see L<git-debrebase(5)>.
-You should read this manpage in conjunction with
+You should read this manpage in cojnunction with
L<git-debrebase(5)/TERMINOLOGY>,
which defines many important terms used here.
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,
+both in terms of its contents,
+and the refs which are relevant to git-debrebase,
+and prints a human-readable summary.
+
+Please do not attempt to parse the output;
+it may be reformatted or reorganised in the future.
+Instead,
+use one of the L<UNDERLYING AND SUPPLEMENTARY OPERATIONS>
+described below.
+
+=item git-debrebase conclude
+
+Finishes a git-debrebase session,
+tidying up the branch and making it fast forward again.
+
+Specifically: if the branch is unstitched,
+launders and restitches it,
+making a new pseudomerge.
+Otherwise, it is an error,
+unless --noop-ok.
+
=item git-debrebase quick
Unconditionally launders and restitches the branch,
consuming any ffq-prev
and making a new pseudomerge.
-If the branch is already laundered and stitched, it is an error,
-unless --noop-ok.
+If the branch is already laundered and stitched, does nothing.
+
+=item git-debrebase prepush [--prose=<for commit message>]
=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.
-It is a snag (see B<-f>) if the branch is not laundered.
+You should consider using B<conclude> instead,
+because that launders the branch too.
-=item git-debrebase new-upstream-v0 <new-version> [<upstream-details>...]
+=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
onto a new upstream version. In detail:
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
=item <upstream-commit-ish>
The new upstream branch (or commit-ish).
-Default is C<upstream>.
+The default is to look for one of these tags, in this order:
+U vU upstream/U;
+where U is the new upstream version.
+(This is the same algorithm as L<git-deborig(1)>.)
It is a snag if the upstream contains a debian/ directory;
if forced to proceed,
L<git-archive(1)>, L<dgit(1)> and
L<gbp-import-orig(1)> may be able to help.
-This subcommand has -v0 in its name because we are not yet sure
-that its command line syntax is optimal.
-We may want to introduce an incompatible replacement syntax
-under the name C<new-upstream>.
+=item git-debrebase make-patches [--quiet-would-amend]
+
+Generate patches in debian/patches/
+representing the changes made to upstream files.
+
+It is not normally necessary to run this command explicitly.
+When uploading to Debian,
+dgit and git-debrebase
+will cooperate to regenerate patches as necessary.
+When working with pure git remotes,
+the patches are not needed.
+
+Normally git-debrebase make-patches will
+require a laundered branch.
+(A laundered branch does not contain any patches.)
+But if there are already some patches made by
+git-debrebase make-patches,
+and all that has happened is that more
+changes to upstream files have been committed,
+running it again can add the missing patches.
+
+If the patches implied by the current branch
+are not a simple superset of those already in debian/patches,
+make-patches will fail with exit status 7,
+and an error message.
+(The message can be suppress with --quiet-would-amend.)
+If the problem is simply that
+the existing patches were not made by git-debrebase,
+using dgit quilt-fixup instead should succeed.
=item git-debrebase convert-from-gbp [<upstream-commit-ish>]
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.
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.
+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
-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
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
Some troublesome things which git-debrebase encounters
are B<snag>s.
(The specific instances are discussed
-in the text for the relvant operation.)
+in the text for the relevant operation.)
When a snag is detected,
a message is printed to stderr containing the snag id
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.
~ianmdlvl / dgit.git / blobdiff