Manpages: Other clarifications and improvements.

diff --git a/debian/changelog b/debian/changelog
index 5e685f1c2d26127ac17e936c8fa5f1f906879f79..853e3eafbf825da57c4bd3002f71bcab8cdae23d 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -87,6 +87,7 @@ dgit (0.23~) unstable; urgency=low
     Also, expand the documentation in this area slightly.  Closes:#768590.
 
   * Manpages: Break out dgit(7) from dgit(1).
+  * Manpages: Other clarifications and improvements.
 
  --
 

diff --git a/dgit.1 b/dgit.1
index 9ebc7b1694070a5b1387705a6d1a6886912101db..e4da7f23b4883b200102994152cf34ac9fba80f9 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -29,13 +29,23 @@ dgit \- git integration with the Debian archive
 .B dgit
 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.
+model, common problems likely to arise with certain kinds of package,
+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
-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.
+The usual workflow is:
+.br
+1.     dgit clone or fetch
+.br
+2.     make, dev test and commit changes in git as desired
+.br
+3.     run dgit build, dgit sbuild or 
+dgit build-source, or generate the source and binary packages for upload
+some other way
+.br
+4.     do pre-upload tests of the proposed upload
+.br
+5.     dgit push.
+.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

diff --git a/dgit.7 b/dgit.7
index a3ea84cc479823966eaf910e6ce109117bfd4c8e..6c74f40d46b4ed789b234e155f17dec0cf38ba54 100644 (file)
--- a/dgit.7
+++ b/dgit.7
@@ -53,9 +53,9 @@ 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.
+remote.  This refers to the well-known dgit-repos location (on a
+dedicated Debian VM).  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
@@ -149,5 +149,27 @@ 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.
+.LP
+.SH PROBLEMS WITH PACKAGE CLEAN TARGETS ETC.
+A related problem is unexpected behaviour by a package's
+.B clean
+target.
+If a package's rules
+remove or modify files which are distributed in the package,
+or simply forgets to remove certain files,
+dgit will complain that the tree is dirty.
+.LP
+The solution is to use
+.BR "dgit -wg" " aka " "--clean=git" ,
+which instructs dgit to use git clean instead of the package's
+build target,
+along with perhaps
+.B git reset --hard
+before each build.
+.LP
+This is 100% reliable, but has the downside
+that if you forget to git add or to commit, and then use
+.BR "dgit -wg" " or " "git reset --hard" ,
+your changes may be lost.
 .SH SEE ALSO
 \fBdgit\fP(1).