documentation style: "appropriate configuration" as a mass noun

[dgit.git] / git-debrebase.1.pod

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 4d4c85a94992b7e83f68d5e8a20212176ee658c6..e5b84a0b140b9fc6067d8c3649716707d9f9078e 100644 (file)
--- 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
 
 This is the command line reference.
 Please read the tutorial

-L<dgit-maint-debrebase(5)>.
+L<dgit-maint-debrebase(7)>.

 For background, theory of operation,
 and definitions see L<git-debrebase(5)>.
 
 For background, theory of operation,
 and definitions see L<git-debrebase(5)>.
 


@@ -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.
 
 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<git-debrebase(5)/ILLEGAL OPERATIONS>
+

 =item git-debrebase status
 
 =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 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.
 
 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=<for commit message>]
 
 
 =item git-debrebase prepush [--prose=<for commit message>]
 

+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<conclude> instead,
+because that launders the branch too.
+

 =item git-debrebase stitch [--prose=<for commit message>]
 
 Stitches the branch,
 consuming ffq-prev.
 =item git-debrebase stitch [--prose=<for commit message>]
 
 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.
 
 
 If there is no ffq-prev, it is an error, unless --noop-ok.
 

-You should consider using B<conclude> instead,
-because that launders the branch too.
+You should consider using B<prepush> or B<conclude> 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 <new-version> [<upstream-details>...]
+If you are in the middle of a git-rebase, will abort that too.
+
+=item git-debrebase new-upstream <new-version> [<upstream-details>...]

 
 Rebases the delta queue
 onto a new upstream version.  In detail:
 
 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.
 
 the whole new upstream operation is aborted,
 except for the laundering.
 

+<new-version>
+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 <upstream-details> are, optionally, in order:
 
 =over
 The <upstream-details> are, optionally, in order:
 
 =over


@@ -142,7 +167,10 @@ The <upstream-details> are, optionally, in order:
 =item <upstream-commit-ish>
 
 The new upstream branch (or commit-ish).
 =item <upstream-commit-ish>
 
 The new upstream branch (or commit-ish).

-Default is C<upstream>.
+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<git-deborig(1)>.)

 
 It is a snag if the upstream contains a debian/ directory;
 if forced to proceed,
 
 It is a snag if the upstream contains a debian/ directory;
 if forced to proceed,


@@ -196,11 +224,6 @@ L<git-deborig(1)>,
 L<git-archive(1)>, L<dgit(1)> and
 L<gbp-import-orig(1)> may be able to help.
 
 L<git-archive(1)>, L<dgit(1)> and
 L<gbp-import-orig(1)> 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<new-upstream>.
-

 =item git-debrebase make-patches [--quiet-would-amend]
 
 Generate patches in debian/patches/
 =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.
 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 [<upstream-commit-ish>]

 
 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
 
 
 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
 

-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
 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.
 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.
 
 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.
 
 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 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</Establish the current branch's ffq-prev>, below.

 
 Note that it is dangerous not to know whether you are
 
 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
 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.
 
 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!
 
 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 [<convert-options>] [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<upstream> 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
 =back
 
 =head1 OPTIONS


@@ -342,7 +480,7 @@ Turns snag(s) with id <snag-id> into warnings.
 Some troublesome things which git-debrebase encounters
 are B<snag>s.
 (The specific instances are discussed
 Some troublesome things which git-debrebase encounters
 are B<snag>s.
 (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
 
 When a snag is detected,
 a message is printed to stderr containing the snag id


@@ -383,10 +521,27 @@ it is a snag if <commit-ish> is the anchor
 for the previous upstream version in
 git-debrebase new-upstream operations.
 
 for the previous upstream version in
 git-debrebase new-upstream operations.
 

+=item --dgit=<program>
+
+Run <program>, 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 -D
 
 Requests (more) debugging.  May be repeated.
 

+=item --experimntal-merge-resolution
+
+Enable experimental code for handling general merges
+(see L<git-debrebase(5)/General merges>).
+
+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
 =back
 
 =head1 UNSTITCHING AND LAUNDERING