X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=git-debrebase.1.pod;h=e5b84a0b140b9fc6067d8c3649716707d9f9078e;hp=4d4c85a94992b7e83f68d5e8a20212176ee658c6;hb=f9de6d94951a129a0a90c688b15807da2d56e77a;hpb=ca261d36408442d8f3beeac12434af95810b1e32 diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index 4d4c85a9..e5b84a0b 100644 --- a/git-debrebase.1.pod +++ b/git-debrebase.1.pod @@ -15,7 +15,7 @@ Debian packages based on upstream source code. This is the command line reference. Please read the tutorial -L. +L. For background, theory of operation, and definitions see L. @@ -55,12 +55,18 @@ The options for git-rebase must either start with C<-i>, or be prececded by C<-->, to distinguish them from options for git-debrebase. +It is hazardous to use plain git-rebase on a git-debrebase branch, +because git-rebase has a tendency to start the rebase +too far back in history, +and then drop important commits. +See L + =item git-debrebase status -Analyise the current branch, -both in terms of its conents, +Analyses the current branch, +both in terms of its contents, and the refs which are relevant to git-debrebase, -and print a human-readable summary. +and prints a human-readable summary. Please do not attempt to parse the output; it may be reformatted or reorganised in the future. @@ -89,18 +95,31 @@ If the branch is already laundered and stitched, does nothing. =item git-debrebase prepush [--prose=] +If the branch is unstitched, +stitches it, +consuming ffq-prev. + +This is a good command to run before pushing to a git server. +You should consider using B instead, +because that launders the branch too. + =item git-debrebase stitch [--prose=] Stitches the branch, consuming ffq-prev. -This is a good command to run before pushing to a git server. If there is no ffq-prev, it is an error, unless --noop-ok. -You should consider using B instead, -because that launders the branch too. +You should consider using B or B instead. + +=item git-debrebase scrap + +Throws away all the work since the branch was last stitched. +This is done by rewinding you to ffq-prev. -=item git-debrebase new-upstream-v0 [...] +If you are in the middle of a git-rebase, will abort that too. + +=item git-debrebase new-upstream [...] Rebases the delta queue onto a new upstream version. In detail: @@ -135,6 +154,12 @@ If you git-rebase --abort, the whole new upstream operation is aborted, except for the laundering. + +may be a whole new Debian version, including revision, +or just the upstream part, +in which case -1 will be appended +to make the new Debian version. + The are, optionally, in order: =over @@ -142,7 +167,10 @@ The are, optionally, in order: =item The new upstream branch (or commit-ish). -Default is C. +The default is to look for one of these tags, in this order: +U vU upstream/U; +where U is the new upstream version. +(This is the same algorithm as L.) It is a snag if the upstream contains a debian/ directory; if forced to proceed, @@ -196,11 +224,6 @@ L, L, L and L 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. - =item git-debrebase make-patches [--quiet-would-amend] Generate patches in debian/patches/ @@ -226,23 +249,49 @@ If the patches implied by the current branch are not a simple superset of those already in debian/patches, make-patches will fail with exit status 7, and an error message. -(The message can be suppress with --quiet-would-amend.) +(The message can be suppressed with --quiet-would-amend.) +If the problem is simply that +the existing patches were not made by git-debrebase, +using dgit quilt-fixup instead should succeed. + +=item git-debrebase convert-from-unapplied [] =item git-debrebase convert-from-gbp [] -Cnnverts a gbp patches-unapplied branch -(not a gbp pq patch queue branch) -into a git-debrebase interchange branch. +Converts any of the following into a git-debrebase interchange branch: -This is done by generating a new anchor merge, -converting the quilt patches as a delta queue, +=over + +=item + +a gbp patches-unapplied branch (but not a gbp pq patch-queue branch) + +=item + +a patches-unapplied git packaging branch containing debian/patches, +as used with quilt + +=item + +a git branch for a package which has no Debian delta - +ie where upstream files are have not been modified in Debian, +so there are no patches + +=back + +(These two commands operate identically and are simply aliases.) + +The conversion is done by generating a new anchor merge, +converting any quilt patches as a delta queue, and dropping the patches from the tree. The upstream commit-ish should correspond to -the gbp upstream branch, if there is one. +the upstream branch or tag, if there is one. It is a snag if it is not an ancestor of HEAD, or if the history between the upstream and HEAD contains commits which make changes to upstream files. +If it is not specified, +the same algorithm is used as for git-debrebase new-upstream. It is also a snag if the specified upstream has a debian/ subdirectory. @@ -250,11 +299,20 @@ This check exists to detect certain likely user errors, but if this situation is true and expected, forcing it is fine. +git-debrebase will try to look for the dgit archive view +of the most recent release, +and if it finds it will make a pseduomerge so that +your new git-debrebase view is appropriately fast forward. + The result is a well-formed git-debrebase interchange branch. -The result is also fast-forward from the gbp branch. +The result is also fast-forward from the original branch. + +It is a snag if the new branch looks like it will have diverged, +just as for a laundering/unstitching call to git-debrebase; +See L, below. Note that it is dangerous not to know whether you are -dealing with a gbp patches-unappled branch containing quilt patches, +dealing with a (gbp) patches-unapplied branch containing quilt patches, or a git-debrebase interchange branch. At worst, using the wrong tool for the branch format might result in @@ -312,13 +370,93 @@ and any ffq-prev is deleted. This is provided mostly for the test suite and for unusual situations. -It should only be used with a care and +It should be used only with care and with a proper understanding of the underlying theory. Be sure to not accidentally treat the result as a git-debrebase branch, or you will drop all the patches! +=item git-debrebase convert-from-dgit-view [] [upstream] + +Converts any dgit-compatible git branch +corresponding to a (possibly hypothetical) 3.0 quilt dsc source package +into a git-debrebase-compatible branch. + +This operation should not be used +if the branch is already in git-debrebase form. +Normally git-debrebase will refuse to continue in this case +(or silently do nothing if the global --noop-ok option is used). + +Some representation of the original upstream source code will be needed. +If I is supplied, that must be a suitable upstream commit. +By default, +git-debrebase will look first for git tags (as for new-upstream), +and then for orig tarballs which it will ask dgit to process. + +The upstream source must be exactly right and +all the patches in debian/patches must be up to date. +Applying the patches from debian/patches to the upstream source +must result in exactly your HEAD. + +The output is laundered and stitched. +The resulting history is not particularly pretty, +especially if orig tarball(s) were imported +to produce a synthetic upstream commit. + +The available convert-options are as follows. +(These must come after convert-from-dgit-view.) + +=over + +=item --[no-]diagnose + +Print additional error messages to help diagnose +failure to find an appropriate upstream. +--no-diagnose is the default. + +=item --build-products-dir + +Directory to look in for orig tarballs. +The default is the git config option +dgit.default.build-products-dir +or failing that, "C<..>". +Passed on to dgit, if git-debrebase invokes dgit. + +=item --[no-]origs + +Whether to try to look for or use any orig tarballs. +--origs is the default. + +=item --[no-]tags + +Whether to try to look for or use any upstream git tags. +--tags is the default. + +=item --always-convert-anyway + +Perform the conversion operation, +producing unpleasant extra history, +even if the branch seems to be in git-debrebase form already. +This should not be done unless necessary, +and it should not be necessary. + +=back + +=item git-debrebase forget-was-ever-debrebase + +Deletes the ffq-prev and debrebase-last refs +associated with this branch, +that git-debrebase and dgit use to determine +whether this branch is managed by git-debrebase, +and what previous head may need to be stitched back in. + +This can be useful if you were just playing with git-debrebase, +and have used git-reset --hard to go back to a commit +before your experiments. + +Do not use this if you expect to run git-debrebase on the branch again. + =back =head1 OPTIONS @@ -342,7 +480,7 @@ Turns snag(s) with id into warnings. Some troublesome things which git-debrebase encounters are Bs. (The specific instances are discussed -in the text for the relvant operation.) +in the text for the relevant operation.) When a snag is detected, a message is printed to stderr containing the snag id @@ -383,10 +521,27 @@ it is a snag if is the anchor for the previous upstream version in git-debrebase new-upstream operations. +=item --dgit= + +Run , instead of dgit from PATH, +when invocation of dgit is necessary. +This is provided mostly for the benefit of the test suite. + =item -D Requests (more) debugging. May be repeated. +=item --experimntal-merge-resolution + +Enable experimental code for handling general merges +(see L). + +This option may generate lossage of various kinds, +including misleading error messages, +references to nonexistent documentation, and +you being handed an incomprehensible pile of +multidimensional merge wreckage. + =back =head1 UNSTITCHING AND LAUNDERING