+'\" t
.TH dgit 1 "" "Debian Project" "dgit"
.SH NAME
dgit \- git integration with the Debian archive
.SH DESCRIPTION
.B dgit
allows you to treat the Debian archive as if it were a git
-repository. See \fBdgit\fP(7) for detailed information about the data
-model, common problems likely to arise with certain kinds of package,
-etc.
+repository.
-The usual workflow is:
-.br
-1. \fBdgit clone\fR or \fBfetch\fR;
-.br
-2. make, do dev tests, and commit changes in git as desired;
-.br
-3. build packages for upload, using e.g. \fBdgit sbuild\fR
-.br
-4. do pre-upload tests of the proposed upload;
-.br
-5. \fBdgit push\fR.
+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-maint-native(7) for maintainers of Debian-native packages
+dgit-maint-merge(7) for maintainers who want a pure git workflow
+dgit-maint-gbp(7) for maintainers already using git-buildpackage
+dgit-sponsorship(7) for sponsors and sponsored contributors
+.TE
+.LP
+See \fBdgit(7)\fP for detailed information about the data
+model,
+common problems likely to arise with certain kinds of package,
+etc.
.SH OPERATIONS
.TP
\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
.I suite
belongs.
+.I suite
+may be
+.IR mainsuite \fB,\fR subsuite ...
+in which case dgit will synthesize a view giving the most
+recent version in any of the specified suites.
+(The subsuites do not need to have the package.)
+If a subsuite starts with
+.B -
+then mainsuite is prepended.
+Each of the suite names will be individually canonicalised
+to calculate the canonical branch names to use.
+When using this facility, it is important to always specify the
+same suites in the same order:
+dgit will not be make a coherent fast-forwarding history
+view otherwise.
+
For your convenience, the
.B vcs-git
remote will be set up from the package's Vcs-Git field, if there is
.IR suite ;
otherwise it parses debian/changelog and uses the suite specified
there.
+
+suite may be
+.IR mainsuite \fB,\fR subsuite ...
+as for clone.
.TP
\fBdgit pull\fR [\fIsuite\fP]
Does dgit fetch, and then merges the new head of the remote tracking
linearisation of your history, by default it will fail, but you can
ask it to generate a single squashed patch instead.
.TP
+\fBdgit import-dsc\fR [\fIsub-options\fR] \fI../path/to/.dsc\fR [\fB+\fR|\fB..\fR]branch
+Import a Debian-format source package,
+specified by its .dsc,
+into git,
+the way dgit fetch would do.
+
+This does about half the work of dgit fetch:
+it will convert the .dsc into a new, orphan git branch.
+Since dgit has no access to a corresponding source package archive
+or knowledge of the history
+it does not consider whether this version is newer
+than any previous import
+or corresponding git branches;
+and it therefore does not
+make a pseudomerge to bind the import
+into any existing git history.
+
+There is only only sub-option:
+
+.B --require-valid-signature
+causes dgit to insist that the signature on the .dsc is valid
+(using the same criteria as dpkg-source -x).
+Otherwise, dgit tries to verify the signature but
+the outcome is reported only as messages to stderr.
+
+If
+.I branch
+is prefixed with
+.B +
+then if it already exists, it will be simply ovewritten,
+no matter its existing contents.
+If
+.I branch
+is prefixed with
+.B ..
+then if it already exists
+and dgit actually imports the dsc
+(rather than simply reading the git commit out of the Dgit field),
+dgit will make a pseudomerge
+so that the result is necessarily fast forward
+from the existing branch.
+Otherwise, if branch already exists,
+dgit will stop with an error message.
+
+If
+.I branch
+does not start with refs/, refs/heads/ is prepended.
+The specified branch is unconditionally updated.
+
+If the specified .dsc contains a Dgit field,
+dgit will simply make a branch of that commit.
+If you cannot manage to find that commit anywhere,
+consider --force-import-dsc-with-dgit-field.
+.TP
.B dgit version
Prints version information and exits.
.TP
implying a split between the dgit view and the
maintainer view, the pseudo-merge will appear only in the dgit view.)
.TP
+.BR --delayed =\fIdays\fR
+Upload to a DELAYED queue.
+
+.B WARNING:
+If the maintainer responds by cancelling
+your upload from the queue,
+and does not make an upload of their own,
+this will not rewind the git branch on the dgit git server.
+Other dgit users will then see your push
+(with a warning message from dgit)
+even though the maintainer wanted to abolish it.
+Such users might unwittingly reintroduce your changes.
+
+If this situation arises,
+someone should make a suitable dgit push
+to update the contents of dgit-repos
+to a version without the controversial changes.
+.TP
+.BR --dgit-view-save= \fIbranch\fR|\fIref\fR
+Specifies that when a split view quilt mode is in operation,
+and dgit calculates
+(or looks up in its cache)
+a dgit view corresponding to your HEAD,
+the dgit view will be left in
+.IR ref .
+The specified ref is unconditionally overwritten,
+so don't specify a branch you want to keep.
+
+This option is effective only with the following operations:
+quilt-fixup; push; all builds.
+And it is only effective with
+--[quilt=]gbp,
+--[quilt=]dpm,
+--quilt=unpatched.
+
+If ref does not start with refs/
+it is taken to to be a branch -
+i.e. refs/heads/ is prepended.
+.TP
.BI --deliberately- something
Declare that you are deliberately doing
.IR something .
.BR sbuild ,
.BR ssh ,
.BR dgit ,
+.BR apt-get ,
+.BR apt-cache ,
.BR gbp-pq ,
.BR gbp-build ,
or
.BR gpg ,
.BR ssh ,
.BR dgit ,
+.BR apt-get ,
+.BR apt-cache ,
.BR git ,
.BR gbp-pq ,
.BR gbp-build ,
in case dgit is confused.
(They might also be useful for testing error cases.)
.TP
+.B --import-dsc-with-dgit-field
+Tell dgit import-dsc to treat a .dsc with a Dgit field
+like one without it.
+The result is a fresh import,
+discarding the git history
+that the person who pushed that .dsc was working with.
+.TP
.B --force-unrepresentable
Carry on even if
dgit thinks that your git tree contains changes
when running gbp pq import
when importing a package from a .dsc.
See Debian bug #841867.
-.SH WORKFLOW - SIMPLE
-It is always possible with dgit to clone or fetch a package, make
-changes in git (using git-commit) on the suite branch
-.RB ( "git checkout dgit/" \fIsuite\fR)
-and then dgit push. You can use whatever gitish techniques you like
-to construct the commits to push;
-the only requirement is that what you push is a
-descendant of the state of the archive, as provided by dgit in the
-remote tracking branch
-.BR remotes/dgit/dgit/ \fIsuite\fR.
-
-If you are using dgit to do an NMU (in Debian),
-and don't know about the
-maintainers' preferred packaging workflows, you should make your
-changes as a linear series of (logicially separated) commits on top of
-what's already in the archive.
-
-If you are lucky the other uploaders have also used dgit and
-integrated the other relevant git history; if not you can fetch it
-into your tree and cherry-pick etc. as you wish.
-.SH WORKFLOW - INTEGRATING BETWEEN DGIT AND OTHER GIT HISTORY
-If you are the maintainer of a package dealing with uploads made
-without dgit, you will probably want to merge the synthetic commits
-(made by dgit to represent the uploads) into your git history.
-Normally you can just merge the dgit branch into your own master, or
-indeed if you do your work on the dgit local suite branch
-.BI dgit/ suite
-you can just use dgit pull.
-
-However the first time dgit is used it will generate a new origin
-commit from the archive which won't be linked into the rest of your
-git history. You will need to merge this.
-
-If last upload was in fact made with git, you should usually proceed
-as follows: identify the commit which was actually used to build the
-package. (Hopefully you have a tag for this.) Check out the dgit
-branch
-.RB ( "git checkout dgit/" \fIsuite\fR)
-and merge that other commit
-.RB ( "git merge debian/" \fIversion\fR).
-Hopefully this merge will be trivial because the two trees should
-be very similar. The resulting branch head can be merged into your
-working branches
-.RB ( "git checkout master && git merge dgit/" \fIsuite\fR).
-
-If last upload was not made with git, a different approach is required
-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/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.
-
-between what's in the archive and what you intend to upload.
-Then run
-.BR "dgit push"
-to actually upload the result.
-
-If the commit-to-be-uploaded is not a descendant of the
-dgit remote tracking branch, you will need to pass
-.B --overwrite
-to dgit.
.SH CONFIGURATION
dgit can be configured via the git config system.
You may set keys with git-config (either in system-global or per-tree
Specifies the distro for a suite. dgit keys off the suite name (which
appears in changelogs etc.), and uses that to determine the distro
which is involved. The config used is thereafter that for the distro.
+
+.I suite
+may be a glob pattern.
.TP
.BI dgit.default.distro " distro"
The default distro for an unknown suite.
environment variables. Consult the documentaton for those programs
for details.
.SH BUGS
-dgit's git representation of format `3.0 (quilt)' source packages does
-not represent the patch stack as git commits. Currently the patch
-series representation cannot round trip between git and the archive.
-Ideally dgit would represent a quilty package with an origin commit of
-some kind followed by the patch stack as a series of commits followed
-by a pseudo-merge (to make the branch fast-forwarding). This would
-also mean a new `dgit rebase-prep' command or some such to turn such a
-fast-forwarding branch back into a rebasing patch stack, and a `force'
-option to dgit push (perhaps enabled automatically by a note left by
-rebase-prep) which will make the required pseudo-merge.
-
-If the dgit push fails halfway through, it should be restartable and
-idempotent. However this is not true for the git tag operation.
-Also, it would be good to check that the proposed signing key is
-available before starting work.
+There should be
+a `dgit rebase-prep' command or some such to turn a
+fast-forwarding branch containing pseudo-merges
+back into a rebasing patch stack.
+It might have to leave a note
+for a future dgit push.
-dgit's handling of .orig.tar.gz is not very sophisticated. Ideally
-the .orig.tar.gz could be transported via the git repo as git tags.
-Doing this is made more complicated by the possibility of a `3.0
-(quilt)' package with multiple .orig tarballs.
+If the dgit push fails halfway through,
+it is not necessarily restartable and
+idempotent.
+It would be good to check that the proposed signing key is
+available before starting work.
-dgit's build functions, and dgit push, should not make any changes to
+dgit's build functions, and dgit push, may make changes to
your current HEAD. Sadly this is necessary for packages in the `3.0
(quilt)' source format. This is ultimately due to what I consider
design problems in quilt and dpkg-source.
-There should be an option which arranges for the `3.0 (quilt)'
-autocommit(s) to not appear on your HEAD, but instead only in the
-remote tracking suite branch.
-
--dry-run does not always work properly, as not doing some of the git
fetches may result in subsequent actions being different. Doing a
non-dry-run dgit fetch first will help.
+--damp-run is likely to work much better.
.SH SEE ALSO
\fBdgit\fP(7),
-\fBdgit-maint-merge\fP(7),
+\fBdgit-*\fP(7),
\fBcurl\fP(1),
\fBdput\fP(1),
\fBdebsign\fP(1),
~ianmdlvl / dgit.git / blobdiff