diff options
author | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2018-02-19 00:52:11 +0000 |
---|---|---|
committer | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2018-06-16 16:07:00 +0100 |
commit | 75d0b8d7275c035f76db79e7cf7e802e061a9bee (patch) | |
tree | bf09eec163ca78b655c8ef60aaa5e57a8edd8ebc | |
parent | d09d35de46974b3ece2c469f54d898daaa28edf5 (diff) |
git-debrebase(1): wip
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
-rw-r--r-- | NOTES.git-debrebase | 21 | ||||
-rwxr-xr-x | git-debrebase | 8 | ||||
-rw-r--r-- | git-debrebase.1.pod | 213 |
3 files changed, 213 insertions, 29 deletions
diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase index 31c0c1c..79b6f2b 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 5b2312d..2520d52 100755 --- a/git-debrebase +++ b/git-debrebase @@ -21,15 +21,7 @@ # usages: # -# git-debrebase [<options>] new-upstream-v0 \ -# <new-version> [<orig-commitish> \ -# [<extra-orig-name> <extra-orig-commitish> ...] \ -# [<git-rebase options>...]] -# -# git-debrebase [<options> --] [<git-rebase options...>] # git-debrebase [<options>] analyse -# git-debrebase [<options>] breakwater # prints breakwater tip only -# git-debrebase [<options>] stitch [--prose=<for commit message>] # git-debrebase [<options>] launder-v0 # prints breakwater tip etc. # git-debrebase [<options>] downstream-rebase-launder-v0 # experimental # 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) |