X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=git-debrebase.1.pod;h=1156825c8a92831c55507a115b92413ace15fe16;hp=ed33b79c1f8d59cb7c3b08983515ed177da7212e;hb=3e9a357df187605ef886381ef66407f1904fc9d1;hpb=fd532a0a35cad3d4753d4f0a2549af2a8b268cc9 diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index ed33b79c..1156825c 100644 --- a/git-debrebase.1.pod +++ b/git-debrebase.1.pod @@ -15,14 +15,13 @@ 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 of the terms used here, -see L. +and definitions see L. -If no operation is specified, -git-debrebase launders the branch and rebases the Debian delta queue. -See below. +You should read this manpage in cojnunction with +L, +which defines many important terms used here. =head1 PRINCIPAL OPERATIONS @@ -30,10 +29,13 @@ See below. =item git-debrebase [-- ] +=item git-debrebase [-i ] + Unstitches and launders the branch. (See L below.) -Then optionally edits the Debian delta queue, +Then, if any git-rebase options were supplied, +edits the Debian delta queue, using git-rebase, by running git rebase @@ -49,25 +51,85 @@ If you abort the git-rebase, the branch will still have been laundered, but everything in the rebase will be undone. +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. +Soo L + +=item git-debrebase status + +Analyses the current branch, +both in terms of its contents, +and the refs which are relevant to git-debrebase, +and prints a human-readable summary. + +Please do not attempt to parse the output; +it may be reformatted or reorganised in the future. +Instead, +use one of the L +described below. + +=item git-debrebase conclude + +Finishes a git-debrebase session, +tidying up the branch and making it fast forward again. + +Specifically: if the branch is unstitched, +launders and restitches it, +making a new pseudomerge. +Otherwise, it is an error, +unless --noop-ok. + +=item git-debrebase quick + +Unconditionally launders and restitches the branch, +consuming any ffq-prev +and making a new pseudomerge. + +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=] -Stitch the branch, +Stitches the branch, consuming ffq-prev. If there is no ffq-prev, it is an error, unless --noop-ok. -It is a problem if the branch is not laundered. +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: Firstly, checks that the proposed rebase seems to make sense: -It is a problem unless the new upstream(s) +It is a snag 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, +And, in the case of a multi-piece upstream +(a multi-component upstream, in dpkg-source terminology), if the pieces are not in the same order, with the same names. If all seems well, unstitches and launders the branch. @@ -90,26 +152,34 @@ 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. +except for the laundering. + + +may be 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 -=item +=item -The new upstream branch (or commitish). -Default is C. +The new upstream branch (or commit-ish). +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 problem if the upstream contains a debian/ directory; +It is a snag 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 +=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, @@ -118,7 +188,7 @@ together, and then use the result as the combined new upstream. For each , -the tree of the +the tree of the becomes the subdirectory in the combined new upstream (supplanting any subdirectory that might be there in @@ -150,14 +220,41 @@ 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. - -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 convert-from-gbp [] +L, +L, L and +L may be able to help. + +=item git-debrebase make-patches [--quiet-would-amend] + +Generate patches in debian/patches/ +representing the changes made to upstream files. + +It is not normally necessary to run this command explicitly. +When uploading to Debian, +dgit and git-debrebase +will cooperate to regenerate patches as necessary. +When working with pure git remotes, +the patches are not needed. + +Normally git-debrebase make-patches will +require a laundered branch. +(A laundered branch does not contain any patches.) +But if there are already some patches made by +git-debrebase make-patches, +and all that has happened is that more +changes to upstream files have been committed, +running it again can add the missing patches. + +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.) +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-gbp [] Cnnverts a gbp patches-unapplied branch (not a gbp pq patch queue branch) @@ -167,23 +264,34 @@ This is done by generating a new anchor merge, converting the quilt patches as a delta queue, and dropping the patches from the tree. -The upstream commitish should correspond to -the gbp upstream branch. -It is a problem if it is not an ancestor of HEAD, +The upstream commit-ish should correspond to +the gbp upstream branch, 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 problem if the specified upstream +It is also a snag if the specified upstream has a debian/ subdirectory. 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. +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 @@ -248,43 +356,127 @@ 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 This section documents the general options to git-debrebase -(ie, the ones which follow git-debrebase). +(ie, the ones which immediately follow +git-debrebase +or +git debrebase +on the command line). Individual operations may have their own options which are docuented under each operation. =over -=item -f +=item -f -Turns problems with id into warnings. +Turns snag(s) with id into warnings. Some troublesome things which git-debrebase encounters -are Bs. +are Bs. (The specific instances are discussed -in the text for the relvant operation.) +in the text for the relevant operation.) -When a problem is detected, -a message is printed to stderr containing the problem id -(in the form C<-f>), +When a snag is detected, +a message is printed to stderr containing the snag id +(in the form C<-f>), along with some prose. -If problems are detected, git-debrebase does not continue, -unless the relevant -f is specified, +If snags are detected, git-debrebase does not continue, +unless the relevant -f is specified, or --force is specified. =item --force -Turns all problems into warnings. -See the -f option. +Turns all snags into warnings. +See the -f option. Do not invoke git-debrebase --force in scripts and aliases; -instead, specify the particular -f for expected problems. +instead, specify the particular -f for expected snags. =item --noop-ok @@ -295,21 +487,43 @@ because there is nothing to do. The specific instances are discussed in the text for the relvant operation. -=item --anchor= +=item --anchor= + +Treats as an anchor. +This overrides the usual logic which automatically classifies +commits as anchors, pseudomerges, delta queue commits, etc. + +It also disables some coherency checks +which depend on metadata extracted from its commit message, +so +it is a snag if is the anchor +for the previous upstream version in +git-debrebase new-upstream operations. -Treats as an anchor, -regardless of what it's actually like. +=item --dgit= -(It is a problem for -git-debrebase new-upstream operations -if is the previous anchor to be used, -because treating an arbitrary commit as an anchor -means forgoing upstream coherency checks.) +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 branch structures that +require the use of this same option by other people. +Also you may experience lossage of various kinds, +including false error messages, +references to nonexistent documentation, +being handed an incomprehensible pile of +multidimensional merge wreckage, +and/or possible mangling of your package's source code. + =back =head1 UNSTITCHING AND LAUNDERING @@ -319,30 +533,49 @@ In detail this means: =head2 Establish the current branch's ffq-prev -If it is not yet recorded, +If ffq-prev is not yet recorded, git-debrebase checks that the current branch is ahead of relevant remote tracking branches. +The relevant branches depend on +the current branch (and its +git configuration) +and are as follows: -The remote tracking branches checked by default are -obtained from the git config. -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. +=over + +=item + +The branch that git would merge from +(remote..merge, remote..remote); + +=item + +The branch git would push to, if different +(remote..pushRemote etc.); + +=item + +For local dgit suite branches, +the corresponding tracking remote; -git-debrebase checks the branch that git would merge from -(remote..merge, remote..remote) -and the branch git would push to -(remote..pushRemote etc.). -For local dgit suite branches -it checks the corresponding tracking remote. -If you are on C, it checks remotes/dgit/dgit/sid. -The resulting ref names to check are filtered through +=item + +If you are on C, +remotes/dgit/dgit/sid. + +=back + +The apparently relevant 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. +In each case it is a snag 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. + If these checks pass, or are forced, git-debrebse then records the current tip as ffq-prev. @@ -369,4 +602,5 @@ The result is the laundered branch. git-debrebase(1), dgit-maint-rebase(7), -dgit(1) +dgit(1), +gitglossary(7)