From cfd5e47a4a0d485c2cbb93cccad40e8086de52ea Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Wed, 1 Jul 2015 18:12:54 +0100 Subject: Manpages: Break out dgit(7) from dgit(1). --- Makefile | 6 ++- debian/changelog | 2 + dgit.1 | 150 ++--------------------------------------------------- dgit.7 | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 164 insertions(+), 147 deletions(-) create mode 100644 dgit.7 diff --git a/Makefile b/Makefile index 3d9319a..cda167e 100644 --- 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 diff --git a/debian/changelog b/debian/changelog index 5724e02..5e685f1 100644 --- a/debian/changelog +++ b/debian/changelog @@ -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 --- 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 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). -- cgit v1.2.3