-.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.
-
-If you are the maintainer of a non-native package, you currently have
-two sensible options:
-
-Firstly, you can regard your git history as primary, and the archive
-as an export format. For example, you could maintain topic branches
-in git and a fast-forwarding release branch; or you could do your work
-directly in a merging way on the
-.BI dgit/ suite
-branches. If you do this you should probably use a `1.0' format
-source package if you can. In the archive, the delta between upstream
-will be represented in the single Debian patch.
-
-Secondly, you can use `3.0 (quilt)', and regard your quiltish patch
-stack in the archive as primary. You will have to use other tools
-besides dgit to import and export this patch stack. But see below:
-.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 (i) the `3.0 (quilt)' source format 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. Instead,
-dpkg-source insists on the trees having extra quilty metadata and
-patch files in the debian/ and .pc/ directories, which dpkg-source
-sometimes modifies.
-
-dgit will automatically work around this braindamage for you when
-building and pushing. The only thing you need to know is that dgit
-build, sbuild, etc., may make a new commit 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.
-
-We recommend against the use of `3.0 (quilt)'.
-.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.