wip new arrangements for clean etc.

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 9b3ffb2cb517756bd4304b2f396fc9bf5fade3d6..652ffbb62bcca12b382947e453b3d815aec07d98 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -5,7 +5,7 @@ dgit \- git integration with the Debian archive
 .SH SYNOPSIS
 .B dgit
 [\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP]
-\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir]
+\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
 .br
 .B dgit
 [\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP]
@@ -37,7 +37,7 @@ in git as desired; 3. run dgit build or dgit sbuild, or generate the
 source and binary packages for upload some other way; 4. do
 pre-upload tests of the proposed upload; 5. run dgit push.
 .TP
-\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir]
+\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
 Consults the archive and dgit-repos to construct the git view of
 history for
 .I package
@@ -65,7 +65,7 @@ belongs.
 Consults the archive and git-repos to update the git view of
 history for a specific suite (and downloads any necessary orig
 tarballs), and updates the remote tracking branch
-.BR remotes/dgit/ \fIsuite\fR.
+.BR remotes/dgit/dgit/ \fIsuite\fR.
 If the current branch is
 .BI dgit/ suite
 then dgit fetch defaults to
@@ -76,7 +76,7 @@ there.
 \fBdgit pull\fR [\fIsuite\fP]
 Does dgit fetch, and then merges the new head of the remote tracking
 branch
-.BI remotes/dgit/ suite
+.BI remotes/dgit/dgit/ suite
 into the current branch.
 .TP
 \fBdgit build\fR ...
@@ -140,7 +140,7 @@ and then dgit push.  You can use whatever gitish techniques you like
 to construct the commit to push; the only requirement is that it is a
 descendant of the state of the archive, as provided by dgit in the
 remote tracking branch
-.BR remotes/dgit/ \fIsuite\fR.
+.BR remotes/dgit/dgit/ \fIsuite\fR.
 
 If you are lucky the other uploaders have also used dgit and
 integrated the other relevant git history; if not you can fetch it
@@ -175,13 +175,13 @@ to start using dgit.  First, do
 .B dgit fetch
 (or clone) to obtain a git history representation of what's in the
 archive and record it in the
-.BI remotes/dgit/ suite
+.BI remotes/dgit/dgit/ suite
 tracking branch.  Then somehow, using your other git history
 plus appropriate diffs and cherry picks from the dgit remote tracking
 branch, construct a git commit whose tree corresponds to the tree to use for the
 next upload.  If that commit-to-be-uploaded is not a descendant of the
 dig remote tracking branch, check it out and say
-.BR "git merge -s ours remotes/dgit/" \fIsuite\fR;
+.BR "git merge -s ours remotes/dgit/dgit/" \fIsuite\fR;
 that tells git that we are deliberately throwing away any differences
 between what's in the archive and what you intend to upload.
 Then run
@@ -321,6 +321,27 @@ or
 .BR mergechanges .
 Can be repeated as necessary.
 .TP
+.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
+Specifies that the suite to be operated on is part of distro
+.IR distro .
+This overrides the default value found from the git config option
+.BR dgit-suite. \fIsuite\fR .distro .
+The only effect is that other configuration variables (used
+for accessing the archive and dgit-repos) used are
+.BR dgit-distro. \fIdistro\fR .* .
+
+If your suite is part of a distro that dgit already knows about, you
+can use this option to make dgit work even if your dgit doesn't know
+about the suite.  For example, specifying
+.B -ddebian
+will work when the suite is an unknown suite in the Debian archive.
+
+To define a new distro it is necessary to define methods and URLs
+for fetching (and, for dgit push, altering) a variety of information both
+in the archive and in dgit-repos.  How to do this is not yet
+documented, and currently the arrangements are unpleasant.  See
+BUGS.
+.TP
 .BI -C changesfile
 Specifies the .changes file which is to be uploaded.  By default
 dgit push looks for single .changes file in the parent directory whose
@@ -390,6 +411,8 @@ on the dgit command line.
 .TP
 .BI dgit-distro. distro .ssh
 .TP
+.BI dgit-distro. distro .keyid
+.TP
 .BR dgit.default. *
 for each
 .BR dgit-distro. \fIdistro\fR . *