chiark / gitweb /
Manpages: Break out dgit(7) from dgit(1).
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Wed, 1 Jul 2015 17:12:54 +0000 (18:12 +0100)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sat, 4 Jul 2015 18:24:46 +0000 (19:24 +0100)
Makefile
debian/changelog
dgit.1
dgit.7 [new file with mode: 0644]

index 3d9319a..cda167e 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -27,10 +27,12 @@ bindir=$(prefix)/bin
 mandir=$(prefix)/share/man
 perldir=$(prefix)/share/perl5
 man1dir=$(mandir)/man1
+man7dir=$(mandir)/man7
 infraexamplesdir=$(prefix)/share/doc/dgit-infrastructure/examples
 
 PROGRAMS=dgit
 MAN1PAGES=dgit.1
+MAN7PAGES=dgit.7
 PERLMODULES=Debian/Dgit.pm
 
 INFRA_PROGRAMS=dgit-repos-server dgit-ssh-dispatch \
@@ -44,12 +46,14 @@ all:
 install:       installdirs
        $(INSTALL_PROGRAM) $(PROGRAMS) $(DESTDIR)$(bindir)
        $(INSTALL_DATA) $(MAN1PAGES) $(DESTDIR)$(man1dir)
+       $(INSTALL_DATA) $(MAN7PAGES) $(DESTDIR)$(man7dir)
        set -e; for m in $(PERLMODULES); do \
                $(INSTALL_DATA) $$m $(DESTDIR)$(perldir)/$${m%/*}; \
        done
 
 installdirs:
-       $(INSTALL_DIR) $(DESTDIR)$(bindir) $(DESTDIR)$(man1dir) \
+       $(INSTALL_DIR) $(DESTDIR)$(bindir) \
+               $(DESTDIR)$(man1dir) $(DESTDIR)$(man7dir) \
                $(addprefix $(DESTDIR)$(perldir)/, $(dir $(PERLMODULES)))
 
 install-infra: installdirs-infra
index 5724e02..5e685f1 100644 (file)
@@ -86,6 +86,8 @@ dgit (0.23~) unstable; urgency=low
     dpkg-buildpackage, suppressing calls to the package's clean target.
     Also, expand the documentation in this area slightly.  Closes:#768590.
 
+  * Manpages: Break out dgit(7) from dgit(1).
+
  --
 
 dgit (0.22.1) unstable; urgency=high
diff --git a/dgit.1 b/dgit.1
index f183e8e..9ebc7b1 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -27,14 +27,9 @@ dgit \- git integration with the Debian archive
 [\fIdgit\-opts\fP] \fIaction\fR ...
 .SH DESCRIPTION
 .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
-as
-.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.
-.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.
-
-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.
-.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.
-.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 `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
-tree.
-
-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.
-.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.
 .SH CONFIGURATION
 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.
 .SH SEE ALSO
+\fBdgit\fP(7),
 \fBcurl\fP(1),
 \fBdput\fP(1),
 \fBdebsign\fP(1),
diff --git a/dgit.7 b/dgit.7
new file mode 100644 (file)
index 0000000..a3ea84c
--- /dev/null
+++ b/dgit.7
@@ -0,0 +1,153 @@
+.TH dgit 7 "" "Debian Project" "dgit"
+.SH NAME
+dgit \- principles of operation
+.SH SUMMARY
+.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
+as
+.B dgit-repos
+which lives outside the Debian archive (currently, on Alioth).
+.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.
+
+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.
+.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.
+.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 `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
+tree.
+
+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.
+.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.
+.SH SEE ALSO
+\fBdgit\fP(1).