Subject: request for manpage TOOL-dgit(7) Severity: wishlist Hi. In this mail you'll find: 1. introduction 2. description of dgit's model as it might concern TOOL 3. suggested structure and for a new manpage 4. some quirks and caveats 5. references 1. Introduction You may have heard of dgit, which is a tool for sharing a canonical git representation of Debian packages, and particularly, packages in the Debian archive. dgit is not a competitor to TOOL. Indeed, dgit is intended to be complementary to existing Debian git packaging tools. I think that TOOL can probably be used together with dgit, and it would be good to help users get TOOL and dgit to work well together. It may also be that TOOL and/or dgit should get some new feature(s) or operation(s) to work better together. Because I don't understand TOOL very well I'm not sure of the details. I'm hoping that you would like to write, or help me write, a manpage TOOL-dgit(7) (which I could cross-reference from dgit(1)). Please let me know whether you think this is a good idea and whether you're able to help. 2. dgit's purpose and model dgit mainly replaces `sign and dupload', and `debcheckout'. For each package there is a fast-forwarding git branch (one per suite) on a central dgit server. The tree contents (in git terminology) of that branch correspond precisely to the contents of the corresponding source package. (In more detail: dgit records a `patches-applied packaging branch without .pc directory'.) The commit graph structure of the dgit branch is primarily up to the maintainer. The only requirements imposed by dgit are that: successive uploads are fast forwards; and, that NMUs are represented by linear commit(s) on the tip of that branch. When a maintainer is using dgit with TOOL, it is TOOL which determines the commit structure, subject to these constraints. 3. Suggsted manpage skeleton Here is a suggestion for what information is needed and how it might be structured. Sorry that I don't have the knowledge to write something more complete. (Below, XXX notes and comments in [ ] are directed to you, the maintainer of TOOL.) If new TOOL or dgit need improvement, this ought to become obvious when trying to write the manpage. NAME TOOL-dgit(7) - use of dgit with TOOL SYNOPSIS dgit can be used to publish and share the git history that TOOL works with. This dgit integration guide is for the TOOL-using maintainer. PUSHING (UPLOADING) WITH DGIT TOOL's XXX [which branch?] branch is directly suitable for use with dgit push. After finalising development with TOOL MAKE-THE-RIGHT-THING-TO-UPLOAD the binary and source package(s) should be built with dgit sbuild or dgit build Then dgit push can be used. See dgit(1) for details. USING *TOOL* WITH DGIT FOR THE FIRST TIME dgit requires that each upload is a fast forward from the previous one (even if the dgit view of the previous upload is a commit synthesised by dgit). So when switching to using TOOL with dgit, it is necessary to stitch the previous dgit history into the git branch: 1. Run dgit fetch (or dgit fetch ) to get the dgit view of the current archive state. 2. Check (for example by looking at debian/changelog in your own branch, and comparing it to debian/changelog in dgit/sid) that the version you are about to upload really is descended from the last upload. 3. Run git merge -s ours dgit/sid to generate a `merge' commit which contains exactly your code but which is also a descendant of the dgit history. When you next come to run TOOL you will need to XXX [will TOOL work on such history or does user need to do something special?] HANDLING AN NMU An NMU should appear in the git history as some additional, linear, commits, descended from the commit of your last upload. To integrate these changes into your own XXX [ git history, branch, whatever? ] you must XXX [ do what? ] NMUs made with dgit will contain whatever git history the NMUer pushed, which should be reasonably clean. (If not, complain to the NMUer.) SEE ALSO dgit(1), dgit(7), ... NMUers who 4. Quirks The dgit view of an NMU may contain commits withh a mixture of debian/ and upstream changes. The intermediate states in the dgit git branch, between the last maintainer upload and the nmu, may not necessarily have the corresponding updates to debian/patches. NMUs not made with dgit will appear as a merge of 1. a root commit describing the .dsc that was uploaded, and 2. a merge to stitch it into the suite branch. dgit's source packages and git trees contain .gitignore. Current default behaviour for dpkg-buildpackage -I is to remove .gitignore. This is not correct for dgit because the .dsc and git tree must be identical. The main effect is just that it is best to use of dgit's build wrapper operations to build the package, since dgit knows the right -I options. 5. References dgit(1) manpage http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.1 dgit(7) manpage http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.1 dgit 1.0 release announcement https://lists.debian.org/debian-devel-announce/2015/07/msg00003.html