(which might not be faithful to dgit's invariants)
or previous non-Dgit uploads
(which would not provide a very rich history).
+
+git represents only file executability.
+git does not represent empty directories,
+or any leaf objects other than plain files and symlinks.
+The behaviour of Debian source package formats
+on objects with unusual permissions is complicated.
+Some pathological Debian source packages will no longer build
+if empty directories are pruned
+(or if other things not reproduced by git are changed).
+Such sources cannot be worked with properly in git,
+and therefore not with dgit either.
.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
git has features which can automatically transform files
as they are being copied between the working tree
and the git history.
+The attributes can be specified in the source tree itself,
+in
+.BR .gitattributes .
See \fBgitattributes\fP(5).
These transformations are context-sensitive
the dgit git history contains the actual contents of the package.
(When dgit is manipulating a .dsc,
it does so in a private area,
-where the transforming gitattributes are defused (disabled),
+where the transforming gitattributes are defused,
to achieve this.)
-If transforming gitattributes used,
+If transforming gitattributes are used,
they can cause trouble,
because the working tree files can differ from
the git revision history
(and therefore from the source packages).
+dgit warns if it finds a .gitattributes file
+(in a package being fetched or imported),
+unless the transforming gitattributes have been defused.
-So dgit clone
+dgit clone
and dgit setup-new-tree
disable transforming gitattributes
by default,
-by creating a .git/info/attributes.
-When fetching or importing sources
-dgit warns if it finds .gitattributes file
-and the transforming gitattributes have not been defused
-(e.g. in the case of a tree not made with dgit clone).
-
+by creating a suitable .git/info/attributes.
See
.B dgit setup-new-tree
and
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 FILE EXECUTABILITY
+Debian source package formats
+do not always faithfully reproduce
+changes to executability.
+But dgit insists that the result of dgit clone is identical
+(as far as git can represent - see Limitations, above)
+to the result of dpkg-source -x.
+
+So files that are executable in your git tree
+must be executable in the result of dpkg-source -x
+(but often aren't).
+If a package has such troublesome files,
+they have to be non-executable in dgit-compatible git branches.
.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
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.
+Simply commiting to source files
+(whether in debian/ or not, but not to patches)
+will result in a branch that dgit quilt-fixup can linearise.
+Other kinds of changes,
+including editing patches or merging,
+cannot be handled this way.
+
You can explicitly request that dgit do just this fixup, by running
dgit quilt-fixup.
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.
+
+.SS quilt fixup error messages
+When dgit's quilt fixup fails, it prints messages like this:
+
+.EX
+dgit: base trees orig=5531f03d8456b702eab6 o+d/p=135338e9cc253cc85f84
+dgit: quilt differences: src: == orig ## gitignores: == orig ##
+dgit: quilt differences: HEAD ## o+d/p HEAD ## o+d/p
+starting quiltify (multiple patches, linear mode)
+
+dgit: error: quilt fixup cannot be linear. Stopped at:
+dgit: 696c9bd5..84ae8f96: changed debian/patches/test-gitignore
+.EE
+
+.TP
+.B orig
+is an import of the .orig tarballs dgit found,
+with the debian/ directory from your HEAD substituted.
+This is a git tree object, not a commit:
+you can pass its hash to git-diff but not git-log.
+
+.TP
+.B o+d/p
+is another tree object,
+which is the same as orig
+but with the patches from debian/patches applied.
+
+.TP
+.B HEAD
+is of course your own git HEAD.
+
+.TP
+.B quilt differences
+shows whether each of the these trees differs from the others
+(i) in upstream files excluding .gitignore files;
+(ii) in upstream .gitignore files.
+.B ==
+indicates equality;
+.B ##
+indicates inequality.
+.LP
+dgit quilt-fixup --quilt=linear walks commits
+backwards from your HEAD
+trying to construct a linear set of additional patches,
+starting at the end.
+It hopes to eventually find an ancestor
+whose tree is identical to o+d/p in all upstream files.
+
+In the error message,
+696c9bd5..84ae8f96
+is the first commit child-parent edge
+which cannot be sensibly be
+either ignored, or turned into a patch in debian/patches.
+In this example, this is because
+it itself changes files in debian/patches,
+indicating that something unusual is going on
+and that continuing is not safe.
+But you might also see other kinds of troublesome commit or edge.
+
+Your appropriate response depends on the cause and the context.
+If you have been freely merging your git branch
+and do not need need a pretty linear patch queue,
+you can use
+.B --quilt=smash
+(or use the
+.B 1.0
+or
+.B single-debian-patch
+source formats; see
+.BR dpkg-source(1) .)
+If you want a pretty linear series,
+and this message is unexpected,
+it can mean that you have unwittingly committed changes
+that are not representable by dpkg-source (such as some mode changes).
+Or maybe you just forgot a necessary
+.B --quilt=
+option.
.SH SPLIT VIEW QUILT MODE
When working with git branches intended
for use with the `3.0 (quilt)' source format