X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=9029f46e014b42cf147b66039d55949bb1f6a6ed;hp=35a09223fdeff8d7a025b15336c64c4f814ef256;hb=75d9628d62edf12c3b57c8d7d1ca614f5cc0fb17;hpb=eab588a83905122af678182876c2f800e4b6fa77 diff --git a/dgit.1 b/dgit.1 index 35a09223..9029f46e 100644 --- a/dgit.1 +++ b/dgit.1 @@ -27,20 +27,23 @@ 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). - -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. +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, common problems likely to arise with certain kinds of package, +etc. + +The usual workflow is: +.br +1. \fBdgit clone\fR or \fBfetch\fR; +.br +2. make, do dev tests, and commit changes in git as desired; +.br +3. build packages for upload, using e.g. \fBdgit sbuild\fR +.br +4. do pre-upload tests of the proposed upload; +.br +5. \fBdgit push\fR. +.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 @@ -167,7 +170,17 @@ Pushes the contents of the specified directory on a remote machine. This is like running dgit push on build-host with build-dir as the current directory; however, signing operations are done on the invoking host. This allows you to do a push when the system which has -the source code and the build outputs has no access to the key. +the source code and the build outputs has no access to the key: + +1. Clone on build host (dgit clone) +.br +2. Edit code on build host (edit, git commit) +.br +3. Build package on build host (dgit build) +.br +4. Test package on build host or elsewhere (dpkg -i, test) +.br +5. Upload by invoking dgit rpush on host with your GPG key. However, the build-host must be able to ssh to the dgit repos. If this is not already the case, you must organise it separately, for @@ -202,15 +215,19 @@ ask it to generate a single squashed patch instead. .TP .B dgit version Prints version information and exits. +.TP +.BI "dgit clone-dgit-repos-server" " destdir" +Tries to fetch a copy of the source code for the dgit-repos-server, +as actually being used on the dgit git server, as a git tree. .SH OPTIONS .TP -.BR --dry-run | -n +.BR --dry-run " | " -n Go through the motions, fetching all information needed, but do not actually update the output(s). For push, dgit does the required checks and leaves the new .dsc in a temporary file, but does not sign, tag, push or upload. .TP -.BR --damp-run | -L +.BR --damp-run " | " -L Go through many more of the motions: do everything that doesn't involve either signing things, or making changes on the public servers. @@ -230,22 +247,31 @@ Specifies that we should process source package rather than looking in debian/control or debian/changelog. Valid with dgit fetch and dgit pull, only. .TP -.BR --clean=git | -wg +.BR --clean=git " | " -wg The source tree should be cleaned, before building a source package with one of the build options, using .BR "git clean -xdf" . -This will delete all files which are not tracked by git. +This will delete all files which are not tracked by git. Also, -wg +causes dgit to pass +.B -nc +to dpkg-buildpackage, which prevents the package's own clean target +from being run. + +--clean=git is useful when the package's clean target is troublesome; +the downside is simply that git clean may delete files you forgot to +git add. .TP -.BR --clean=none | -wn +.BR --clean=none " | " -wn Do not clean the tree before building a source package. If there are -files which are not in git, a subsequent dgit push will fail. +files which are not in git, or if the build creates such files, a +subsequent dgit push will fail. .TP -.BR --clean=dpkg-source | -wd +.BR --clean=dpkg-source " | " -wd Use dpkg-buildpackage to do the clean, so that the source package is cleaned by dpkg-source running the package's clean target. This is the default. It requires the package's build dependencies. .TP -.BR -N | --new +.BR -N " | " --new The package may be new in this suite. Without this, dgit will refuse to push. .TP @@ -278,6 +304,11 @@ option after verifying that: none of the rejected-from-NEW (or never-accepted) versions in the git history of your current push, were rejected by ftpmaster for copyright or redistributability reasons. .TP +.BR --deliberately-fresh-repo +Declare that you are deliberately rewinding history and want to +throw away the existing repo. Not relevant when pushing to Debian, +as the Debian server will do this automatically when necessary. +.TP .BR --quilt=linear When fixing up source format `3.0 (quilt)' metadata, insist on generating a linear patch stack. If such a stack cannot be generated, @@ -302,7 +333,7 @@ because the dgit git tree does not have a .B .pc directory.) .TP -.BR --quilt=nocheck | --no-quilt-fixup +.BR --quilt=nocheck " | " --no-quilt-fixup Do not check whether up source format `3.0 (quilt)' metadata needs fixing up. If you use this option and the metadata did in fact need fixing up, dgit push will fail. @@ -337,7 +368,7 @@ Passed to dpkg-genchanges (eventually). Specifies a single additional option to pass, eventually, to dpkg-genchanges. .TP -.RI \fB--curl=\fR program |\fB--dput=\fR program |... +.RI \fB--curl=\fR program " | \fB--dput=\fR" program " |..." Specifies alternative programs to use instead of .BR curl , .BR dput , @@ -375,7 +406,7 @@ git to access dgit-repos, only git's idea of what ssh to use (eg, .BR GIT_SSH ) is relevant. .TP -.RI \fB--curl:\fR option |\fB--dput:\fR option |... +.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..." Specifies a single additional option to pass to .BR curl , .BR dput , @@ -525,140 +556,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. - -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 @@ -783,6 +680,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),