path: root/dgit.1
diff options
authorIan Jackson <>2015-07-01 18:12:54 +0100
committerIan Jackson <>2015-07-04 19:24:46 +0100
commitcfd5e47a4a0d485c2cbb93cccad40e8086de52ea (patch)
tree4fd93d63ac7c3df2428b77dab6a6d0bf13ab227f /dgit.1
parent54bd461a80ec31613c02831bd7c889ea9f91ed65 (diff)
Manpages: Break out dgit(7) from dgit(1).
Diffstat (limited to 'dgit.1')
1 files changed, 4 insertions, 146 deletions
diff --git a/dgit.1 b/dgit.1
index f183e8e..9ebc7b1 100644
--- a/dgit.1
+++ b/dgit.1
@@ -27,14 +27,9 @@ dgit \- git integration with the Debian archive
[\fIdgit\-opts\fP] \fIaction\fR ...
.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
-.B dgit-repos
-which lives outside the Debian archive (currently, on Alioth).
+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 etc.
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
@@ -553,144 +548,6 @@ between what's in the archive and what you intend to upload.
Then run
.BR "dgit push"
to actually upload the result.
-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.
-.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
-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.
-dgit repositories could be cloned with standard (git) methods. The
-only exception is that for sourcefull builds / uploads the orig
-tarball(s) need to be present in the parent directory.
-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.
-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.
-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.
-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
-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
-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.
-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:
-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.
-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.
-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.
-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
-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.
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
@@ -815,6 +672,7 @@ well-defined interface, let alone a secure one.)
fetches may result in subsequent actions being different. Doing a
non-dry-run dgit fetch first will help.