Convert to defvalopt: --existing-package

[dgit.git] / dgit.7

diff --git a/dgit.7 b/dgit.7
index a3ea84cc479823966eaf910e6ce109117bfd4c8e..a9886563eae90110f0f560bb2f73ed17fed3adf7 100644 (file)
--- a/dgit.7
+++ b/dgit.7
@@ -10,7 +10,7 @@ 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
 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).
+which lives on a dedicated git server.

 .SH MODEL
 You may use any suitable git workflow with dgit, provided you
 satisfy dgit's requirements:
 .SH MODEL
 You may use any suitable git workflow with dgit, provided you
 satisfy dgit's requirements:


@@ -31,10 +31,10 @@ 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'.
 
 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
+dgit push will also make signed tags called

 .BI debian/ version
 .BI debian/ version

-and push them to dgit-repos, but nothing depends on these tags
-existing.
+(a la DEP-14) and push them to dgit-repos.  These are used at the
+server to authenticate pushes.

 
 dgit push can operate on any commit which is a descendant of the
 current dgit/suite tip in dgit-repos.
 
 dgit push can operate on any commit which is a descendant of the
 current dgit/suite tip in dgit-repos.


@@ -53,9 +53,9 @@ the dgit/suite branch.
 
 dgit expects repos that it works with to have a
 .B dgit
 
 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
 
 dgit does not (currently) represent the orig tarball(s) in git.  The
 orig tarballs are downloaded (by dgit clone) into the parent


@@ -64,7 +64,7 @@ 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
 build and dgit push.
 
 dgit repositories could be cloned with standard (git) methods. The

-only exception is that for sourcefull builds / uploads the orig
+only exception is that for sourceful 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
 tarball(s) need to be present in the parent directory.
 
 To a user looking at the archive, changes pushed using dgit look like


@@ -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.
 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).
 .SH SEE ALSO
 \fBdgit\fP(1).