diff options
| -rw-r--r-- | NOTES.git-debrebase | 5 | ||||
| -rw-r--r-- | git-debrebase.1.pod | 61 |
2 files changed, 39 insertions, 27 deletions
diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase index 79b6f2b..5a6ff88 100644 --- a/NOTES.git-debrebase +++ b/NOTES.git-debrebase @@ -88,10 +88,7 @@ N. git-debrebase [--noop-ok] record-ffq-prev does what is described above -2. git-debrebase [--noop-ok] stitch - - makes pseudomerge with ffq-prev - deletes ffq-prev +Re git-debrebase [--noop-ok] stitch we will teach dgit to do git-debrebase stitch diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index ab6e12c..ce442da 100644 --- a/git-debrebase.1.pod +++ b/git-debrebase.1.pod @@ -2,6 +2,11 @@ git-debrebase - delta queue rebase tool for Debian packaging +=head1 SYNOPSYS + + git-debrebase [<options...>] [-- <git-rebase options...>] + git-debrebase [<options...>] <operation> [<operation options...> + =head1 INTRODUCTION git-debrebase is a tool for representing in git, @@ -11,11 +16,14 @@ 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)>. +If no operation is specified, +git-debrebase launders the branch and rebases the Debian delta queue. +See below. + =head1 PRINCIPAL OPERATIONS =over @@ -142,6 +150,22 @@ 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. +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>. + +=back + +=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 UNSTITCHING AND LAUNDERING @@ -151,24 +175,25 @@ 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 +If it is not yet recorded, +git-debrebase checks 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: +In each case it is a problem if +the local HEAD is behind the checked remote, +or if local HEAD has diverged from it. +All the checks are done locally using the remote tracking refs: git-debrebase does not fetch anything from anywhere. -We check the branch we would merge from +git-debrebase checks the branch that git would merge from (remote.<branch>.merge, remote.<branch>.remote) -and the branch we would push to +and the branch git 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. +it checks the corresponding tracking remote. +If you are on C<master>, it checks 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, @@ -176,11 +201,12 @@ each optionally preceded by !; first match wins. If these checks pass, or are forced, -we then record the current tip as ffq-prev. +git-debrebse then records the current tip as ffq-prev. =head2 Examine the branch -Analyse the current HEAD's history to find the anchor +git-debrebase +analyses the current HEAD's history to find the anchor in its breakwater, and the most recent breakwater tip. @@ -195,17 +221,6 @@ 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), |