1 Subject: request for manpage TOOL-dgit(7)
5 Hi. In this mail you'll find:
8 2. description of dgit's model as it might concern TOOL
9 3. suggested structure and for a new manpage
10 4. some quirks and caveats
16 You may have heard of dgit, which is a tool for sharing a canonical
17 git representation of Debian packages, and particularly, packages in
20 dgit is not a competitor to TOOL. Indeed, dgit is intended to be
21 complementary to existing Debian git packaging tools. I think that
22 TOOL can probably be used together with dgit, and it would be good to
23 help users get TOOL and dgit to work well together.
25 It may also be that TOOL and/or dgit should get some new feature(s) or
26 operation(s) to work better together.
28 Because I don't understand TOOL very well I'm not sure of the details.
29 I'm hoping that you would like to write, or help me write, a manpage
30 TOOL-dgit(7) (which I could cross-reference from dgit(1)).
32 Please let me know whether you think this is a good idea and whether
36 2. dgit's purpose and model
38 dgit mainly replaces `sign and dupload', and `debcheckout'. For each
39 package there is a fast-forwarding git branch (one per suite) on a
42 The tree contents (in git terminology) of that branch correspond
43 precisely to the contents of the corresponding source package. (In
44 more detail: dgit records a `patches-applied packaging branch without
47 The commit graph structure of the dgit branch is primarily up to the
48 maintainer. The only requirements imposed by dgit are that:
49 successive uploads are fast forwards; and, that NMUs are represented
50 by linear commit(s) on the tip of that branch.
52 When a maintainer is using dgit with TOOL, it is TOOL which determines
53 the commit structure, subject to these constraints.
56 3. Suggsted manpage skeleton
58 Here is a suggestion for what information is needed and how it might
59 be structured. Sorry that I don't have the knowledge to write
60 something more complete. (Below, XXX notes and comments in [ ] are
61 directed to you, the maintainer of TOOL.)
63 If new TOOL or dgit need improvement, this ought to become obvious
64 when trying to write the manpage.
68 TOOL-dgit(7) - use of dgit with TOOL
72 dgit can be used to publish and share the git history that TOOL
73 works with. This dgit integration guide is for the TOOL-using
76 PUSHING (UPLOADING) WITH DGIT
78 TOOL's XXX [which branch?] branch is directly suitable for use
81 After finalising development with
82 TOOL MAKE-THE-RIGHT-THING-TO-UPLOAD
83 the binary and source package(s) should be built with
88 Then dgit push can be used. See dgit(1) for details.
90 USING *TOOL* WITH DGIT FOR THE FIRST TIME
92 dgit requires that each upload is a fast forward from the previous
93 one (even if the dgit view of the previous upload is a commit
96 So when switching to using TOOL with dgit, it is necessary to
97 stitch the previous dgit history into the git branch:
99 1. Run dgit fetch (or dgit fetch <suite>) to get the dgit view
100 of the current archive state.
102 2. Check (for example by looking at debian/changelog in your own
103 branch, and comparing it to debian/changelog in dgit/sid) that
104 the version you are about to upload really is descended from
108 git merge -s ours dgit/sid
109 to generate a `merge' commit which contains exactly your code
110 but which is also a descendant of the dgit history.
112 When you next come to run TOOL you will need to XXX [will TOOL
113 work on such history or does user need to do something special?]
117 An NMU should appear in the git history as some additional,
118 linear, commits, descended from the commit of your last upload.
120 To integrate these changes into your own XXX [ git history,
121 branch, whatever? ] you must XXX [ do what? ]
123 NMUs made with dgit will contain whatever git history the NMUer
124 pushed, which should be reasonably clean. (If not, complain to
128 dgit(1), dgit(7), ...
135 The dgit view of an NMU may contain commits withh a mixture of
136 debian/ and upstream changes. The intermediate states in the dgit
137 git branch, between the last maintainer upload and the nmu, may
138 not necessarily have the corresponding updates to
141 NMUs not made with dgit will appear as a merge of 1. a root commit
142 describing the .dsc that was uploaded, and 2. a merge to stitch it
143 into the suite branch.
145 dgit's source packages and git trees contain .gitignore. Current
146 default behaviour for dpkg-buildpackage -I is to remove
147 .gitignore. This is not correct for dgit because the .dsc and git
148 tree must be identical. The main effect is just that it is best
149 to use of dgit's build wrapper operations to build the package,
150 since dgit knows the right -I options.
156 http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.1
159 http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/dgit.1
161 dgit 1.0 release announcement
162 https://lists.debian.org/debian-devel-announce/2015/07/msg00003.html