git-debrebase(1): wip

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

1 files changed, 213 insertions, 0 deletions

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
new file mode 100644
index 0000000..ab6e12c
--- /dev/null
+++ b/git-debrebase.1.pod
@@ -0,0 +1,213 @@
+=head1 NAME
+
+git-debrebase - delta queue rebase tool for Debian packaging
+
+=head1 INTRODUCTION
+
+git-debrebase is a tool for representing in git,
+and manpulating,
+Debian packages based on upstream source code.
+
+This is the command line reference.
+Please read the tutorial
+L<dgit-maint-debrebase(5)>.
+
+For background, theory of operation,
+and definitions of the terms used here,
+see L<git-debrebase(5)>.
+
+=head1 PRINCIPAL OPERATIONS
+
+=over
+
+=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,
+consuming ffq-prev.
+
+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.
+
+Then,
+generates
+(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.
+
+Finally,
+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:
+
+=over
+
+=item <upstream-commitish>
+
+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
+together,
+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.
+
+=back
+
+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.
+
+=back
+
+=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
+(remote.<branch>.merge, remote.<branch>.remote)
+and the branch we would push to
+(remote.<branch>.pushRemote etc.).
+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
+branch.<branch>.ffq-ffrefs,
+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.
+Pseudomerges,
+and quilt patch additions,
+are dropped.
+
+This rewrite will always succeed, by construction.
+The result is the laundered branch.
+
+=head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
+
+=over
+
+=item git-debrebase breakwater
+
+Prints the breakwater tip commitid.
+Fails if your HEAD branch is not laundered.
+
+=back
+
+=head1 SEE ALSO
+
+git-debrebase(1),
+dgit-maint-rebase(7),
+dgit(1)