From 75d0b8d7275c035f76db79e7cf7e802e061a9bee Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 19 Feb 2018 00:52:11 +0000 Subject: [PATCH] git-debrebase(1): wip Signed-off-by: Ian Jackson --- NOTES.git-debrebase | 21 ----- git-debrebase | 8 -- git-debrebase.1.pod | 213 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 213 insertions(+), 29 deletions(-) create mode 100644 git-debrebase.1.pod diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase index 31c0c1c5..79b6f2b6 100644 --- a/NOTES.git-debrebase +++ b/NOTES.git-debrebase @@ -84,27 +84,6 @@ We check we are ff from remotes before recording new ffq-prev ---------- now follows much the same info in different words ---------- -1. git-debrebase [-i etc.] - - should: - check for ffq-prev - if is already a ffq-prev, fine, do no more - if not: - - check our origin branch exists and we are ff from it - if not fail - - check our other might-be-pushed to branches - check we are ff from them - if not fail - - set ffq-prev to something which is ff from - all above branches - - we use our tip, as discussed above - (optionally, can use some other commit which is ff - from all of the above, eg one of them) - N. git-debrebase [--noop-ok] record-ffq-prev does what is described above diff --git a/git-debrebase b/git-debrebase index 5b2312d8..2520d52c 100755 --- a/git-debrebase +++ b/git-debrebase @@ -21,15 +21,7 @@ # usages: # -# git-debrebase [] new-upstream-v0 \ -# [ \ -# [ ...] \ -# [...]] -# -# git-debrebase [ --] [] # git-debrebase [] analyse -# git-debrebase [] breakwater # prints breakwater tip only -# git-debrebase [] stitch [--prose=] # git-debrebase [] launder-v0 # prints breakwater tip etc. # git-debrebase [] downstream-rebase-launder-v0 # experimental # diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod new file mode 100644 index 00000000..ab6e12ce --- /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. + +For background, theory of operation, +and definitions of the terms used here, +see L. + +=head1 PRINCIPAL OPERATIONS + +=over + +=item git-debrebase [-- ] + +Unstitches and launders the branch. +(See L below.) + +Then optionally edits the Debian delta queue, +using git-rebase, by running + + git rebase + +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=] + +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 [...] + +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 are, optionally, in order: + +=over + +=item + +The new upstream branch (or commitish). +Default is C. + +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 + +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 , +the tree of the +becomes the subdirectory +in the combined new upstream +(supplanting any subdirectory that might be there in +the main upstream branch). + + 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 + +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, L and L 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..merge, remote..remote) +and the branch we would push to +(remote..pushRemote etc.). +For local dgit suite branches +we check the corresponding tracking remote. +If we are on C, we check remotes/dgit/dgit/sid. +The resulting ref names to check are filtered through +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) -- 2.30.2