[\fIdgit\-opts\fP] \fIaction\fR ...
.SH DESCRIPTION
.B dgit
-treats the Debian archive as a version control system, and
-bidirectionally gateways between the archive and git. The git view of
-the package can contain the usual upstream git history, and will be
-augmented by commits representing uploads done by other developers not
-using dgit. This git history is stored in a canonical location known
-as
-.B dgit-repos
-which lives outside the Debian archive (currently, on Alioth).
-
-The usual workflow is: 1. clone or fetch; 2. make and commit changes
-in git as desired; 3. run dgit build, dgit sbuild or dgit
-build-source, 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.
+allows you to treats 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.
+
+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.
+.SH OPERATIONS
.TP
\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
This is like running dgit push on build-host with build-dir as the
current directory; however, signing operations are done on the
invoking host. This allows you to do a push when the system which has
-the source code and the build outputs has no access to the key.
+the source code and the build outputs has no access to the key:
+
+1. Clone on build host (dgit clone)
+.br
+2. Edit code on build host (edit, git commit)
+.br
+3. Build package on build host (dgit build)
+.br
+4. Test package on build host or elsewhere (dpkg -i, test)
+.br
+5. Upload by invoking dgit rpush on host with your GPG key.
However, the build-host must be able to ssh to the dgit repos. If
this is not already the case, you must organise it separately, for
the invocation host. The build-host needs gnupg installed, with your
public key in its keyring (but not your private key, obviously).
.TP
+.B dgit setup-mergechangelogs
+Configures a git merge helper for the file
+.B debian/changelog
+which uses
+.BR dpkg-mergechangelogs .
+You can use this in any git repository, not just ones used with
+the other dgit operations.
+.TP
.B dgit quilt-fixup
`3.0 (quilt)' format source packages need changes representing not
only in-tree but also as patches in debian/patches. dgit quilt-fixup
.TP
.B dgit version
Prints version information and exits.
+.TP
+.BI "dgit clone-dgit-repos-server" " destdir"
+Tries to fetch a copy of the source code for the dgit-repos-server,
+as actually being used on the dgit git server, as a git tree.
.SH OPTIONS
.TP
-.BR --dry-run | -n
+.BR --dry-run " | " -n
Go through the motions, fetching all information needed, but do not
actually update the output(s). For push, dgit does
the required checks and leaves the new .dsc in a temporary file,
but does not sign, tag, push or upload.
.TP
-.BR --damp-run | -L
+.BR --damp-run " | " -L
Go through many more of the motions: do everything that doesn't
involve either signing things, or making changes on the public
servers.
rather than looking in debian/control or debian/changelog.
Valid with dgit fetch and dgit pull, only.
.TP
-.BR --clean=git | -wg
+.BR --clean=git " | " -wg
The source tree should be cleaned, before building a source package
with one of the build options, using
.BR "git clean -xdf" .
-This will delete all files which are not tracked by git.
+This will delete all files which are not tracked by git. Also, -wg
+causes dgit to pass
+.B -nc
+to dpkg-buildpackage, which prevents the package's own clean target
+from being run.
+
+--clean=git is useful when the package's clean target is troublesome;
+the downside is simply that git clean may delete files you forgot to
+git add. --clean=git can also avoid needing the build-dependencies.
.TP
-.BR --clean=none | -wn
+.BR --clean=git-ff " | " -wgf
+The source tree should be cleaned, before building a source package
+with one of the build options, using
+.BR "git clean -xdff" .
+This is like
+"git clean -xdf"
+but it also removes any subdirectories containing different git
+trees (which only unusual packages are likely to create).
+.TP
+.BR --clean=check " | " -wn
+Merely check that the tree is clean (does not contain uncommitted
+files), before building a source package.
+.TP
+.BR --clean=none " | " -wn
Do not clean the tree before building a source package. If there are
-files which are not in git, a subsequent dgit push will fail.
+files which are not in git, or if the build creates such files, a
+subsequent dgit push will fail.
.TP
-.BR --clean=dpkg-source | -wd
+.BR --clean=dpkg-source " | " -wd
Use dpkg-buildpackage to do the clean, so that the source package
is cleaned by dpkg-source running the package's clean target.
This is the default. It requires the package's build dependencies.
.TP
-.BR -N | --new
+.BR --clean=dpkg-source-d " | " -wdd
+Use
+.B dpkg-buildpackage -d
+to do the clean, so that the source package
+is cleaned by dpkg-source running the package's clean target.
+The build-dependencies are not checked (due to
+.BR -d ),
+which violates policy, but may work in practice.
+.TP
+.BR -N " | " --new
The package may be new in this suite. Without this, dgit will
refuse to push.
.TP
.B .pc
directory.)
.TP
-.BR --quilt=nocheck | --no-quilt-fixup
+.BR --quilt=nocheck " | " --no-quilt-fixup
Do not check whether up source format `3.0 (quilt)' metadata needs
fixing up. If you use this option and the metadata did in fact need
fixing up, dgit push will fail.
Specifies a single additional option to pass, eventually, to
dpkg-genchanges.
.TP
-.RI \fB--curl=\fR program |\fB--dput=\fR program |...
+.RI \fB--curl=\fR program " | \fB--dput=\fR" program " |..."
Specifies alternative programs to use instead of
.BR curl ,
.BR dput ,
.BR GIT_SSH )
is relevant.
.TP
-.RI \fB--curl:\fR option |\fB--dput:\fR option |...
+.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
Specifies a single additional option to pass to
.BR curl ,
.BR dput ,
Then run
.BR "dgit push"
to actually upload the result.
-.SH MODEL
-You may use any suitable git workflow with dgit, provided you
-satisfy dgit's requirements:
-
-dgit maintains a pseudo-remote called
-.BR dgit ,
-with one branch per suite. This remote cannot be used with
-plain git.
-
-The
-.B dgit-repos
-repository for each package contains one ref per suite named
-\fBrefs/dgit/\fR\fIsuite\fR. These should be pushed to only by
-dgit. They are fast forwarding. Each push on this branch
-corresponds to an upload (or attempted upload).
-
-However, it is perfectly fine to have other branches in dgit-repos;
-normally the dgit-repos repo for the package will be accessible via
-the remote name `origin'.
-
-dgit push will also (by default) make signed tags called
-.BI debian/ version
-and push them to dgit-repos, but nothing depends on these tags
-existing.
-
-dgit push can operate on any commit which is a descendant of the
-current dgit/suite tip in dgit-repos.
-
-Uploads made by dgit contain an additional field
-.B Dgit
-in the source package .dsc. (This is added by dgit push.)
-This specifies a commit (an ancestor of the dgit/suite
-branch) whose tree is identical to the unpacked source upload.
-
-Uploads not made by dgit are represented in git by commits which are
-synthesised by dgit. The tree of each such commit corresponds to the
-unpacked source; there is an origin commit with the contents, and a
-psuedo-merge from last known upload - that is, from the contents of
-the dgit/suite branch.
-
-dgit expects repos that it works with to have a
-.B dgit
-remote. This refers to the well-known dgit-repos location
-(currently, the dgit-repos project on Alioth). dgit fetch updates
-the remote tracking branch for dgit/suite.
-
-dgit does not (currently) represent the orig tarball(s) in git. The
-orig tarballs are downloaded (by dgit clone) into the parent
-directory, as with a traditional (non-gitish) dpkg-source workflow.
-You need to retain these tarballs in the parent directory for dgit
-build and dgit push.
-
-To a user looking at the archive, changes pushed using dgit look like
-changes made in an NMU: in a `3.0 (quilt)' package the delta from the
-previous upload is recorded in a new patch constructed by dpkg-source.
-.SH READ-ONLY DISTROS
-Distros which do not maintain a set of dgit history git repositories
-can still be used in a read-only mode with dgit. Currently Ubuntu
-is configured this way.
-.SH PACKAGE SOURCE FORMATS
-If you are not the maintainer, you do not need to worry about the
-source format of the package. You can just make changes as you like
-in git. If the package is a `3.0 (quilt)' package, the patch stack
-will usually not be represented in the git history.
-.SH FORMAT 3.0 (QUILT)
-For a format `3.0 (quilt)' source package, dgit may have to make a
-commit on your current branch to contain metadata used by quilt and
-dpkg-source.
-
-This is because `3.0 (quilt)' source format represents the patch stack
-as files in debian/patches/ actually inside the source tree. This
-means that, taking the whole tree (as seen by git or ls) (i)
-dpkg-source cannot represent certain trees, and (ii) packing up a tree
-in `3.0 (quilt)' and then unpacking it does not always yield the same
-tree.
-
-dgit will automatically work around this for you when building and
-pushing. The only thing you need to know is that dgit build, sbuild,
-etc., may make new commits on your HEAD. If you're not a quilt user
-this commit won't contain any changes to files you care about.
-
-You can explicitly request that dgit do just this fixup, by running
-dgit quilt-fixup.
-
-If you are a quilt user you need to know that dgit's git trees are
-`patches applied packaging branches' and do not contain the .pc
-directory (which is used by quilt to record which patches are
-applied). If you want to manipulate the patch stack you probably want
-to be looking at tools like git-dpm.
-.SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT
-This section is mainly of interest to maintainers who want to use dgit
-with their existing git history for the Debian package.
-
-Some developers like to have an extra-clean git tree which lacks files
-which are normally found in source tarballs and therefore in Debian
-source packages. For example, it is conventional to ship ./configure
-in the source tarball, but some people prefer not to have it present
-in the git view of their project.
-
-dgit requires that the source package unpacks to exactly the same
-files as are in the git commit on which dgit push operates. So if you
-just try to dgit push directly from one of these extra-clean git
-branches, it will fail.
-
-As the maintainer you therefore have the following options:
-.TP
-\(bu
-Persuade upstream that the source code in their git history and the
-source they ship as tarballs should be identical. Of course simply
-removing the files from the tarball may make the tarball hard for
-people to use.
-.IP
-One answer is to commit the (maybe autogenerated)
-files, perhaps with some simple automation to deal with conflicts and
-spurious changes. This has the advantage that someone who clones
-the git repository finds the program just as easy to build as someone
-who uses the tarball.
-.TP
-\(bu
-Have separate git branches which do contain the extra files, and after
-regenerating the extra files (whenever you would have to anyway),
-commit the result onto those branches.
-.TP
-\(bu
-Provide source packages which lack the files you don't want
-in git, and arrange for your package build to create them as needed.
-This may mean not using upstream source tarballs and makes the Debian
-source package less useful for people without Debian build
-infrastructure.
-.LP
-Of course it may also be that the differences are due to build system
-bugs, which cause unintended files to end up in the source package.
-dgit will notice this and complain. You may have to fix these bugs
-before you can unify your existing git history with dgit's.
.SH CONFIGURATION
dgit looks at the following git config keys to control its behaviour.
You may set them with git-config (either in system-global or per-tree
environment variables. Consult the documentaton for those programs
for details.
.SH BUGS
-We should be using some kind of vhost/vpath setup for the git repos on
-alioth, so that they can be moved later if and when this turns out to
-be a good idea.
-
-dgit push should perhaps do `git push origin', or something similar,
-by default.
-
-Debian does not have a working rmadison server, so to find out what
-version of a package is in the archive, or to canonicalise suite
-names, we ssh directly into the ftpmaster server and run psql there to
-access the database.
-
-The mechanism for checking for and creating per-package repos on
-alioth is a hideous bodge. One consequence is that dgit currently
-only works for people with push access.
-
-Debian Maintainers are currently not able to push, as there is not
-currently any mechanism for determining and honouring the archive's
-ideas about access control. Currently only DDs can push.
+Debian Maintainers are currently not able to push, as the project
+lacks a list of their ssh keys (!)
dgit's git representation of format `3.0 (quilt)' source packages does
not represent the patch stack as git commits. Currently the patch
The option parser requires values to be cuddled to the option name.
-dgit assumes knowledge of the archive database. (The information dgit
-needs is not currently available via any public online service with a
-well-defined interface, let alone a secure one.)
-
--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.
.SH SEE ALSO
+\fBdgit\fP(7),
\fBcurl\fP(1),
\fBdput\fP(1),
\fBdebsign\fP(1),