diff options
author | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2015-07-01 18:12:54 +0100 |
---|---|---|
committer | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2015-07-04 19:24:46 +0100 |
commit | cfd5e47a4a0d485c2cbb93cccad40e8086de52ea (patch) | |
tree | 4fd93d63ac7c3df2428b77dab6a6d0bf13ab227f /dgit.1 | |
parent | 54bd461a80ec31613c02831bd7c889ea9f91ed65 (diff) |
Manpages: Break out dgit(7) from dgit(1).
Diffstat (limited to 'dgit.1')
-rw-r--r-- | dgit.1 | 150 |
1 files changed, 4 insertions, 146 deletions
@@ -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), |