X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=git-debrebase.1.pod;h=639b07d2e6af4feb4b17a0b9720d6e08a222a774;hp=a964180d7890491398ac93116edb3f528d09a476;hb=HEAD;hpb=8521ee9155c24772c1cc0c3c8b6fa00d7d742e2d diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index a964180d..639b07d2 100644 --- a/git-debrebase.1.pod +++ b/git-debrebase.1.pod @@ -1,25 +1,39 @@ =head1 NAME -git-debrebase - delta queue rebase tool for Debian packaging +git-debrebase - tool to maintain series of Debian changes to upstream source =head1 SYNOPSYS git-debrebase [] [-- ] git-debrebase [] [ -=head1 INTRODUCTION +=head1 QUICK REFERENCE -git-debrebase is a tool for representing in git, -and manpulating, -Debian packages based on upstream source code. +These are most of the commands you will regularly need: + + git debrebase -i # edit the patch queue + git debrebase conclude && git push # push to eg salsa + git debrebase conclude && dgit push-source # source-only upload + git debrebase new-upstream 1.2.3-1 [-i] # uses tag, eg "v1.2.3" + dpkg-buildpackage -uc -b # get test debs, at any time + +To add patches, or edit the packaging, just make git commits. +Ignore anything that may appear in debian/patches. +Avoid using "git pull" and "git merge" without "--ff-only". + +git-debrebase has a special branch format, so see +"CONVERTING AN EXISTING PACKAGE" in L. + +=head1 GUIDE TO DOCUMENTATION This is the command line reference. -Please read the tutorial -L. +There is also a detailed workflow tutorial at +L +(on which the above "QUICK REFERENCE" is based). For background, theory of operation, and definitions see L. -You should read this manpage in cojnunction with +You should read this manpage in conjunction with L, which defines many important terms used here. @@ -59,7 +73,7 @@ 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 +See L =item git-debrebase status @@ -115,11 +129,12 @@ 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. +This is done by resetting you to ffq-prev +and discarding all working tree changes. If you are in the middle of a git-rebase, will abort that too. -=item git-debrebase new-upstream [...] +=item git-debrebase new-upstream [...] [--|-i ] Rebases the delta queue onto a new upstream version. In detail: @@ -155,7 +170,7 @@ the whole new upstream operation is aborted, except for the laundering. -may be whole new Debian version, including revision, +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. @@ -249,14 +264,16 @@ 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 any of the following into a git-debrebase interchange branch: +Converts any of the following into a git-debrebase interchange branch: =over @@ -277,6 +294,8 @@ 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. @@ -366,7 +385,7 @@ 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 only be used with care and with a proper understanding of the underlying theory. Be sure to not accidentally treat the result as @@ -527,7 +546,7 @@ This is provided mostly for the benefit of the test suite. Requests (more) debugging. May be repeated. -=item --experimntal-merge-resolution +=item --experimental-merge-resolution Enable experimental code for handling general merges (see L). @@ -615,6 +634,6 @@ The result is the laundered branch. =head1 SEE ALSO git-debrebase(1), -dgit-maint-rebase(7), +dgit-maint-debrebase(7), dgit(1), gitglossary(7)