git-debrebase: make-patched: Provide --quiet-would-amend

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

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 7e126246bfd9e534d2998591539956fc24025099..4d4c85a94992b7e83f68d5e8a20212176ee658c6 100644 (file)
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -29,10 +29,13 @@ which defines many important terms used here.
 
 =item git-debrebase [-- <git-rebase options...>]
 
 
 =item git-debrebase [-- <git-rebase options...>]
 

+=item git-debrebase [-i <further git-rebase options...>]
+

 Unstitches and launders the branch.
 (See L</UNSTITCHING AND LAUNDERING> below.)
 
 Unstitches and launders the branch.
 (See L</UNSTITCHING AND LAUNDERING> 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 <git-rebase options> <breakwater-tip>
 using git-rebase, by running
 
     git rebase <git-rebase options> <breakwater-tip>


@@ -48,14 +51,54 @@ If you abort the git-rebase,
 the branch will still have been laundered,
 but everything in the rebase will be undone.
 
 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.
+
+=item git-debrebase status
+
+Analyise the current branch,
+both in terms of its conents,
+and the refs which are relevant to git-debrebase,
+and print 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<UNDERLYING AND SUPPLEMENTARY OPERATIONS>
+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=<for commit message>]
+

 =item git-debrebase stitch [--prose=<for commit message>]
 
 =item git-debrebase stitch [--prose=<for commit message>]
 

-Stitch the branch,
+Stitches the branch,

 consuming ffq-prev.
 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.
 

-It is a problem if the branch is not laundered.
+You should consider using B<conclude> instead,
+because that launders the branch too.

 
 =item git-debrebase new-upstream-v0 <new-version> [<upstream-details>...]
 
 
 =item git-debrebase new-upstream-v0 <new-version> [<upstream-details>...]
 


@@ -63,7 +106,7 @@ Rebases the delta queue
 onto a new upstream version.  In detail:
 
 Firstly, checks that the proposed rebase seems to make sense:
 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
 are fast forward from the previous upstream(s)
 as found in the current breakwater anchor.
 And, in the case of a multi-piece upstream


@@ -101,7 +144,7 @@ The <upstream-details> are, optionally, in order:
 The new upstream branch (or commit-ish).
 Default is C<upstream>.
 
 The new upstream branch (or commit-ish).
 Default is C<upstream>.
 

-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.
 if forced to proceed,
 git-debrebase will disregard the upstream's debian/ and
 take (only) the packaging from the current breakwater.


@@ -158,6 +201,33 @@ that its command line syntax is optimal.
 We may want to introduce an incompatible replacement syntax
 under the name C<new-upstream>.
 
 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/
+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.)
+

 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
 
 Cnnverts a gbp patches-unapplied branch
 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
 
 Cnnverts a gbp patches-unapplied branch


@@ -170,11 +240,11 @@ and dropping the patches from the tree.
 
 The upstream commit-ish should correspond to
 the gbp upstream branch, if there is one.
 
 The upstream commit-ish should correspond to
 the gbp upstream branch, if there is one.

-It is a problem if it is not an ancestor of HEAD,
+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.
 
 or if the history between the upstream and HEAD
 contains commits which make changes to upstream files.
 

-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,
 has a debian/ subdirectory.
 This check exists to detect certain likely user errors,
 but if this situation is true and expected,


@@ -265,31 +335,31 @@ docuented under each operation.
 
 =over
 
 
 =over
 

-=item -f<problem-id>
+=item -f<snag-id>

 
 

-Turns problems with id <problem-id> into warnings.
+Turns snag(s) with id <snag-id> into warnings.

 
 Some troublesome things which git-debrebase encounters
 
 Some troublesome things which git-debrebase encounters

-are B<problem>s.
+are B<snag>s.

 (The specific instances are discussed
 in the text for the relvant operation.)
 
 (The specific instances are discussed
 in the text for the relvant operation.)
 

-When a problem is detected,
-a message is printed to stderr containing the problem id
-(in the form C<-f<problem-idE<gt>>),
+When a snag is detected,
+a message is printed to stderr containing the snag id
+(in the form C<-f<snag-idE<gt>>),

 along with some prose.
 
 along with some prose.
 

-If problems are detected, git-debrebase does not continue,
-unless the relevant -f<problem-id> is specified,
+If snags are detected, git-debrebase does not continue,
+unless the relevant -f<snag-id> is specified,

 or --force is specified.
 
 =item --force
 
 or --force is specified.
 
 =item --force
 

-Turns all problems into warnings.
-See the -f<problem-id> option.
+Turns all snags into warnings.
+See the -f<snag-id> option.

 
 Do not invoke git-debrebase --force in scripts and aliases;
 
 Do not invoke git-debrebase --force in scripts and aliases;

-instead, specify the particular -f<problem-id> for expected problems.
+instead, specify the particular -f<snag-id> for expected snags.

 
 =item --noop-ok
 
 
 =item --noop-ok
 


@@ -303,12 +373,13 @@ in the text for the relvant operation.
 =item --anchor=<commit-ish>
 
 Treats <commit-ish> as an anchor.
 =item --anchor=<commit-ish>
 
 Treats <commit-ish> as an anchor.

-This overrides the usual automatic commit classification logic.
+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 also disables some coherency checks
 which depend on metadata extracted from its commit message,
 so

-it is a problem if <commit-ish> is the anchor
+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.
 


@@ -362,7 +433,7 @@ branch.<branch>.ffq-ffrefs,
 which is a semicolon-separated list of glob patterns,
 each optionally preceded by !; first match wins.
 
 which is a semicolon-separated list of glob patterns,
 each optionally preceded by !; first match wins.
 

-In each case it is a problem if
+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:
 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: