X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=ef5236a4ce70c3aaadd637ba87ba948069ec51e8;hp=2233d95941fa34f9ec4ac9e9a4a77c25f77cda34;hb=10d3925a7aebac484e09aa2d636ceae1cbffeb10;hpb=4d5ef701bf95a1c60a5cc1b9f5c4d771ac49375a

diff --git a/dgit.1 b/dgit.1
index 2233d959..ef5236a4 100644
--- a/dgit.1
+++ b/dgit.1
@@ -17,7 +17,7 @@ dgit \- git integration with the Debian archive
 [\fIbuild\-opts\fp]
 .br
 .B dgit
-[\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP]
+[\fIdgit\-opts\fP] \fBpush\fP|\fBpush-source\fP [\fIdgit\-opts\fP]
 [\fIsuite\fP]
 .br
 .B dgit
@@ -30,15 +30,20 @@ dgit \- git integration with the Debian archive
 .B dgit
 allows you to treat the Debian archive as if it were a git
 repository.
+Conversely,
+it allows Debian to publish the source of its packages
+as git branches, in a format which is directly useable
+by ordinary people.
 
 This is the command line reference.
 Please read the tutorial(s):
 .TS
 lb l.
-dgit-user(7)	for users: editing, building and sharing packages
-dgit-nmu-simple(7)	for DDs: doing a straightforward NMU
+dgit-user(7)	for users: edit, build and share packages
+dgit-nmu-simple(7)	for DDs: do a straightforward NMU
 dgit-maint-native(7)	for maintainers of Debian-native packages
-dgit-maint-merge(7)	for maintainers who want a pure git workflow
+dgit-maint-debrebase(7)	for maintainers: a pure-git rebasish workflow
+dgit-maint-merge(7)	for maintainers: a pure-git merging workflow
 dgit-maint-gbp(7)	for maintainers already using git-buildpackage
 dgit-sponsorship(7)	for sponsors and sponsored contributors
 .TE
@@ -113,6 +118,10 @@ that the generated source package corresponds to the relevant git
 commit.
 
 Tagging, signing and actually uploading should be left to dgit push.
+
+dgit's build operations access the the network,
+to get the -v option right.
+See -v, below.
 .TP
 \fBdgit build-source\fR ...
 Builds the source package, and a changes file for a prospective
@@ -123,7 +132,8 @@ The output is left in
 and
 .IR package \fB_\fR version \fB_source.changes\fR.
 
-Tagging, signing and actually uploading should be left to dgit push.
+Tagging, signing and actually uploading should be left to dgit
+push-source, or dgit push.
 .TP
 .B dgit clean
 Cleans the current working tree (according to the --clean= option in
@@ -180,6 +190,19 @@ archive.
 dgit push always uses the package, suite and version specified in the
 debian/changelog and the .dsc, which must agree.  If the command line
 specifies a suite then that must match too.
+
+With \fB-C\fR, performs a dgit push, additionally ensuring that no
+binary packages are uploaded.
+
+When used on a git-debrebase branch,
+dgit calls git-debrebase
+to prepare the branch
+for source package upload and push.
+.TP
+\fBdgit push-source\fR [\fIsuite\fP]
+Without \fB-C\fR, builds a source package and dgit pushes it.  Saying
+\fBdgit push-source\fR is like saying "update the source code in the
+archive to match my git HEAD, and let the autobuilders do the rest."
 .TP
 \fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR]
 Pushes the contents of the specified directory on a remote machine.
@@ -249,10 +272,19 @@ For why, see
 in
 .BR dgit(7) .
 
+If there is an existing macro attribute line
+.B [attr]dgit-defuse-attrs
+in .git/info/attributes,
+but it is insufficient,
+because it was made by an earlier version of dgit
+and git has since introduced new transforming attributes,
+modifies the macro to disable the newer transformations.
+
 (If there is already a macro attribute line
 .B [attr]dgit-defuse-attrs
 in .git/info/attributes
-(whatever its effects),
+which does what dgit requires
+(whatever files it effects),
 this operation does nothing further.
 This fact can be used to defeat or partially defeat
 dgit setup-gitattributes
@@ -273,6 +305,15 @@ new quilt patch.  dgit cannot convert nontrivial merges, or certain
 other kinds of more exotic history.  If dgit can't find a suitable
 linearisation of your history, by default it will fail, but you can
 ask it to generate a single squashed patch instead.
+
+When used with a git-debrebase branch,
+dgit will ask git-debrebase to prepare patches.
+However,
+dgit can make patches in some situations where git-debrebase fails,
+so dgit quilt-fixup can be useful in its own right.
+To always use dgit's own patch generator
+instead of git-debrebase make-patches,
+pass --git-debrebase=true to dgit.
 .TP
 \fBdgit import-dsc\fR [\fIsub-options\fR] \fI../path/to/.dsc\fR [\fB+\fR|\fB..\fR]branch
 Import a Debian-format source package,
@@ -343,6 +384,13 @@ as actually being used on the dgit git server, as a git tree.
 Prints the url used by dgit clone-dgit-repos-server.
 This is hopefully suitable for use as a git remote url.
 It may not be useable in a browser.
+.TP
+.BI "dgit print-dpkg-source-ignores"
+Prints the -i and -I arguments which must be passed to dpkg-souce
+to cause it to exclude exactly the .git diredcory
+and nothing else.
+The separate arguments are unquoted, separated by spaces,
+and do not contain spaces.
 .SH OPTIONS
 .TP
 .BR --dry-run " | " -n
@@ -725,6 +773,9 @@ The default is not to remove, but
 .B \-\-no-rm-old-changes
 can be used to override a previous \-\-rm-old-changes
 or the .rm-old-changes configuration setting.
+
+Note that \fBdgit push-source\fR will always find the right .changes,
+regardless of this option.
 .TP
 .BI --build-products-dir= directory
 Specifies where to find the built files to be uploaded.
@@ -802,6 +853,7 @@ Specifies a single additional option to pass to
 .BR sbuild ,
 .BR ssh ,
 .BR dgit ,
+.BR git-debrebase ,
 .BR apt-get ,
 .BR apt-cache ,
 .BR gbp-pq ,
@@ -849,6 +901,7 @@ Specifies alternative programs to use instead of
 .BR gpg ,
 .BR ssh ,
 .BR dgit ,
+.BR git-debrebase ,
 .BR apt-get ,
 .BR apt-cache ,
 .BR git ,