|author||Ian Jackson <firstname.lastname@example.org>||2018-02-19 00:52:11 +0000|
|committer||Ian Jackson <email@example.com>||2018-06-16 16:07:00 +0100|
Signed-off-by: Ian Jackson <firstname.lastname@example.org>
Diffstat (limited to 'git-debrebase.1.pod')
1 files changed, 213 insertions, 0 deletions
diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
new file mode 100644
@@ -0,0 +1,213 @@
+git-debrebase - delta queue rebase tool for Debian packaging
+git-debrebase is a tool for representing in git,
+Debian packages based on upstream source code.
+This is the command line reference.
+Please read the tutorial
+For background, theory of operation,
+and definitions of the terms used here,
+=head1 PRINCIPAL OPERATIONS
+=item git-debrebase [-- <git-rebase options...>]
+Unstitches and launders the branch.
+(See L</UNSTITCHING AND LAUNDERING> below.)
+Then optionally edits the Debian delta queue,
+using git-rebase, by running
+ git rebase <git-rebase options> <breakwater-tip>
+Do not pass a base branch argument:
+git-debrebase will supply that.
+Do not use --onto, or --fork-point.
+Useful git-rebase options include -i and --autosquash.
+If git-rebase stops for any reason,
+you may git-rebase --abort, --continue, or --skip, as usual.
+If you abort the git-rebase,
+the branch will still have been laundered,
+but everything in the rebase will be undone.
+=item git-debrebase stitch [--prose=<for commit message>]
+Stitch the branch,
+If there is no ffq-prev, it is an error, unless --noop-ok.
+=item git-debrebase new-upstream-v0 <new-version> [<upstream-details>...]
+Rebases the delta queue
+onto a new upstream version. In detail:
+Firstly, checks that the proposed rebase seems to make sense:
+It is a problem unless the new upstream(s)
+are fast forward from the previous upstream(s)
+as found in the current breakwater anchor.
+And, in the case of a multi-piece upstream,
+if the pieces are not in the same order, with the same names.
+If all seems well, unstitches and launders the branch.
+(in a private working area)
+a new anchor merge commit,
+on top of the breakwater tip,
+and on top of that a commit to
+update the version number in debian/changelog.
+starts a git-rebase
+of the delta queue onto these new commits.
+That git-rebase may complete successfully,
+or it may require your assistance,
+just like a normal git-rebase.
+If you git-rebase --abort,
+the whole new upstream operation is aborted,
+but the laundering will still have been done.
+The <upstream-details> are, optionally, in order:
+The new upstream branch (or commitish).
+Default is C<upstream>.
+It is a problem if the upstream contains a debian/ directory;
+if forced to proceed,
+git-debrebase will disregard the upstream's debian/ and
+take (only) the packaging from the current breakwater.
+=item <piece-name> <piece-upstream-commitish>
+Specifies that this is a multi-piece upstream.
+(A multi-component upstream, in dpkg-source terminology.)
+May be repeated.
+When such a pair is specified,
+git-debrebase will first combine the pieces of the upstream
+and then use the result as the combined new upstream.
+For each <piece-name>,
+the tree of the <piece-upstream-commitish>
+becomes the subdirectory <piece-name>
+in the combined new upstream
+(supplanting any subdirectory that might be there in
+the main upstream branch).
+<piece-name> has a restricted syntax:
+it may contain only ASCII alphanumerics and hyphens.
+The combined upstream is itself recorded as a commit,
+with each of the upstream pieces' commits as parents.
+The combined commit contains an annotation
+to allow a future git-debrebase new upstream operation
+to make the coherency checks described above.
+=item <git-rebase options>
+These will be passed to git rebase.
+If the upstream rebase is troublesome, -i may be helpful.
+As with plain git-debrebase,
+do not specify a base, or --onto, or --fork-point.
+If you are planning to generate a .dsc,
+you will also need to have, or generate,
+actual orig tarball(s),
+which must be identical to the rev-spec(s)
+passed to git-debrebase.
+git-debrebase does not concern itself with source packages
+so neither helps with this, nor checks it.
+L<git-archive(1)>, L<dgit(1)> and L<gbp(1)> may be able to help.
+=head1 UNSTITCHING AND LAUNDERING
+Several operations unstitch and launder the branch first.
+In detail this means:
+=head2 Establish the current branch's ffq-prev
+If it is not yet recorded, we
+check that the current branch is ahead of relevant
+remote tracking branches.
+The remote tracking branches checked by default are
+obtained from the git config.
+In each case it is a problem if we are behind the checked remote,
+or if we have diverged from it.
+All the checks are local:
+git-debrebase does not fetch anything from anywhere.
+We check the branch we would merge from
+and the branch we would push to
+For local dgit suite branches
+we check the corresponding tracking remote.
+If we are on C<master>, we check remotes/dgit/dgit/sid.
+The resulting ref names to check are filtered through
+which is a semicolon-separated list of glob patterns,
+each optionally preceded by !; first match wins.
+If these checks pass,
+or are forced,
+we then record the current tip as ffq-prev.
+=head2 Examine the branch
+Analyse the current HEAD's history to find the anchor
+in its breakwater,
+and the most recent breakwater tip.
+=head2 Rewrite the commits into laundered form
+Mixed debian+upstream commits are split into two commits each.
+Delta queue (upstream files) commits bubble to the top.
+and quilt patch additions,
+This rewrite will always succeed, by construction.
+The result is the laundered branch.
+=head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
+=item git-debrebase breakwater
+Prints the breakwater tip commitid.
+Fails if your HEAD branch is not laundered.
+=head1 SEE ALSO